From owner-svn-src-head@freebsd.org Thu May 31 14:42:10 2018 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id B065CFD49C1; Thu, 31 May 2018 14:42:10 +0000 (UTC) (envelope-from freebsd@pdx.rh.CN85.dnsmgr.net) Received: from pdx.rh.CN85.dnsmgr.net (br1.CN84in.dnsmgr.net [69.59.192.140]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 14FF66963D; Thu, 31 May 2018 14:42:09 +0000 (UTC) (envelope-from freebsd@pdx.rh.CN85.dnsmgr.net) Received: from pdx.rh.CN85.dnsmgr.net (localhost [127.0.0.1]) by pdx.rh.CN85.dnsmgr.net (8.13.3/8.13.3) with ESMTP id w4VEg8rg077098; Thu, 31 May 2018 07:42:08 -0700 (PDT) (envelope-from freebsd@pdx.rh.CN85.dnsmgr.net) Received: (from freebsd@localhost) by pdx.rh.CN85.dnsmgr.net (8.13.3/8.13.3/Submit) id w4VEg8c9077097; Thu, 31 May 2018 07:42:08 -0700 (PDT) (envelope-from freebsd) From: "Rodney W. Grimes" Message-Id: <201805311442.w4VEg8c9077097@pdx.rh.CN85.dnsmgr.net> Subject: Re: svn commit: r334431 - head/share/man/man3 In-Reply-To: <201805311423.w4VENXwY020239@repo.freebsd.org> To: Warner Losh Date: Thu, 31 May 2018 07:42:08 -0700 (PDT) CC: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Reply-To: rgrimes@freebsd.org X-Mailer: ELM [version 2.4ME+ PL121h (25)] MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 31 May 2018 14:42:10 -0000 > 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