Date: Thu, 31 May 2018 07:42:08 -0700 (PDT) From: "Rodney W. Grimes" <freebsd@pdx.rh.CN85.dnsmgr.net> To: Warner Losh <imp@freebsd.org> Cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r334431 - head/share/man/man3 Message-ID: <201805311442.w4VEg8c9077097@pdx.rh.CN85.dnsmgr.net> In-Reply-To: <201805311423.w4VENXwY020239@repo.freebsd.org>
next in thread | previous 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). Thank you! > 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 > > -- Rod Grimes rgrimes@freebsd.org
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201805311442.w4VEg8c9077097>