ATTRIBUTE(3) BSD Library Functions Manual ATTRIBUTE(3)
attribute -- non-standard GCC attribute extensions
The GNU Compiler Collection (GCC) provides many extensions to the standard C language. Among these are the so-called attributes. In NetBSD
all attributes are provided in a restricted namespace. The described macros should be preferred instead of using the GCC's __attribute__
The gcc(1) compiler knows that certain functions such as abort(3) and exit(3) can never return any value. When such a function is
equipped with __dead, certain optimizations are possible. Obviously a __dead function can never have return type other than void.
A __pure function is defined to be one that has no effects except the return value, which is assumed to depend only on the function
parameters and/or global variables. Any access to parameters and/or global variables must also be read-only. A function that depends
on volatile memory, or other comparable system resource that can change between two consecutive calls, can never be __pure. Many
math(3) functions satisfy the definition of a __pure function, at least in theory. Other examples include strlen(3) and strcmp(3).
A ``const function'' is a stricter variant of ``pure functions''. In addition to the restrictions of pure functions, a function
declared with __constfunc can never access global variables nor take pointers as parameters. The return value of these functions must
depend only on the passed-by-value parameters. Note also that a function that calls non-const functions can not be __constfunc. The
canonical example of a const function would be abs(3). As with pure functions, certain micro-optimizations are possible for functions
declared with __constfunc.
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 __noinline macro expands to a function attribute that prevents GCC for inlining the function, irrespec-
tive whether the function was declared with the inline keyword. The attribute takes precedence over all other compiler options related
In most GCC versions the common -Wall flag enables warnings produced by functions that are defined but unused. Marking an unused func-
tion with the __unused macro inhibits these warnings.
The __used macro expands to an attribute that informs GCC that a static variable or function is to be always retained in the object file
even if it is unreferenced.
The __packed macro expands to an attribute that forces a variable or structure field to have the smallest possible alignment, poten-
tially disregarding architecture specific alignment requirements. The smallest possible alignment is effectively one byte for variables
and one bit for fields. If specified on a struct or union, all variables therein are also packed. The __packed macro is often useful
when dealing with data that is in a particular static format on the disk, wire, or memory.
The __aligned() macro expands to an attribute that specifies the minimum alignment in bytes for a variable, structure field, or func-
tion. In other words, the specified object should have an alignment of at least x bytes, as opposed to the minimum alignment require-
ments dictated by the architecture and the ABI. Possible use cases include:
o Mixing assembly and C code.
o Dealing with hardware that may impose alignment requirements greater than the architecture itself.
o Using instructions that may impose special alignment requirements. Typical example would be alignment of frequently used
objects along processor cache lines.
Note that when used with functions, structures, or structure members, __aligned() can only be used to increase the alignment. If the
macro is however used as part of a typedef, the alignment can both increase and decrease. Otherwise it is only possible to decrease the
alignment for variables and fields by using the __packed macro. The effectiveness of __aligned() is largely dependent on the linker.
The __alignof__(3) operator can be used to examine the alignment.
The __section() macro expands to an attribute that specifies a particular section to which a variable or function should be placed.
Normally the compiler places the generated objects to sections such as ``data'' or ``text''. By using __section(), it is possible to
override this behavior, perhaps in order to place some variables into particular sections specific to unique hardware.
The __read_mostly macro uses __section() to place a variable or function into the ``.data.read_mostly'' section of the (kernel) elf(5).
The use of __read_mostly allows infrequently modified data to be grouped together; it is expected that the cachelines of rarely and fre-
quently modified data structures are this way separated. Candidates for __read_mostly include variables that are initialized once, read
very often, and seldom written to.
The __cacheline_aligned macro behaves like __read_mostly, but the used section is ``.data.cacheline_aligned'' instead. It also uses
__aligned() to set the minimum alignment into a predefined coherency unit. This should ensure that frequently used data structures are
aligned on cacheline boundaries. Both __cacheline_aligned and __read_mostly are only available for the kernel.
A branch is generally defined to be a conditional execution of a program depending on whether a certain flow control mechanism is
altered. Typical example would be a ``if-then-else'' sequence used in high-level languages or a jump instruction used in machine-level
code. A branch prediction would then be defined as an attempt to guess whether a conditional branch will be taken.
The macros __predict_true() and __predict_false() annotate the likelihood of whether a branch will evaluate to true or false. The
rationale is to improve instruction pipelining. Semantically __predict_true expects that the integral expression exp equals 1.
The __predict_false expands to an attribute that instructs the compiler to predict that a given branch will be likely false. As pro-
grammers are notoriously bad at predicting the likely behavior of their code, profiling and empirical evidence should precede the use of
__predict_false and __predict_true.
gcc(1), __builtin_object_size(3), cdefs(3), c(7)
It goes without saying that portable applications should steer clear from non-standard extensions specific to any given compiler. Even when
portability is not a concern, use these macros sparsely and wisely.
December 19, 2010 BSD