assert.3: improved description

PATCH In review Nikos Mavrogiannopoulos 2 participants 4 messages Jun 2, 2016 – Jun 3, 2016 3 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Nikos Mavrogiannopoulos

author

2016-06-02 09:07 UTC #0 lore raw

PATCH 1/1 assert.3: improved description

Removed text referring to text not being helpful to users. Provide the error text instead to allow the reader to determine whether it is helpful. Recommend against using NDEBUG for programs to excibit deterministic behavior. Moved description ahead of recommendations.

Signed-off-by Nikos Mavrogiannopoulos <[email protected]>

---
man3/assert.3 | 29 +++++++++++++++--------------

 1 file changed, 15 insertions(+), 14 deletions(-)

man3/assert.3 +0 -0

index 7cf7328..1b85a68 100644
@@ -24,6 +24,7 @@

.\"
.\" Modified Sat Jul 24 21:42:42 1993 by Rik Faith <[email protected]> .\" Modified Tue Oct 22 23:44:11 1996 by Eric S. Raymond <[email protected]>
+.\" Modified Thu Jun 2 23:44:11 2016 by Nikos Mavrogiannopoulos <[email protected]> .TH ASSERT 3 2015-08-08 "GNU" "Linux Programmer's Manual"
.SH NAME
assert \- abort the program if assertion is false
@@ -34,26 +35,26 @@ assert \- abort the program if assertion is false
.BI "void assert(scalar " expression );
.fi
.SH DESCRIPTION
+This macro can help programmers find bugs in their programs, or handle exceptional cases
+via a crash that will produce limited debugging output. The function will print an
+error message to standard error, e.g., "assertion failed in file foo.c, function do_bar(), line 1287" +and terminate the program by calling
+.BR abort (3)
+if
+.I expression
+is false (i.e., compares equal to zero).
+.LP
If the macro
.B NDEBUG
-was defined at the moment
+is defined at the moment
.I <assert.h>
was last included, the macro
.BR assert ()
-generates no code, and hence does nothing at all.
-Otherwise, the macro
+generates no code, and hence does nothing at all. It is not recommended to define
+.B NDEBUG
+if using
.BR assert ()
-prints an error message to standard error and terminates the program
-by calling
-.BR abort (3)
-if
-.I expression
-is false (i.e., compares equal to zero).
-.LP
-The purpose of this macro is to help programmers find bugs in
-their programs.
-The message "assertion failed in file foo.c, function
-do_bar(), line 1287" is of no help at all to a user.
+to detect error conditions since the software may behave non-deterministically.
.SH RETURN VALUE
No value is returned.
.SH ATTRIBUTES
--
2.5.5

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Michael Kerrisk (man-pages)

2016-06-02 23:35 UTC #2 lore raw

Hi Nikos,

Quoted 4 lines · Nikos Mavrogiannopoulos

Removed text referring to text not being helpful to users. Provide the error text instead to allow the reader to determine whether it is helpful. Recommend against using NDEBUG for programs to excibit deterministic behavior. Moved description ahead of recommendations.

The patch concept seems good to me, butfor some reason it does not apply. Could you check against latest git please?

Thanks,

Michael

Quoted 62 lines

Signed-off-by Nikos Mavrogiannopoulos <[email protected]>

---
 man3/assert.3 | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

man3/assert.3 +15 ~~-14~~

index 7cf7328..1b85a68 100644
@@ -24,6 +24,7 @@
 .\"
 .\" Modified Sat Jul 24 21:42:42 1993 by Rik Faith <[email protected]>
 .\" Modified Tue Oct 22 23:44:11 1996 by Eric S. Raymond <[email protected]>
+.\" Modified Thu Jun  2 23:44:11 2016 by Nikos Mavrogiannopoulos <[email protected]>
 .TH ASSERT 3  2015-08-08 "GNU" "Linux Programmer's Manual"
 .SH NAME
 assert \- abort the program if assertion is false

@@ -34,26 +35,26 @@ assert \- abort the program if assertion is false
 .BI "void assert(scalar " expression );
 .fi
 .SH DESCRIPTION
+This macro can help programmers find bugs in their programs, or handle exceptional cases
+via a crash that will produce limited debugging output. The function will print an
+error message to standard error, e.g., "assertion failed in file foo.c, function do_bar(), line 1287"
+and terminate the program by calling
+.BR abort (3)
+if
+.I expression
+is false (i.e., compares equal to zero).
+.LP
 If the macro
 .B NDEBUG
-was defined at the moment
+is defined at the moment
 .I <assert.h>
 was last included, the macro
 .BR assert ()
