GNU Info

(libc.info)Consistency Checking

---

Next: Variadic Functions Up: Language Features

---

Enter node , (file) or (file)node

Explicitly Checking Internal Consistency
========================================

   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.

   The `assert' macro, defined in the header file `assert.h', provides
a convenient way to abort the program while printing a message about
where in the program the error was detected.

   Once you think your program is debugged, you can disable the error
checks performed by the `assert' macro by recompiling with the macro
`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.

 - Macro: void assert (int EXPRESSION)
     Verify the programmer's belief that EXPRESSION is nonzero at this
     point in the program.

     If `NDEBUG' is not defined, `assert' tests the value of
     EXPRESSION.  If it is false (zero), `assert' aborts the program
     (Note: Aborting a Program) after printing a message of the form:

          `FILE':LINENUM: FUNCTION: Assertion `EXPRESSION' failed.

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

     If the preprocessor macro `NDEBUG' is defined before `assert.h' is
     included, the `assert' macro is defined to do absolutely nothing.

     *Warning:* Even the argument expression EXPRESSION is not
     evaluated if `NDEBUG' is in effect.  So never use `assert' with
     arguments that involve side effects.  For example, `assert (++i >
     0);' is a bad idea, because `i' will not be incremented if
     `NDEBUG' is defined.

   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 `assert_perror' macro makes this easy.

 - Macro: void assert_perror (int ERRNUM)
     Similar to `assert', but verifies that ERRNUM is zero.

     If `NDEBUG' is defined, `assert_perror' tests the value of ERRNUM.
     If it is nonzero, `assert_perror' aborts the program after
     printing a message of the form:

          `FILE':LINENUM: FUNCTION: ERROR TEXT

     on the standard error stream.  The file name, line number, and
     function name are as for `assert'.  The error text is the result of
     `strerror (ERRNUM)'.  Note: Error Messages.

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

     This macro is a GNU extension.

   *Usage note:* The `assert' facility is designed for detecting
_internal inconsistency_; it is not suitable for reporting invalid
input or improper usage by the _user_ of the program.

   The information in the diagnostic messages printed by the `assert'
and `assert_perror' macro is intended to help you, the programmer,
track down the cause of a bug, but is not really useful for telling a
user of your program why his or her input was invalid or why a command
could not be carried out.  What's more, your program should not abort
when given invalid input, as `assert' would do--it should exit with
nonzero status (Note: Exit Status) after printing its error messages,
or perhaps read another command or move on to the next input file.

   Note: Error Messages, for information on printing error messages
for problems that _do not_ represent bugs in the program.