1.\" Copyright (c) 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)assert.3 8.1 (Berkeley) 6/9/93 29.\" $FreeBSD$ 30.\" 31.Dd April 20, 2021 32.Dt ASSERT 3 33.Os 34.Sh NAME 35.Nm assert , 36.Nm static_assert 37.Nd expression verification macro 38.Sh SYNOPSIS 39.In assert.h 40.Fn assert expression 41.Fn static_assert expression 42.Fn static_assert expression message 43.Sh DESCRIPTION 44The 45.Fn assert 46macro tests the given 47.Ar expression 48and if it is false, 49the calling process is terminated. 50A diagnostic message is written to 51.Dv stderr 52and the function 53.Xr abort 3 54is called, effectively terminating the program. 55.Pp 56If 57.Ar expression 58is true, 59the 60.Fn assert 61macro does nothing. 62.Pp 63The 64.Fn assert 65macro 66may be removed at compile time by defining 67.Dv NDEBUG 68as a macro 69(e.g., by using the 70.Xr cc 1 71option 72.Fl D Ns Dv NDEBUG ) . 73Unlike most other include files, 74.In assert.h 75may be included multiple times. 76Each time whether or not 77.Dv NDEBUG 78is defined determines the behavior of assert from that point forward 79until the end of the unit or another include of 80.In assert.h . 81.Pp 82The 83.Fn assert 84macro should only be used for ensuring the developer's expectations 85hold true. 86It is not appropriate for regular run-time error detection. 87.Pp 88The 89.Fn static_assert 90macro expands to 91.Fn _Static_assert , 92and, contrarily to 93.Fn assert , 94makes assertions at compile-time. 95Once the constraint is violated, the compiler produces a diagnostic 96message including the string literal message, if provided. 97The initial form of the 98.Fn _Static_assert 99containing a string literal message was introduced in C11 standard, and 100the other form with no string literal is to be implemented by C2x and 101some compilers may lack its adoption at present. 102.Sh EXAMPLES 103The assertion: 104.Dl "assert(1 == 0);" 105generates a diagnostic message similar to the following: 106.Dl "Assertion failed: (1 == 0), function main, file main.c, line 100." 107.Pp 108The following assert tries to assert there was no partial read: 109.Dl "assert(read(fd, buf, nbytes) == nbytes);" 110However, there are two problems. 111First, it checks for normal conditions, rather than conditions that 112indicate a bug. 113Second, the code will disappear if 114.Dv NDEBUG 115is defined, changing the semantics of the program. 116.Pp 117The following asserts that the size of the S structure is 16. 118Otherwise, it produces a diagnostic message which points at the 119constraint and includes the provided string literal: 120.Dl "static_assert(sizeof(struct S) == 16, ""size mismatch"");" 121If none is provided, it only points at the constraint. 122.Sh SEE ALSO 123.Xr abort2 2 , 124.Xr abort 3 125.Sh STANDARDS 126.Rs 127The 128.Fn assert 129macro conforms to 130.St -isoC-99 . 131.Re 132.Pp 133.Rs 134The 135.Fn static_assert 136macro conforms to 137.St -isoC-2011 . 138.Re 139.Sh HISTORY 140An 141.Nm 142macro appeared in 143.At v7 . 144