attribute(3)
- NetBSD Manual Pages
ATTRIBUTE(3) NetBSD Library Functions Manual ATTRIBUTE(3)
NAME
attribute -- non-standard compiler attribute extensions
SYNOPSIS
#include <sys/cdefs.h>
__dead
__pure
__constfunc
__noinline
__unused
__used
__diagused
__debugused
__packed
__aligned(x);
__section(section);
__read_mostly
__cacheline_aligned
__predict_true(exp);
__predict_false(exp);
DESCRIPTION
As an extension to the C standard, some compilers allow non-standard
attributes to be associated with functions, variables, or types, to mod-
ify some aspect of the way the compiler treats the associated item. The
GNU Compiler Collection (GCC), and LLVM/Clang, use the __attribute__ syn-
tax for such attributes, but different versions of the compilers support
different attributes, and other compilers may use entirely different syn-
tax.
NetBSD code should usually avoid direct use of the __attribute__ or simi-
lar syntax provided by specific compilers. Instead, NetBSD's
<sys/cdefs.h> header file provides several attribute macros in a names-
pace reserved for the implementation (beginning with `__'), that expand
to the appropriate syntax for the compiler that is in use.
ATTRIBUTES
__dead
Certain functions, such as abort(3) and exit(3), can never return
any value. When such a function is declared with __dead, certain
optimizations are possible. Obviously a __dead function can never
have return type other than void.
__pure
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).
__constfunc
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.
__noinline
Sometimes it is known that inlining is undesirable or that a func-
tion will perform incorrectly when inlined. The __noinline macro
expands to a function attribute that prevents the compiler from
inlining the function, irrespective of whether the function was
declared with the inline keyword. The attribute takes precedence
over all other compiler options related to inlining.
__unused
Marking an unused function with the __unused macro inhibits warnings
that a function is defined but not used. Marking a variable with
the __unused macro inhibits warnings that the variable is unused, or
that it is set but never read.
__used
The __used 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.
__diagused
The __diagused macro expands to an attribute that informs the com-
piler that a variable or function is used only in diagnostic code,
and may be unused in non-diagnostic code.
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.
Variables used only in assert(3) or KASSERT(9) macros are likely
candidates for being declared with __diagused.
__debugused
The __debugused macro expands to an attribute that informs the com-
piler that a variable or function is used only in debug code, and
may be unused in non-debug code.
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.
In the kernel, variables used only in KDASSERT(9) macros are likely
candidates for being declared with __debugused. There is no estab-
lished convention for the use of DEBUG in userland code.
__packed
The __packed macro expands to an attribute that forces a variable or
structure field to have the smallest possible alignment, potentially
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 use-
ful when dealing with data that is in a particular static format on
the disk, wire, or memory.
__aligned(x)
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:
· Mixing assembly and C code.
· Dealing with hardware that may impose alignment require-
ments greater than the architecture itself.
· Using instructions that may impose special alignment
requirements. Typical example would be alignment of fre-
quently used objects along processor cache lines.
Note that when used with functions, structures, or structure mem-
bers, __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 depen-
dent on the linker. The __alignof__(3) operator can be used to
examine the alignment.
__section(section)
The __section() macro expands to an attribute that specifies a par-
ticular 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.
__read_mostly
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 frequently modified data structures are this way separated.
Candidates for __read_mostly include variables that are initialized
once, read very often, and seldom written to.
__cacheline_aligned
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.
__predict_true
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 like-
lihood 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 yields
nonzero.
__predict_false
The __predict_false expands to an attribute that instructs the com-
piler 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.
SEE ALSO
clang(1), gcc(1), __builtin_object_size(3), cdefs(3), c(7)
CAVEATS
It goes without saying that portable applications should steer clear from
non-standard extensions specific to any given compiler. Even when porta-
bility is not a concern, use these macros sparsely and wisely.
NetBSD 7.1.1 October 25, 2013 NetBSD 7.1.1
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.