Date: Thu, 31 May 2018 14:23:33 +0000 (UTC) From: Warner Losh <imp@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r334431 - head/share/man/man3 Message-ID: <201805311423.w4VENXwY020239@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: imp Date: Thu May 31 14:23:33 2018 New Revision: 334431 URL: https://svnweb.freebsd.org/changeset/base/334431 Log: 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) Modified: head/share/man/man3/assert.3 Modified: head/share/man/man3/assert.3 ============================================================================== --- head/share/man/man3/assert.3 Thu May 31 13:26:12 2018 (r334430) +++ head/share/man/man3/assert.3 Thu May 31 14:23:33 2018 (r334431) @@ -28,7 +28,7 @@ .\" @(#)assert.3 8.1 (Berkeley) 6/9/93 .\" $FreeBSD$ .\" -.Dd May 28, 2018 +.Dd May 31, 2018 .Dt ASSERT 3 .Os .Sh NAME @@ -44,8 +44,7 @@ macro tests the given .Ar expression and if it is false, the calling process is terminated. -A -diagnostic message is written to +A diagnostic message is written to .Dv stderr and the function .Xr abort 3 @@ -76,14 +75,26 @@ Each time whether or not is defined determines the behavior of assert from that point forward until the end of the unit or another include of .In assert.h . +.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. .Sh EXAMPLES The assertion: -.Pp .Dl "assert(1 == 0);" -.Pp generates a diagnostic message similar to the following: +.Dl "Assertion failed: (1 == 0), function main, file main.c, line 100." .Pp -.Dl "Assertion failed: (1 == 0), function main, file assertion.c, line 100." +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. .Sh SEE ALSO .Xr abort2 2 , .Xr abort 3
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201805311423.w4VENXwY020239>