Date: Thu, 31 May 2018 07:46:19 -0700 From: Ben Widawsky <ben@bwidawsk.net> To: rgrimes@freebsd.org Cc: Warner Losh <imp@freebsd.org>, svn-src-head@freebsd.org, svn-src-all@freebsd.org, src-committers@freebsd.org Subject: Re: svn commit: r334431 - head/share/man/man3 Message-ID: <20180531144619.jjy45q6elg2hanmi@mail.bwidawsk.net> In-Reply-To: <201805311442.w4VEg8c9077097@pdx.rh.CN85.dnsmgr.net> References: <201805311423.w4VENXwY020239@repo.freebsd.org> <201805311442.w4VEg8c9077097@pdx.rh.CN85.dnsmgr.net>
next in thread | previous in thread | raw e-mail | index | archive | help
On 18-05-31 07:42:08, Rodney W. Grimes wrote: > > 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 ^ typo > > 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 > _______________________________________________ > svn-src-head@freebsd.org mailing list > https://lists.freebsd.org/mailman/listinfo/svn-src-head > To unsubscribe, send any mail to "svn-src-head-unsubscribe@freebsd.org"
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20180531144619.jjy45q6elg2hanmi>