glibc/manual/assert.texi

@node Consistency Checking, Mathematics, Low-Level Terminal Interface, Top
@chapter Explicitly Checking Internal Consistency
@cindex consistency checking
@cindex impossible events
@cindex assertions

When you're writing a program, it's often a good idea to put in checks
at strategic places for ``impossible'' errors or violations of basic
assumptions.  These kinds of checks are helpful in debugging problems
with the interfaces between different parts of the program, for example.

@pindex assert.h
The @code{assert} macro, defined in the header file @file{assert.h},
provides a convenient way to abort the program while printing some
debugging information about where in the program the error was detected.

@vindex NDEBUG
Once you think your program is debugged, you can disable the error
checks performed by the @code{assert} macro by recompiling with the
macro @code{NDEBUG} defined.  This means you don't actually have to
change the program source code to disable these checks.

But disabling these consistency checks is undesirable unless they make
the program significantly slower.  All else being equal, more error
checking is good no matter who is running the program.  A wise user
would rather have a program crash, visibly, than have it return nonsense
without indicating anything might be wrong.

@comment assert.h
@comment ANSI
@deftypefn Macro void assert (int @var{expression})
Verify the programmer's belief that @var{expression} should be nonzero
at a certain point in the program.

If @code{NDEBUG} is not defined, @code{assert} tests the value of
@var{expression}.  If it is false (zero), @code{assert} aborts the
program (@pxref{Aborting a Program}) after printing a message of the
form:

@smallexample
@file{@var{file}}:@var{linenum}: @var{function}: Assertion `@var{expression}' failed.
@end smallexample

@noindent
on the standard error stream @code{stderr} (@pxref{Standard Streams}).
The filename and line number are taken from the C preprocessor macros
@code{__FILE__} and @code{__LINE__} and specify where the call to
@code{assert} was written.  When using the GNU C compiler, the name of
the function which calls @code{assert} is taken from the built-in
variable @code{__PRETTY_FUNCTION__}; with older compilers, the function
name and following colon are omitted.

If the preprocessor macro @code{NDEBUG} is defined before
@file{assert.h} is included, the @code{assert} macro is defined to do
absolutely nothing.  Even the argument expression @var{expression} is
not evaluated, so you should avoid calling @code{assert} with arguments
that involve side effects.

For example, @code{assert (++i > 0);} is a bad idea, because @code{i}
will not be incremented if @code{NDEBUG} is defined.
@end deftypefn

Sometimes the ``impossible'' condition you want to check for is an error
return from an operating system function.  Then it is useful to display
not only where the program crashes, but also what error was returned.
The @code{assert_perror} macro makes this easy.

@comment assert.h
@comment GNU
@deftypefn Macro void assert_perror (int @var{errnum})
Similar to @code{assert}, but verifies that @var{errnum} is zero.

If @code{NDEBUG} is defined, @code{assert_perror} tests the value of
@var{errnum}.  If it is nonzero, @code{assert_perror} aborts the program
after a printing a message of the form:

@smallexample
@file{@var{file}}:@var{linenum}: @var{function}: @var{error text}
@end smallexample

@noindent
on the standard error stream.  The file name, line number, and function
name are as for @code{assert}.  The error text is the result of
@w{@code{strerror (@var{errnum})}}.  @xref{Error Messages}.

Like @code{assert}, if @code{NDEBUG} is defined before @file{assert.h}
is included, the @code{assert_perror} macro does absolutely nothing.  It
does not evaluate the argument, so @var{errnum} should not have any side
effects.  It is best for @var{errnum} to be a just simple variable
reference; often it will be @code{errno}.

This macro is a GNU extension.
@end deftypefn

@strong{Usage note:} The @code{assert} facility is designed for
detecting @emph{internal inconsistency}; it is not suitable for
reporting invalid input or improper usage.

The information in the diagnostic messages provided by the @code{assert}
macro is intended to to help you, the programmer, track down the cause
of a bug, but is not really useful in telling a user of your program why
his or her input was invalid or why a command could not be carried out.
So you can't use @code{assert} to print the error messages for these
eventualities.

What's more, your program should not abort when given invalid input, as
@code{assert} would do---it should exit with nonzero status after
printing its error messages, or perhaps read another command or move
on to the next input file.

@xref{Error Messages}, for information on printing error messages for
problems that @emph{do not} represent bugs in the program.