.\" $NetBSD: attribute.3,v 1.18 2018/09/14 20:53:49 christos Exp $
.\"
.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Jukka Ruohonen.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd September 14, 2018
.Dt ATTRIBUTE 3
.Os
.Sh NAME
.Nm attribute
.Nd non-standard compiler attribute extensions
.Sh SYNOPSIS
.In sys/cdefs.h
.Pp
.Ic __dead
.Pp
.Ic __pure
.Pp
.Ic __constfunc
.Pp
.Ic __noinline
.Pp
.Ic __unused
.Pp
.Ic __used
.Pp
.Ic __diagused
.Pp
.Ic __debugused
.Pp
.Ic __packed
.Pp
.Fn __aligned "x"
.Fn __section "section"
.Pp
.Ic __read_mostly
.Pp
.Ic __cacheline_aligned
.Pp
.Fn __predict_true "exp"
.Pp
.Fn __predict_false "exp"
.Pp
.Fn __printflike "fmtarg" "firstvararg"
.Pp
.Fn __sysloglike "fmtarg" "firstvararg"
.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 ,
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
code should usually avoid direct use of the
.Em __attribute__
or similar syntax provided by specific compilers.
Instead,
.Nx Ap 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
Certain functions, such as
.Xr abort 3
and
.Xr exit 3 ,
can never return.
When such a function is declared with
.Ic __dead ,
certain optimizations are possible and warnings sensitive to the code flow graph
may be pruned.
Obviously a
.Ic __dead
function can never have return type other than
.Vt void .
.It Ic __pure
A
.Ic __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
.Ic __pure .
Many
.Xr math 3
functions satisfy the definition of a
.Ic __pure
function, at least in theory.
Other examples include
.Xr strlen 3
and
.Xr strcmp 3 .
.It Ic __constfunc
A
.Dq const function
is a stricter variant of
.Dq pure functions .
In addition to the restrictions of pure functions, a function declared with
.Ic __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
.Ic __constfunc .
The canonical example of a const function would be
.Xr abs 3 .
As with pure functions,
certain micro-optimizations are possible for functions declared with
.Ic __constfunc .
.It Ic __noinline
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
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
Marking an unused function with the
.Ic __unused
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 the compiler
that a static variable or function is to be always retained
in the object file even if it is unreferenced.
.It Ic __diagused
The
.Ic __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.
.Pp
In the kernel, variables that are used when
.Dv DIAGNOSTIC
is defined, but unused when
.Dv DIAGNOSTIC
is not defined, may be declared with
.Ic __diagused .
In userland, variables that are used when
.Dv NDEBUG
is not defined, but unused when
.Dv NDEBUG
is defined, may be declared with
.Ic __diagused .
.Pp
Variables used only in
.Xr assert 3
or
.Xr KASSERT 9
macros are likely candidates for being declared with
.Ic __diagused .
.It Ic __debugused
The
.Ic __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.
.Pp
In either the kernel or userland, variables that are used when
.Dv DEBUG
is defined, but unused when
.Dv DEBUG
is not defined, may be declared with
.Ic __debugused .
.Pp
In the kernel, variables used only in
.Xr KDASSERT 9
macros are likely candidates for being declared with
.Ic __debugused .
There is no established convention for the use of
.Dv DEBUG
in userland code.
.It Ic __packed
The
.Ic __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
.Vt struct
or
.Vt union ,
all variables therein are also packed.
The
.Ic __packed
macro is often useful when dealing with data that
is in a particular static format on the disk, wire, or memory.
.It Fn __aligned "x"
The
.Fn __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
.Fa x
bytes, as opposed to the minimum alignment requirements dictated
by the architecture and the
.Tn ABI .
Possible use cases include:
.Bl -bullet -offset indent
.It
Mixing assembly and C code.
.It
Dealing with hardware that may impose alignment requirements
greater than the architecture itself.
.It
Using instructions that may impose special alignment requirements.
Typical example would be alignment of frequently used objects along
processor cache lines.
.El
.Pp
Note that when used with functions, structures, or structure members,
.Fn __aligned
can only be used to increase the alignment.
If the macro is however used as part of a
.Vt typedef ,
the alignment can both increase and decrease.
Otherwise it is only possible to decrease the alignment
for variables and fields by using the
.Ic __packed
macro.
The effectiveness of
.Fn __aligned
is largely dependent on the linker.
The
.Xr __alignof__ 3
operator can be used to examine the alignment.
.It Fn __section "section"
The
.Fn __section
macro expands to an attribute that specifies a particular
.Fa section
to which a variable or function should be placed.
Normally the compiler places the generated objects to sections such as
.Dq data
or
.Dq text .
By using
.Fn __section ,
it is possible to override this behavior, perhaps in order to place
some variables into particular sections specific to unique hardware.
.It Ic __read_mostly
The
.Ic __read_mostly
macro uses
.Fn __section
to place a variable or function into the
.Dq .data.read_mostly
section of the (kernel)
.Xr elf 5 .
The use of
.Ic __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
.Ic __read_mostly
include variables that are initialized once,
read very often, and seldom written to.
.It Ic __cacheline_aligned
The
.Ic __cacheline_aligned
macro behaves like
.Ic __read_mostly ,
but the used section is
.Dq .data.cacheline_aligned
instead.
It also uses
.Fn __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
.Ic __cacheline_aligned
and
.Ic __read_mostly
are only available for the kernel.
.It Ic __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
.Dq 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.
.Pp
The macros
.Fn __predict_true
and
.Fn __predict_false
annotate the likelihood of whether
a branch will evaluate to true or false.
The rationale is to improve instruction pipelining.
Semantically
.Ic __predict_true
expects that the integral expression
.Fa exp
yields nonzero.
.It Ic __predict_false
The
.Ic __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
.Ic __predict_false
and
.Ic __predict_true .
.It Fn __printflike "fmtarg" "firstvararg"
Marks a function as taking printf-like arguments.
.Fa fmtarg
is the index of the format string in the argument list, and
.Fa firstvararg
is the index of the first item of the vararg list.
.It Fn __sysloglike "fmtarg" "firstvararg"
Marks a function as taking syslog-like arguments.
Allows use of the %m formatting code.
.Fa fmtarg
is the index of the format string in the argument list, and
.Fa firstvararg
is the index of the first item of the vararg list, or
.Dv 0
if the argument is a
.Ft va_list .
.El
.Sh SEE ALSO
.Xr clang 1 ,
.Xr gcc 1 ,
.Xr __builtin_object_size 3 ,
.Xr cdefs 3 ,
.Xr c 7
.Sh CAVEATS
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.