[src/trunk]: src/share/man/man3 Try to make this more compiler-neutral, and g...

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

details:   https://anonhg.NetBSD.org/src/rev/07a3cee0440d
branches:  trunk
changeset: 790858:07a3cee0440d
user:      apb <apb%NetBSD.org@localhost>
date:      Fri Oct 25 14:41:08 2013 +0000

description:
Try to make this more compiler-neutral, and give both GCC and LLVM/Clang
as examples.

diffstat:

 share/man/man3/attribute.3 |  66 +++++++++++++++++++++++++--------------------
 1 files changed, 37 insertions(+), 29 deletions(-)

diffs (131 lines):

diff -r 0b8665b70aa1 -r 07a3cee0440d share/man/man3/attribute.3
--- a/share/man/man3/attribute.3        Fri Oct 25 14:32:10 2013 +0000
+++ b/share/man/man3/attribute.3        Fri Oct 25 14:41:08 2013 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: attribute.3,v 1.11 2011/09/18 17:43:20 jym Exp $
+.\" $NetBSD: attribute.3,v 1.12 2013/10/25 14:41:08 apb Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,12 +27,12 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd December 19, 2010
+.Dd October 25, 2013
 .Dt ATTRIBUTE 3
 .Os
 .Sh NAME
 .Nm attribute
-.Nd non-standard GCC attribute extensions
+.Nd non-standard compiler attribute extensions
 .Sh SYNOPSIS
 .In sys/cdefs.h
 .Pp
@@ -61,30 +61,42 @@
 .Pp
 .Fn __predict_false "exp"
 .Sh DESCRIPTION
+As an extension to the C standard, some compilers allow non-standard
+attributes to be associated with functions, variables, or types, to
+modify some aspect of the way the compiler treats the associated item.
 The
 .Tn GNU
 Compiler Collection
-.Pq Tn GCC
-provides many extensions to the standard C language.
-Among these are the so-called attributes.
-In
+.Pq Tn GCC ,
+and
+.Tn LLVM/Clang ,
+use the
+.Em __attribute__
+syntax for such attributes,
+but different versions of the compilers support different attributes,
+and other compilers may use entirely different syntax.
+.Pp
 .Nx
-all attributes are provided in a restricted namespace.
-The described macros should be preferred instead of using the
-.Tn GCC's
+code should usually avoid direct use of the
 .Em __attribute__
-extension directly.
+or similar syntax provided by specific compilers.
+Instead,
+.Nx Ns 's
+.In sys/cdefs.h
+header file
+provides several attribute macros in a namespace
+reserved for the implementation (beginning with
+.Ql __ ) ,
+that expand to the appropriate syntax for the compiler that is in use.
 .Sh ATTRIBUTES
 .Bl -tag -width abc
 .It Ic __dead
-The
-.Xr gcc 1
-compiler knows that certain functions such as
+Certain functions, such as
 .Xr abort 3
 and
-.Xr exit 3
+.Xr exit 3 ,
 can never return any value.
-When such a function is equipped with
+When such a function is declared with
 .Ic __dead ,
 certain optimizations are possible.
 Obviously a
@@ -129,34 +141,29 @@
 certain micro-optimizations are possible for functions declared with
 .Ic __constfunc .
 .It Ic __noinline
-.Tn GCC
-is known for aggressive function inlining.
 Sometimes it is known that inlining is undesirable or that
 a function will perform incorrectly when inlined.
 The
 .Ic __noinline
 macro expands to a function attribute that prevents
-.Tn GCC
-for inlining the function, irrespective
-whether the function was declared with the
+the compiler from inlining the function, irrespective
+of whether the function was declared with the
 .Em inline
 keyword.
 The attribute takes precedence over all
 other compiler options related to inlining.
 .It Ic __unused
-In most
-.Tn GCC
-versions the common
-.Fl Wall
-flag enables warnings produced by functions that are defined but unused.
 Marking an unused function with the
 .Ic __unused
-macro inhibits these warnings.
+macro inhibits warnings that a function is defined but not used.
+Marking a variable with the
+.Ic __unused
+macro inhibits warnings that the variable is unused,
+or that it is set but never read.
 .It Ic __used
 The
 .Ic __used
-macro expands to an attribute that informs
-.Tn GCC
+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 __packed
@@ -300,6 +307,7 @@
 .Ic __predict_true .
 .El
 .Sh SEE ALSO
+.Xr clang 1 ,
 .Xr gcc 1 ,
 .Xr __builtin_object_size 3 ,
 .Xr cdefs 3 ,