-generates no code, and hence does nothing at all.
-Otherwise, the macro
+generates no code, and hence does nothing at all. It is not recommended to define 
+.B NDEBUG
+if using
 .BR assert ()
-prints an error message to standard error and terminates the program
-by calling
-.BR abort (3)
-if
-.I expression
-is false (i.e., compares equal to zero).
-.LP
-The purpose of this macro is to help programmers find bugs in
-their programs.
-The message "assertion failed in file foo.c, function
-do_bar(), line 1287" is of no help at all to a user.
+to detect error conditions since the software may behave non-deterministically.
 .SH RETURN VALUE
 No value is returned.
 .SH ATTRIBUTES

Signature · 1 line

2.5.5

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): dce9e3be-8461-2d09-197d-424a64eed8b7-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org

Nikos Mavrogiannopoulos

author

2016-06-03 05:08 UTC #4 lore raw

Quoted 10 lines · Michael Kerrisk (man-pages)

Hi Nikos,
Quoted 7 lines · Nikos Mavrogiannopoulos
Removed text referring to text not being helpful to users. Provide the error text instead to allow the reader to determine whether it is helpful.
Recommend against using NDEBUG for programs to excibit deterministic behavior.
Moved description ahead of recommendations.

Quoted 3 lines

The patch concept seems good to me, butfor some reason it does not apply.
Could you check against latest git please?

I've rebased it against current master. Attached in case my mailer broke the patch.

From 0b59455d0889ced3c9d20ffed768c3911ed915b3 Mon Sep 17 00:00:00 2001
From: Nikos Mavrogiannopoulos <[email protected]>
Date: Thu, 2 Jun 2016 11:03:26 +0200
Subject: [PATCH] assert.3: improved description

Signed-off-by Nikos Mavrogiannopoulos <[email protected]>

---
 man3/assert.3 | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

man3/assert.3 +15 ~~-14~~

index 7cf7328..1b85a68 100644
@@ -24,6 +24,7 @@
 .\"
 .\" Modified Sat Jul 24 21:42:42 1993 by Rik Faith <[email protected]>
 .\" Modified Tue Oct 22 23:44:11 1996 by Eric S. Raymond <[email protected]>
+.\" Modified Thu Jun  2 23:44:11 2016 by Nikos Mavrogiannopoulos <[email protected]>
 .TH ASSERT 3  2015-08-08 "GNU" "Linux Programmer's Manual"
 .SH NAME
 assert \- abort the program if assertion is false

@@ -34,26 +35,26 @@ assert \- abort the program if assertion is false
 .BI "void assert(scalar " expression );
 .fi
 .SH DESCRIPTION
+This macro can help programmers find bugs in their programs, or handle exceptional cases
+via a crash that will produce limited debugging output. The function will print an
+error message to standard error, e.g., "assertion failed in file foo.c, function do_bar(), line 1287"
+and terminate the program by calling
+.BR abort (3)
+if
+.I expression
+is false (i.e., compares equal to zero).
+.LP
 If the macro
 .B NDEBUG
-was defined at the moment
+is defined at the moment
 .I <assert.h>
 was last included, the macro
 .BR assert ()
-generates no code, and hence does nothing at all.
-Otherwise, the macro
+generates no code, and hence does nothing at all. It is not recommended to define 
+.B NDEBUG
+if using
 .BR assert ()
-prints an error message to standard error and terminates the program
-by calling
-.BR abort (3)
-if
-.I expression
-is false (i.e., compares equal to zero).
-.LP
-The purpose of this macro is to help programmers find bugs in
-their programs.
-The message "assertion failed in file foo.c, function
-do_bar(), line 1287" is of no help at all to a user.
+to detect error conditions since the software may behave non-deterministically.
 .SH RETURN VALUE
 No value is returned.
 .SH ATTRIBUTES

Signature · 1 line

2.5.5

A message that is not in the archive (sent off-list or not yet received): [email protected]

Michael Kerrisk (man-pages)

2016-06-03 11:41 UTC #6 lore raw

Quoted 11 lines · Nikos Mavrogiannopoulos

Quoted 10 lines · Michael Kerrisk (man-pages)
Hi Nikos,
Quoted 7 lines · Nikos Mavrogiannopoulos
Removed text referring to text not being helpful to users. Provide the error text instead to allow the reader to determine whether it is helpful.
Recommend against using NDEBUG for programs to excibit deterministic behavior.
Moved description ahead of recommendations.

Quoted 6 lines

Quoted 3 lines
The patch concept seems good to me, butfor some reason it does not apply.
Could you check against latest git please?
I've rebased it against current master. Attached in case my mailer broke the patch.

Thanks, Nikos. Applied. I also did some further changes, so you might want to take a look.

Cheers,

Michael

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html