freebsd-nq/share/man/man3/assert.3

.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)assert.3	8.1 (Berkeley) 6/9/93
.\" $FreeBSD$
.\"
.Dd January 26, 1999
.Dt ASSERT 3
.Os
.Sh NAME
.Nm assert
.Nd expression verification macro
.Sh SYNOPSIS
.In assert.h
.Fn assert expression
.Sh DESCRIPTION
The
.Fn assert
macro tests the given
.Ar expression
and if it is false,
the calling process is terminated.
A
diagnostic message is written to
.Dv stderr
and the function
.Xr abort 3
is called, effectively terminating the program.
.Pp
If
.Ar expression
is true,
the
.Fn assert
macro does nothing.
.Pp
The
.Fn assert
macro
may be removed at compile time by defining
.Dv NDEBUG
as a macro
(e.g., by using the
.Xr cc 1
option
.Fl D Ns Dv NDEBUG ) .
.Sh EXAMPLES
The assertion:
.Pp
.Dl "assert(1 == 0);"
.Pp
generates a diagnostic message similar to the following:
.Pp
.Dl "Assertion failed: (1 == 0), function main, file assertion.c, line 100."
.Sh SEE ALSO
.Xr abort 3
.Sh STANDARDS
The
.Fn assert
macro conforms to
.St -isoC-99 .
.Sh HISTORY
An
.Nm
macro appeared in
.At v6 .
BSD 4.4 Lite Share Sources 1994-05-30 19:09:18 +00:00			`.\" Copyright (c) 1991, 1993`
			`.\" The Regents of the University of California. All rights reserved.`
			`.\"`
			`.\" Redistribution and use in source and binary forms, with or without`
			`.\" modification, are permitted provided that the following conditions`
			`.\" are met:`
			`.\" 1. Redistributions of source code must retain the above copyright`
			`.\" notice, this list of conditions and the following disclaimer.`
			`.\" 2. Redistributions in binary form must reproduce the above copyright`
			`.\" notice, this list of conditions and the following disclaimer in the`
			`.\" documentation and/or other materials provided with the distribution.`
multiple: Remove 3rd clause from BSD license where approved by the regents and renumber. This patch skips files in contrib/ and crypto/ Acked by: imp Discussed with: emaste 2014-03-14 03:07:51 +00:00			`.\" 3. Neither the name of the University nor the names of its contributors`
BSD 4.4 Lite Share Sources 1994-05-30 19:09:18 +00:00			`.\" may be used to endorse or promote products derived from this software`
			`.\" without specific prior written permission.`
			`.\"`
			.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
			`.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE`
			`.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE`
			`.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE`
			`.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL`
			`.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS`
			`.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)`
			`.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT`
			`.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY`
			`.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF`
			`.\" SUCH DAMAGE.`
			`.\"`
			`.\" @(#)assert.3 8.1 (Berkeley) 6/9/93`
$Id$ -> $FreeBSD$ 1999-08-28 00:22:10 +00:00			`.\" $FreeBSD$`
BSD 4.4 Lite Share Sources 1994-05-30 19:09:18 +00:00			`.\"`
Fix typo by rewriting sentence. 1999-01-26 16:59:02 +00:00			`.Dd January 26, 1999`
BSD 4.4 Lite Share Sources 1994-05-30 19:09:18 +00:00			`.Dt ASSERT 3`
			`.Os`
			`.Sh NAME`
			`.Nm assert`
			`.Nd expression verification macro`
			`.Sh SYNOPSIS`
mdoc(7) police: Use the new .In macro for #include statements. 2001-10-01 16:09:29 +00:00			`.In assert.h`
BSD 4.4 Lite Share Sources 1994-05-30 19:09:18 +00:00			`.Fn assert expression`
			`.Sh DESCRIPTION`
			`The`
			`.Fn assert`
			`macro tests the given`
			`.Ar expression`
			`and if it is false,`
			`the calling process is terminated.`
			`A`
Fix typo by rewriting sentence. 1999-01-26 16:59:02 +00:00			`diagnostic message is written to`
Consistently mark std(in\|out\|err) with .Dv, because that's how they are marked up in stdio(3), and because they are defined expressions of type "FILE *". Approved by: re 2002-12-04 18:57:46 +00:00			`.Dv stderr`
BSD 4.4 Lite Share Sources 1994-05-30 19:09:18 +00:00			`and the function`
Indicate that assert exits with abort(3) instead of _exit(2). Closes PR 1317. Reviewed by: alex Submitted by: Cove Schneider <cove@brazil.nbn.com> 1996-06-12 23:46:47 +00:00			`.Xr abort 3`
Minor punctuation/grammar nits. 1999-04-30 13:12:44 +00:00			`is called, effectively terminating the program.`
BSD 4.4 Lite Share Sources 1994-05-30 19:09:18 +00:00			`.Pp`
			`If`
			`.Ar expression`
			`is true,`
			`the`
			`.Fn assert`
			`macro does nothing.`
			`.Pp`
			`The`
			`.Fn assert`
			`macro`
Fix typo by rewriting sentence. 1999-01-26 16:59:02 +00:00			`may be removed at compile time by defining`
			`.Dv NDEBUG`
			`as a macro`
			`(e.g., by using the`
			`.Xr cc 1`
			`option`
			`.Fl D Ns Dv NDEBUG ) .`
Only provide function information in compile environments that support the C99 variable __func__ and never for C++. Provide a more meaningful example in the assert(3) manual. Reviewed by: asmodai, bde 2001-10-27 20:11:10 +00:00			`.Sh EXAMPLES`
			`The assertion:`
mdoc(7) police: one-line literal displays are faster. 2001-11-20 15:17:51 +00:00			`.Pp`
			`.Dl "assert(1 == 0);"`
Only provide function information in compile environments that support the C99 variable __func__ and never for C++. Provide a more meaningful example in the assert(3) manual. Reviewed by: asmodai, bde 2001-10-27 20:11:10 +00:00			`.Pp`
			`generates a diagnostic message similar to the following:`
mdoc(7) police: one-line literal displays are faster. 2001-11-20 15:17:51 +00:00			`.Pp`
Make the example "assertion failure" message match reality. 2002-10-25 14:22:20 +00:00			`.Dl "Assertion failed: (1 == 0), function main, file assertion.c, line 100."`
Expanded cross references. 1998-01-02 19:22:52 +00:00			`.Sh SEE ALSO`
			`.Xr abort 3`
Document C99 conformity. Update text which is printed out to reflect reality. 2001-10-24 18:14:51 +00:00			`.Sh STANDARDS`
			`The`
			`.Fn assert`
Only provide function information in compile environments that support the C99 variable __func__ and never for C++. Provide a more meaningful example in the assert(3) manual. Reviewed by: asmodai, bde 2001-10-27 20:11:10 +00:00			`macro conforms to`
Document C99 conformity. Update text which is printed out to reflect reality. 2001-10-24 18:14:51 +00:00			`.St -isoC-99 .`
BSD 4.4 Lite Share Sources 1994-05-30 19:09:18 +00:00			`.Sh HISTORY`
Minor punctuation/grammar nits. 1999-04-30 13:12:44 +00:00			`An`
mdoc(7) police: use the new features of the Nm macro. 2000-11-20 18:41:33 +00:00			`.Nm`
BSD 4.4 Lite Share Sources 1994-05-30 19:09:18 +00:00			`macro appeared in`
			`.At v6 .`