From owner-svn-src-head@freebsd.org Thu May 31 14:54:02 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 1C6F7FD5AD0; Thu, 31 May 2018 14:54:02 +0000 (UTC) (envelope-from ben@bwidawsk.net) Received: from mail.bwidawsk.net (zangief2.bwidawsk.net [107.170.211.233]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "bwidawsk.net", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id AC9A46A213; Thu, 31 May 2018 14:54:01 +0000 (UTC) (envelope-from ben@bwidawsk.net) Received: by mail.bwidawsk.net (Postfix, from userid 5001) id F3796123191; Thu, 31 May 2018 07:46:21 -0700 (PDT) X-Spam-Checker-Version: SpamAssassin 3.4.1 (2015-04-28) on zangief.bwidawsk.net X-Spam-Level: X-Spam-ASN: X-Spam-Status: No, score=-1.0 required=4.1 tests=ALL_TRUSTED=-1 shortcircuit=no autolearn=no autolearn_force=no version=3.4.1 Received: from mail.bwidawsk.net (c-73-25-164-31.hsd1.or.comcast.net [73.25.164.31]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mail.bwidawsk.net (Postfix) with ESMTPSA id AEA26123190; Thu, 31 May 2018 07:46:19 -0700 (PDT) Date: Thu, 31 May 2018 07:46:19 -0700 From: Ben Widawsky To: rgrimes@freebsd.org Cc: Warner Losh , 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> Mail-Followup-To: rgrimes@freebsd.org, Warner Losh , svn-src-head@freebsd.org, svn-src-all@freebsd.org, src-committers@freebsd.org References: <201805311423.w4VENXwY020239@repo.freebsd.org> <201805311442.w4VEg8c9077097@pdx.rh.CN85.dnsmgr.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <201805311442.w4VEg8c9077097@pdx.rh.CN85.dnsmgr.net> User-Agent: NeoMutt/20180323 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:54:02 -0000 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"