ATTRIBUTE(3)

ATTRIBUTE(3) | 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);

`__printflike`(fmtarg, firstvararg);

`__sysloglike`(fmtarg, firstvararg);

# 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 GNU Compiler Collection (GCC), and LLVM/Clang, use the __attribute__ syntax for such attributes, but different versions of the compilers support different attributes, and other compilers may use entirely different syntax.

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.

# ATTRIBUTES

`__dead`
  Certain functions, such as abort(3) and exit(3), can never return. When such a function is declared with `__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`
  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 function 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 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`
  The `__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`
  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 useful 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 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:
  - Mixing assembly and C code.
  - Dealing with hardware that may impose alignment requirements greater than the architecture itself.
  - 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.

`__section`(section)
  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.
`__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 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`
  The `__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)
  Marks a function as taking printf-like arguments. fmtarg is the index of the format string in the argument list, and firstvararg is the index of the first item of the vararg list.
`__sysloglike`(fmtarg, firstvararg)
  Marks a function as taking syslog-like arguments. Allows use of the %m formatting code. fmtarg is the index of the format string in the argument list, and firstvararg is the index of the first item of the vararg list, or `0` if the argument is a va_list.

# 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 portability is not a concern, use these macros sparsely and wisely.

September 14, 2018 | NetBSD 9.4