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.
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.
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.