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

[Rodney W. Grimes]

> 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 at freebsd.org