svn commit: r286103 - head/share/man/man9

[Bruce Evans]

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 <sys/systm.h>.  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 <sys/cdefs.h>
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