d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
96f57c313d
freebsd-dev/share/man/man3/assert.3

111 lines
3.3 KiB
Groff
Raw Normal View History

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
.\"
Depart from normal man page proactice a little and provide guidance on when to use assert, as well as providing a bad example of using assert. While not strictly necessary, experience has shown issues with poor assert choice happen often enough that this departure seems warranted. Also, tighten up the previous example (there's no need to have extra paragraphs or gratuitously long lines). Reviewed by: emaste@ (earlier version)
2018-05-31 14:23:33 +00:00
.Dd May 31, 2018
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.
Depart from normal man page proactice a little and provide guidance on when to use assert, as well as providing a bad example of using assert. While not strictly necessary, experience has shown issues with poor assert choice happen often enough that this departure seems warranted. Also, tighten up the previous example (there's no need to have extra paragraphs or gratuitously long lines). Reviewed by: emaste@ (earlier version)
2018-05-31 14:23:33 +00:00
A 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 ) .
Add note that assert.h may be included multiple times with and without NDEBUG defined.
2018-01-01 18:59:11 +00:00
Unlike most other include files,
.In assert.h
may be included multiple times.
Each time whether or not
.Dv NDEBUG
is defined determines the behavior of assert from that point forward
Be less verbose and more precise.
2018-01-01 19:04:40 +00:00
until the end of the unit or another include of
Add note that assert.h may be included multiple times with and without NDEBUG defined.
2018-01-01 18:59:11 +00:00
.In assert.h .
Depart from normal man page proactice a little and provide guidance on when to use assert, as well as providing a bad example of using assert. While not strictly necessary, experience has shown issues with poor assert choice happen often enough that this departure seems warranted. Also, tighten up the previous example (there's no need to have extra paragraphs or gratuitously long lines). Reviewed by: emaste@ (earlier version)
2018-05-31 14:23:33 +00:00
.Pp
The
.Fn assert
macro should only be used for ensuring the developer's expectations
hold true.
It is not appropriate for regular run-time error detection.
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
.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
generates a diagnostic message similar to the following:
Depart from normal man page proactice a little and provide guidance on when to use assert, as well as providing a bad example of using assert. While not strictly necessary, experience has shown issues with poor assert choice happen often enough that this departure seems warranted. Also, tighten up the previous example (there's no need to have extra paragraphs or gratuitously long lines). Reviewed by: emaste@ (earlier version)
2018-05-31 14:23:33 +00:00
.Dl "Assertion failed: (1 == 0), function main, file main.c, line 100."
mdoc(7) police: one-line literal displays are faster.
2001-11-20 15:17:51 +00:00
.Pp
Depart from normal man page proactice a little and provide guidance on when to use assert, as well as providing a bad example of using assert. While not strictly necessary, experience has shown issues with poor assert choice happen often enough that this departure seems warranted. Also, tighten up the previous example (there's no need to have extra paragraphs or gratuitously long lines). Reviewed by: emaste@ (earlier version)
2018-05-31 14:23:33 +00:00
The following assert tries to assert there was no partial read:
.Dl "assert(read(fd, buf, nbytes) == nbytes);"
However, there are two problems.
First, it checks for normal conditions, rather than conditions that
indicate a bug.
Second, the code will disappear if
.Dv NDEBUG
is defined, changing the semantics of the program.
Expanded cross references.
1998-01-02 19:22:52 +00:00
.Sh SEE ALSO
Cross-reference abort2(2) from a few man pages I didn't know abort2 existed until it was mentioned on a mailing list. Mention it in related pages so others can find it easily. MFC after: 3 days Sponsored by: Dell EMC
2018-05-29 01:16:00 +00:00
.Xr abort2 2 ,
Expanded cross references.
1998-01-02 19:22:52 +00:00
.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
assert(3) appeared first in the 7th Edition Unix, not the 6th, at least according to the extant distributions preserved at tuhs.org. Obtained from: http://www.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/assert.h
2018-01-01 18:55:13 +00:00
.At v7 .
Reference in New Issue Copy Permalink