From f34fcbb86bc1e0bfcb09e527327eb7a4726948e9 Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Fri, 3 Jun 2016 07:08:50 +0200 Subject: [PATCH] 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 exhibit deterministic behavior. Moved description ahead of recommendations. Signed-off-by: Nikos Mavrogiannopoulos --- man3/assert.3 | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/man3/assert.3 b/man3/assert.3 index 7cf732860..1b85a6848 100644 --- a/man3/assert.3 +++ b/man3/assert.3 @@ -24,6 +24,7 @@ .\" .\" Modified Sat Jul 24 21:42:42 1993 by Rik Faith .\" Modified Tue Oct 22 23:44:11 1996 by Eric S. Raymond +.\" Modified Thu Jun 2 23:44:11 2016 by Nikos Mavrogiannopoulos .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 -If the macro -.B NDEBUG -was defined at the moment -.I -was last included, the macro -.BR assert () -generates no code, and hence does nothing at all. -Otherwise, the macro -.BR assert () -prints an error message to standard error and terminates the program -by calling +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 -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. +If the macro +.B NDEBUG +is defined at the moment +.I +was last included, the macro +.BR assert () +generates no code, and hence does nothing at all. It is not recommended to define +.B NDEBUG +if using +.BR assert () +to detect error conditions since the software may behave non-deterministically. .SH RETURN VALUE No value is returned. .SH ATTRIBUTES