ATTRIBUTE(3) | Library Functions Manual | ATTRIBUTE(3) |
attribute
—
#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);
__printflike
(fmtarg,
firstvararg);
__sysloglike
(fmtarg,
firstvararg);
NetBSD code should usually avoid direct
use of the __attribute__ or similar syntax provided by
specific compilers. Instead, NetBSD's
<sys/cdefs.h>
header file
provides several attribute macros in a namespace reserved for the
implementation (beginning with ‘__
’),
that expand to the appropriate syntax for the compiler that is in use.
__dead
__dead
,
certain optimizations are possible and warnings sensitive to the code flow
graph may be pruned. Obviously a __dead
function
can never have return type other than void.__pure
__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
__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
__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
__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
__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
__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.
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
__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.
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 established convention
for the use of DEBUG
in userland code.
__packed
__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 useful when dealing with data that is in a particular static format
on the disk, wire, or memory.__aligned
(x)__aligned
() macro expands to an attribute that
specifies the minimum alignment in bytes for a variable, structure field,
or function. In other words, the specified object should have an alignment
of at least x bytes, as opposed to the minimum
alignment requirements dictated by the architecture and the ABI. Possible
use cases include:
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.
__section
(section)__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.__read_mostly
__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
__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
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 yields nonzero.
__predict_false
__predict_false
expands to an attribute that
instructs the compiler to predict that a given branch will be likely
false. As programmers 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
.__printflike
(fmtarg,
firstvararg)__sysloglike
(fmtarg,
firstvararg)0
if the argument is a va_list.September 14, 2018 | NetBSD 9.2 |