From owner-svn-src-all@freebsd.org Fri Jul 31 07:28:17 2015 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id E3C789AF050; Fri, 31 Jul 2015 07:28:17 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail105.syd.optusnet.com.au (mail105.syd.optusnet.com.au [211.29.132.249]) by mx1.freebsd.org (Postfix) with ESMTP id A12807F0; Fri, 31 Jul 2015 07:28:16 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from c211-30-166-197.carlnfd1.nsw.optusnet.com.au (c211-30-166-197.carlnfd1.nsw.optusnet.com.au [211.30.166.197]) by mail105.syd.optusnet.com.au (Postfix) with ESMTPS id 3882C1047463; Fri, 31 Jul 2015 17:28:12 +1000 (AEST) Date: Fri, 31 Jul 2015 17:28:12 +1000 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: John-Mark Gurney cc: Bruce Evans , src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r286103 - head/share/man/man9 In-Reply-To: <20150731070314.GY78154@funkthat.com> Message-ID: <20150731171611.O2162@besplex.bde.org> References: <201507310328.t6V3S3LC087650@repo.freebsd.org> <20150731152253.Y1843@besplex.bde.org> <20150731070314.GY78154@funkthat.com> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Optus-CM-Score: 0 X-Optus-CM-Analysis: v=2.1 cv=XMDNMlVE c=1 sm=1 tr=0 a=KA6XNC2GZCFrdESI5ZmdjQ==:117 a=PO7r1zJSAAAA:8 a=JzwRw_2MAAAA:8 a=kj9zAlcOel0A:10 a=AJbpanktw9WC98yC8TwA:9 a=CjuIK1q_8ugA:10 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 31 Jul 2015 07:28:18 -0000 On Fri, 31 Jul 2015, John-Mark Gurney wrote: > Bruce Evans wrote this message on Fri, Jul 31, 2015 at 16:21 +1000: >> On Fri, 31 Jul 2015, John-Mark Gurney wrote: >> >>> Log: >>> The implementation note isn't true anymore.. >>> >>> Not that anyone reads it, but those that do, remind them that this >>> isn't usable in userland... I can't wait till this doc is wrong.. >> >> It goes without saying that an API documented in a section 9 man page >> isn't usable in userland > > I think you mean that some API's are well documented in section 9 > and undocumented in section 3. For example, atomic(9) is used in > userland in such places as libthr, jemalloc, and more. Bug in these places. It is now clear that they should use C11 atomics. Both are very hard to understand even with documentation. The C11 ones are more complicate and the FreeBSD ones are more subject to change. >> In this case, it is obviously even more unusable in userland, because >> the documentation specifies including . That header is >> undocumented, but everyone should know that it it is kernel-only. > > Well, now I know.. it'd be nice to document it w/ an > ifndef _KERNEL/error line.. or at least a comment... or even in > the documentation... It should have had #error if !_KERNEL but it is apparently unusable without _KERNEL anyway. Applications can now use _Static_assert(condition, message) instead of rthe FreeBSDism CTASSERT(). _Static_assert() is in so it is available everywhere. Of course, it is undocumented like most things there, and it goes without saying that using it is a misuse since it is in the implementation namespace :-). It seems to be standard only in C++, with the spelling static_assert(). Bruce