manual/assert.texi

   1 @node Consistency Checking, Mathematics, Low-Level Terminal Interface, Top
   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 @smallexample
  41 @file{@var{file}}:@var{linenum}: @var{function}: Assertion `@var{expression}' failed.
  42 @end smallexample
  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.  When using the GNU C compiler, the name of
  49 the function which calls @code{assert} is taken from the built-in
  50 variable @code{__PRETTY_FUNCTION__}; with older compilers, the function
  51 name and following colon are omitted.
  52
  53 If the preprocessor macro @code{NDEBUG} is defined before
  54 @file{assert.h} is included, the @code{assert} macro is defined to do
  55 absolutely nothing.  Even the argument expression @var{expression} is
  56 not evaluated, so you should avoid calling @code{assert} with arguments
  57 that involve side effects.
  58
  59 For example, @code{assert (++i > 0);} is a bad idea, because @code{i}
  60 will not be incremented if @code{NDEBUG} is defined.
  61 @end deftypefn
  62
  63 Sometimes the ``impossible'' condition you want to check for is an error
  64 return from an operating system function.  Then it is useful to display
  65 not only where the program crashes, but also what error was returned.
  66 The @code{assert_perror} macro makes this easy.
  67
  68 @comment assert.h
  69 @comment GNU
  70 @deftypefn Macro void assert_perror (int @var{errnum})
  71 Similar to @code{assert}, but verifies that @var{errnum} is zero.
  72
  73 If @code{NDEBUG} is defined, @code{assert_perror} tests the value of
  74 @var{errnum}.  If it is nonzero, @code{assert_perror} aborts the program
  75 after a printing a message of the form:
  76
  77 @smallexample
  78 @file{@var{file}}:@var{linenum}: @var{function}: @var{error text}
  79 @end smallexample
  80
  81 @noindent
  82 on the standard error stream.  The file name, line number, and function
  83 name are as for @code{assert}.  The error text is the result of
  84 @w{@code{strerror (@var{errnum})}}.  @xref{Error Messages}.
  85
  86 Like @code{assert}, if @code{NDEBUG} is defined before @file{assert.h}
  87 is included, the @code{assert_perror} macro does absolutely nothing.  It
  88 does not evaluate the argument, so @var{errnum} should not have any side
  89 effects.  It is best for @var{errnum} to be a just simple variable
  90 reference; often it will be @code{errno}.
  91
  92 This macro is a GNU extension.
  93 @end deftypefn
  94
  95 @strong{Usage note:} The @code{assert} facility is designed for
  96 detecting @emph{internal inconsistency}; it is not suitable for
  97 reporting invalid input or improper usage.
  98
  99 The information in the diagnostic messages provided by the @code{assert}
 100 macro is intended to to help you, the programmer, track down the cause
 101 of a bug, but is not really useful in telling a user of your program why
 102 his or her input was invalid or why a command could not be carried out.
 103 So you can't use @code{assert} to print the error messages for these
 104 eventualities.
 105
 106 What's more, your program should not abort when given invalid input, as
 107 @code{assert} would do---it should exit with nonzero status after
 108 printing its error messages, or perhaps read another command or move
 109 on to the next input file.
 110
 111 @xref{Error Messages}, for information on printing error messages for
 112 problems that @emph{do not} represent bugs in the program.
 113