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

[Warner Losh]

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