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

[Bruce Evans]

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

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.
Only the following places in userland include it:

contrib/ipfilter (17 files)

# Seems to be unused compatibility mistakes.  Never actually included.
contrib/ntp/libparse/Makefile.am
contrib/ntp/libparse/Makefile.in
contrib/ntp/CommitLog-4.1.0
contrib/ntp/CommitLog

contrib/top/Changes (log of when it was used for Pyramid in 1987)

# Closely related to this commit.  vis.c is ifdefed to use CTASSERT().
# The ifdef is very convoluted, ugly and of course broken.  All systems
# except NetBSD are assumed to have CTASSERT().  Probably no system
# except FreeBSD has it (that is the broken part).  But the ifdef is
# especially ugly for FreeBSD.  It documents the detail that you just
# removed -- that the CTASSERT() in <sys/systm.h> only works in the
# kernel.  So vis.c doesn't use the kernel version.  It provides its
# own version.  This begins badly with '#ifdef CTASSERT'.  CTASSERT
# can only be defined if some system provides it as namespace pollution.
# Then the definition of CTASSERT seems to be the old FreeBSD one --
# the one that doesn't really work.  But it doesn't really work just
# as well everywhere.  Only it being in <sys/systm.h> prevents it being
# used in userland.
#
# This mess of ifdefs takes 24 lines.  22 for the ifdef, 1 line for
# formatting, and 1 line to actually use CTASSERT().
contrib/libc-vis/vis.c

Your change may be incorrect due to a similar mess of ifdefs for
defining CTASSERT in the kernel.  It is defined in terms of
_Static_assert, and _Static_assert is defined in a mess if ifdefs in
<sys/cdefs.h>.  I think these ifdefs are just broken in all cases for
old compilers instead of only in rare cases.  For gcc before 4.6,
the ifdef reduces to using __COUNTER__ as the second variable if
__COUNTER__ is supported, else nothing.  So for the undocumented
subset of compilers that support __COUNTER__ all cases work, and
for the complementary subset no cases work (the macro is null).
This is incompatible with old versions of the macro, where there
were no ifdefs and most cases worked.

The implementation still has the bug of not parenthesizing the args
except in 1 place.

# Probably OK since for the kernel:
cddl/contrib/opensolaris/common/ctf/ctf_impl.h
cddl/contrib/dtracetoolkit/Bin/swapinfo.d
cddl/contrib/dtracetoolkit/Mem/swapinfo.d
cddl/contrib/dtracetoolkit/Man/man1m/swapinfo.d.1m

# OK since for the kernel (shared file with _KERNEL ifdefs):
lib/libc/gmon/mcount.c

# Probably OK since for the kernel (shared file with _KERNEL ifdefs):
lib/libmd/md5c.c

# Looks like kernel support:
usr.sbin/ndiscvt/windrv_stub.c

# Just a rotted comment (pointer to where something no longer is in the kernel):
usr.sbin/pciconf/cap.c
sbin/hastd/activemap.c

# Generate include of <sys/systm.h>:
usr.sbin/config/mkmakefile.c

# Undef _KERNEL ifdef:
usr.sbin/makefs/ffs/ffs_bswap.c

# Not checked:
tools/regression/kthread/kld/kthrdlk.c
tools/regression/net80211/ccmp/test_ccmp.c
tools/regression/net80211/tkip/test_tkip.c
tools/regression/net80211/wep/test_wep.c
tools/regression/redzone9/redzone.c
tools/tools/kttcp/sys/kttcp.c
tools/tools/vhba/vhba.h

share/man/man9 (34 files)

# Kernelish:
share/examples/kld/dyn_sysctl/dyn_sysctl.c
share/examples/kld/syscall/module/syscall.c
share/examples/kld/random_adaptor/random_adaptor_example.c
share/examples/kld/firmware/fwconsumer/fw_consumer.c
share/examples/kld/cdev/module/cdev.c
share/examples/kld/cdev/module/cdevmod.c
share/examples/drivers/make_device_driver.sh
share/examples/drivers/make_pseudo_driver.sh

Summary: userland has very little abuse of <sys/systm.h>.  It has related
errors in 3 files:
- ugliness in in contrib/libc-vis/vis.c
- rotted comments in usr.sbin/pciconf/cap.c and sbin/hastd/activemap.c.

Bruce