Put a @table around @include summary.out.
[kopensolaris-gnu/glibc.git] / manual / assert.texi
1 @node Consistency Checking
2 @chapter Explicitly Checking Internal Consistency
3 @cindex consistency checking
4 @cindex impossible events
5 @cindex assertions
6
7 When you're writing a program, it's often a good idea to put in checks
8 at strategic places for ``impossible'' errors or violations of basic
9 assumptions.  These kinds of checks are helpful in debugging problems
10 with the interfaces between different parts of the program, for example.
11
12 @pindex assert.h
13 The @code{assert} macro, defined in the header file @file{assert.h},
14 provides a convenient way to abort the program while printing some
15 debugging information about where in the program the error was detected.
16
17 @vindex NDEBUG
18 Once you think your program is debugged, you can disable the error
19 checks performed by the @code{assert} macro by recompiling with the
20 macro @code{NDEBUG} defined.  This means you don't actually have to
21 change the program source code to disable these checks.
22
23 But disabling these consistency checks is undesirable unless they make
24 the program significantly slower.  All else being equal, more error
25 checking is good no matter who is running the program.  A wise user
26 would rather have a program crash, visibly, than have it return nonsense
27 without indicating anything might be wrong.
28
29 @comment assert.h
30 @comment ANSI
31 @deftypefn Macro void assert (int @var{expression})
32 Verify the programmer's belief that @var{expression} should be nonzero
33 at a certain point in the program.
34
35 If @code{NDEBUG} is not defined, @code{assert} tests the value of
36 @var{expression}.  If it is false (zero), @code{assert} aborts the
37 program (@pxref{Aborting a Program}) after printing a message of the
38 form:
39
40 @example
41 @file{@var{file}}:@var{linenum}: Assertion `@var{expression}' failed.
42 @end example
43
44 @noindent
45 on the standard error stream @code{stderr} (@pxref{Standard Streams}).
46 The filename and line number are taken from the C preprocessor macros
47 @code{__FILE__} and @code{__LINE__} and specify where the call to
48 @code{assert} was written.
49
50 If the preprocessor macro @code{NDEBUG} is defined before
51 @file{assert.h} is included, the @code{assert} macro is defined to do
52 absolutely nothing.  Even the argument expression @var{expression} is
53 not evaluated, so you should avoid calling @code{assert} with arguments
54 that involve side effects.
55
56 For example, @code{assert (++i > 0);} is a bad idea, because @code{i}
57 will not be incremented if @code{NDEBUG} is defined.
58 @end deftypefn
59
60 @strong{Usage note:} The @code{assert} facility is designed for
61 detecting @emph{internal inconsistency}; it is not suitable for
62 reporting invalid input or improper usage.
63
64 The information in the diagnostic messages provided by the @code{assert}
65 macro is intended to to help you, the programmer, track down the cause
66 of a bug, but is not really useful in telling a user of your program why
67 his or her input was invalid or why a command could not be carried out.
68 So you can't use @code{assert} to print the error messages for these
69 eventualities.
70
71 What's more, your program should not abort when given invalid input, as
72 @code{assert} would do---it should exit with nonzero status after
73 printing its error messages, or perhaps read another command or move
74 on to the next input file.
75
76 @xref{Error Messages}, for information on printing error messages for
77 problems that @emph{do not} represent bugs in the program.
78