svn commit: r334431 - head/share/man/man3

[Ben Widawsky]

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 at freebsd.org
> _______________________________________________
> svn-src-head at freebsd.org mailing list
> https://lists.freebsd.org/mailman/listinfo/svn-src-head
> To unsubscribe, send any mail to "svn-src-head-unsubscribe at freebsd.org"