Consistency Checking (The GNU C Library)

### A.1 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)` ¶

  Preliminary: | MT-Safe | AS-Unsafe heap corrupt | AC-Unsafe mem lock corrupt | See POSIX Safety Concepts.

  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 (see Aborting a Program) after printing a message of the form:

      file:linenum: function: Assertion `expression' failed.

  on the standard error stream `stderr` (see 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)` ¶

  Preliminary: | MT-Safe | AS-Unsafe heap corrupt | AC-Unsafe mem lock corrupt | See POSIX Safety Concepts.

  Similar to `assert`, but verifies that errnum is zero.

  If `NDEBUG` is not 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)`. See 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 (see Exit Status) after printing its error messages, or perhaps read another command or move on to the next input file.

See Error Messages, for information on printing error messages for problems that do not represent bugs in the program.