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

[Bruce Evans]

On Sun, 2 Aug 2015, John-Mark Gurney wrote:

> Log:
>  mark this function as deprecated, and put the warning first, since I
>  doubt most people will read to the end...  Note the use of sys/cdefs.h
>  for pre-C11 compilers...

This function shouldn't be deprecated.  It is a kernel wrapper with a
good name for hiding the implementation detail or not-yet standard
interface _Static_assert().

CTASSERT() is the compile-time variant of KASSERT().  We intentionally
use KASSERT() instead of anything like the standard assert(3) since
we don't like the API or semantics of assert() and want one with
different design and implementation bugs.  I can't think of any use
for different semantics to _Static_assert(), but using CTASSERT()
retains flexibility.

<sys/cdefs.h> isn't a prerequisite for this function.  The correct
prerequisites for this function are already documented.  They are
<sys/param.h> and <sys/systm.h>.

>  I didn't included a note about being compatibile w/ userland since a
>  C11 feature should be obviously usable in userland...

If CTASSERT() is abused in userland, then the kernel environment must
be faked.

> Modified: head/share/man/man9/CTASSERT.9
> ==============================================================================
> --- head/share/man/man9/CTASSERT.9	Sun Aug  2 00:18:48 2015	(r286169)
> +++ head/share/man/man9/CTASSERT.9	Sun Aug  2 00:22:14 2015	(r286170)
> @@ -26,7 +26,7 @@
> .\"
> .\" $FreeBSD$
> .\"
> -.Dd July 30, 2015
> +.Dd August 1, 2015
> .Dt CTASSERT 9
> .Os
> .Sh NAME
> @@ -39,6 +39,15 @@
> .Sh DESCRIPTION
> The
> .Fn CTASSERT
> +macro is deprecated and the C11 standard
> +.Fn _Static_assert
> +should be used instead.
> +The header
> +.Fa sys/cdefs.h
> +should be included to provide compatibility for pre-C11 compilers.

_Static_assert() shoudn't be used instead, but when it is including
sys/cdefs.h isn' optional.  Then the documented prerequisites for this
function might not be needed for the replacement but in the kernel they
must be provided for other functions.

Some section 9 man pages, e.g., atomic.9, document a minimal
prerequisite like <sys/types.h>, but this sets a bad example and
inhibits adding conditional features like KASSERTS()s in atomic.h.
atomic.h is so low-level that you normally wouldn't want to bloat it
with assertions, but you might want to add them for debugging.  In
fact, it is a style bug for any kernel file to use the documented
prerequisite for the atomic functions.  <machine/atomic.h> is part of
the standard pollution in <sys/systm.h> and it is a style bug to not
depend on that.

sys/param.h is a documented prerequisite in 264 section 9 man pages
(at the source level; many more counting links).  sys/systm.h is in
only 34.  sys/types.h is in 41.

> +.Pp
> +The
> +.Fn CTASSERT
> macro evaluates
> .Fa expression
> at compile time and causes a compiler error if it is false.
> @@ -48,10 +57,6 @@ The
> macro is useful for asserting the size or alignment of important
> data structures and variables during compilation, which would
> otherwise cause the code to fail at run time.
> -.Pp
> -The
> -.Fn CTASSERT
> -macro is not usable in userland.

The CTASSERT() macro is still not usable in userland.  It is only abusable.
Its alternative _Static_assert() is usable, but most people won't read to
the beginning of this to find it here.

> .Sh EXAMPLES
> Assert that the size of the
> .Vt uuid

Bruce