man3/assert.3

   1 '\" t
   2 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified Sat Jul 24 21:42:42 1993 by Rik Faith <faith@cs.unc.edu>
   7 .\" Modified Tue Oct 22 23:44:11 1996 by Eric S. Raymond <esr@thyrsus.com>
   8 .\" Modified Thu Jun  2 23:44:11 2016 by Nikos Mavrogiannopoulos <nmav@redhat.com>
   9 .TH assert 3 (date) "Linux man-pages (unreleased)"
  10 .SH NAME
  11 assert \- abort the program if assertion is false
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <assert.h>
  18 .P
  19 .BI "void assert(scalar " expression );
  20 .fi
  21 .SH DESCRIPTION
  22 This macro can help programmers find bugs in their programs,
  23 or handle exceptional cases
  24 via a crash that will produce limited debugging output.
  25 .P
  26 If
  27 .I expression
  28 is false (i.e., compares equal to zero),
  29 .BR assert ()
  30 prints an error message to standard error
  31 and terminates the program by calling
  32 .BR abort (3).
  33 The error message includes the name of the file and function containing the
  34 .BR assert ()
  35 call, the source code line number of the call, and the text of the argument;
  36 something like:
  37 .P
  38 .in +4n
  39 .EX
  40 prog: some_file.c:16: some_func: Assertion \`val == 0\[aq] failed.
  41 .EE
  42 .in
  43 .P
  44 If the macro
  45 .B NDEBUG
  46 is defined at the moment
  47 .I <assert.h>
  48 was last included, the macro
  49 .BR assert ()
  50 generates no code, and hence does nothing at all.
  51 It is not recommended to define
  52 .B NDEBUG
  53 if using
  54 .BR assert ()
  55 to detect error conditions since the software
  56 may behave non-deterministically.
  57 .SH RETURN VALUE
  58 No value is returned.
  59 .SH ATTRIBUTES
  60 For an explanation of the terms used in this section, see
  61 .BR attributes (7).
  62 .TS
  63 allbox;
  64 lbx lb lb
  65 l l l.
  66 Interface       Attribute       Value
  67 T{
  68 .na
  69 .nh
  70 .BR assert ()
  71 T}      Thread safety   MT-Safe
  72 .TE
  73 .SH STANDARDS
  74 C11, POSIX.1-2008.
  75 .SH HISTORY
  76 C89, C99, POSIX.1-2001.
  77 .P
  78 In C89,
  79 .I expression
  80 is required to be of type
  81 .I int
  82 and undefined behavior results if it is not, but in C99
  83 it may have any scalar type.
  84 .\" See Defect Report 107 for more details.
  85 .SH BUGS
  86 .BR assert ()
  87 is implemented as a macro; if the expression tested has side-effects,
  88 program behavior will be different depending on whether
  89 .B NDEBUG
  90 is defined.
  91 This may create Heisenbugs which go away when debugging
  92 is turned on.
  93 .SH SEE ALSO
  94 .BR abort (3),
  95 .BR assert_perror (3),
  96 .BR exit (3)