man3/assert.3

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