diff options
Diffstat (limited to 'static/netbsd/man3/attribute.3')
| -rw-r--r-- | static/netbsd/man3/attribute.3 | 392 |
1 files changed, 392 insertions, 0 deletions
diff --git a/static/netbsd/man3/attribute.3 b/static/netbsd/man3/attribute.3 new file mode 100644 index 00000000..3ac665b4 --- /dev/null +++ b/static/netbsd/man3/attribute.3 @@ -0,0 +1,392 @@ +.\" $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. |