[src/trunk]: src/share/man/man3 Document __diagused and __debugused

[apb <apb%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/2ea04fe964ed
branches:  trunk
changeset: 790861:2ea04fe964ed
user:      apb <apb%NetBSD.org@localhost>
date:      Fri Oct 25 14:46:59 2013 +0000

description:
Document __diagused and __debugused

diffstat:

 share/man/man3/attribute.3 |  35 ++++++++++++++++++++++++++++++++++-
 1 files changed, 34 insertions(+), 1 deletions(-)

diffs (56 lines):

diff -r c9f8b68c1184 -r 2ea04fe964ed share/man/man3/attribute.3
--- a/share/man/man3/attribute.3        Fri Oct 25 14:46:35 2013 +0000
+++ b/share/man/man3/attribute.3        Fri Oct 25 14:46:59 2013 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: attribute.3,v 1.12 2013/10/25 14:41:08 apb Exp $
+.\" $NetBSD: attribute.3,v 1.13 2013/10/25 14:46:59 apb Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -48,6 +48,10 @@
 .Pp
 .Ic __used
 .Pp
+.Ic __diagused
+.Pp
+.Ic __debugused
+.Pp
 .Ic __packed
 .Pp
 .Fn __aligned "x"
@@ -166,6 +170,35 @@
 macro expands to an attribute that informs the compiler
 that a static variable or function is to be always retained
 in the object file even if it is unreferenced.
+.It Ic __diagused
+The
+.Ic __diagused
+macro expands to an attribute that informs the compiler
+that a variable or function is used only in diagnostic code,
+and may be unused in non-diagnostic code.
+.Pp
+In the kernel, variables that are used when DIAGNOSTIC is defined,
+but unused when DIAGNOSTIC is not defined, may be declared with
+__diagused.  In userland, variables that are used when NDEBUG is not
+defined, but unused when NDEBUG is defined, may be declared with
+__diagused.
+.Pp
+Variables used only in assert(3) or KASSERT(9) macros are likely
+candidates for being declared with __diagused.
+.It Ic __debugused
+The
+.Ic __debugused
+macro expands to an attribute that informs the compiler
+that a variable or function is used only in debug code,
+and may be unused in non-debug code.
+.Pp
+In either the kernel or userland, variables that are used when DEBUG
+is defined, but unused when DEBUG is not defined, may be declared with
+__debugused.
+.Pp
+In the kernel, variables used only in KDASSERT(9) macros are likely
+candidates for being declared with __debugused.  There is no
+established convention for the use of DEBUG in userland code.
 .It Ic __packed
 The
 .Ic __packed