Module Name: src
Committed By: apb
Date: Fri Oct 25 14:41:08 UTC 2013
Modified Files:
src/share/man/man3: attribute.3
Log Message:
Try to make this more compiler-neutral, and give both GCC and LLVM/Clang
as examples.
To generate a diff of this commit:
cvs rdiff -u -r1.11 -r1.12 src/share/man/man3/attribute.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man3/attribute.3
diff -u src/share/man/man3/attribute.3:1.11 src/share/man/man3/attribute.3:1.12
--- src/share/man/man3/attribute.3:1.11 Sun Sep 18 17:43:20 2011
+++ src/share/man/man3/attribute.3 Fri Oct 25 14:41:08 2013
@@ -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 @@ As with pure functions,
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 @@ and
.Ic __predict_true .
.El
.Sh SEE ALSO
+.Xr clang 1 ,
.Xr gcc 1 ,
.Xr __builtin_object_size 3 ,
.Xr cdefs 3 ,
