From owner-svn-src-head@freebsd.org Thu May 31 14:23:34 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 37463FD262E; Thu, 31 May 2018 14:23:34 +0000 (UTC) (envelope-from imp@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id D412B68323; Thu, 31 May 2018 14:23:33 +0000 (UTC) (envelope-from imp@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id B36E11B5CF; Thu, 31 May 2018 14:23:33 +0000 (UTC) (envelope-from imp@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id w4VENXBX020240; Thu, 31 May 2018 14:23:33 GMT (envelope-from imp@FreeBSD.org) Received: (from imp@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w4VENXwY020239; Thu, 31 May 2018 14:23:33 GMT (envelope-from imp@FreeBSD.org) Message-Id: <201805311423.w4VENXwY020239@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: imp set sender to imp@FreeBSD.org using -f From: Warner Losh Date: Thu, 31 May 2018 14:23:33 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r334431 - head/share/man/man3 X-SVN-Group: head X-SVN-Commit-Author: imp X-SVN-Commit-Paths: head/share/man/man3 X-SVN-Commit-Revision: 334431 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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:23:34 -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). 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