Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


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.

NetBSD 10.99                  September 14, 2018                  NetBSD 10.99