1.\" $NetBSD: attribute.3,v 1.18 2018/09/14 20:53:49 christos Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jukka Ruohonen. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd September 14, 2018 31.Dt ATTRIBUTE 3 32.Os 33.Sh NAME 34.Nm attribute 35.Nd non-standard compiler attribute extensions 36.Sh SYNOPSIS 37.In sys/cdefs.h 38.Pp 39.Ic __dead 40.Pp 41.Ic __pure 42.Pp 43.Ic __constfunc 44.Pp 45.Ic __noinline 46.Pp 47.Ic __unused 48.Pp 49.Ic __used 50.Pp 51.Ic __diagused 52.Pp 53.Ic __debugused 54.Pp 55.Ic __packed 56.Pp 57.Fn __aligned "x" 58.Fn __section "section" 59.Pp 60.Ic __read_mostly 61.Pp 62.Ic __cacheline_aligned 63.Pp 64.Fn __predict_true "exp" 65.Pp 66.Fn __predict_false "exp" 67.Pp 68.Fn __printflike "fmtarg" "firstvararg" 69.Pp 70.Fn __sysloglike "fmtarg" "firstvararg" 71.Sh DESCRIPTION 72As an extension to the C standard, some compilers allow non-standard 73attributes to be associated with functions, variables, or types, to 74modify some aspect of the way the compiler treats the associated item. 75The 76.Tn GNU 77Compiler Collection 78.Pq Tn GCC , 79and 80.Tn LLVM/Clang , 81use the 82.Em __attribute__ 83syntax for such attributes, 84but different versions of the compilers support different attributes, 85and other compilers may use entirely different syntax. 86.Pp 87.Nx 88code should usually avoid direct use of the 89.Em __attribute__ 90or similar syntax provided by specific compilers. 91Instead, 92.Nx Ap s 93.In sys/cdefs.h 94header file 95provides several attribute macros in a namespace 96reserved for the implementation (beginning with 97.Ql __ ) , 98that expand to the appropriate syntax for the compiler that is in use. 99.Sh ATTRIBUTES 100.Bl -tag -width abc 101.It Ic __dead 102Certain functions, such as 103.Xr abort 3 104and 105.Xr exit 3 , 106can never return. 107When such a function is declared with 108.Ic __dead , 109certain optimizations are possible and warnings sensitive to the code flow graph 110may be pruned. 111Obviously a 112.Ic __dead 113function can never have return type other than 114.Vt void . 115.It Ic __pure 116A 117.Ic __pure 118function is defined to be one that has no effects except 119the return value, which is assumed to depend only on the 120function parameters and/or global variables. 121Any access to parameters and/or global variables must also be read-only. 122A function that depends on volatile memory, or other comparable 123system resource that can change between two consecutive calls, 124can never be 125.Ic __pure . 126Many 127.Xr math 3 128functions satisfy the definition of a 129.Ic __pure 130function, at least in theory. 131Other examples include 132.Xr strlen 3 133and 134.Xr strcmp 3 . 135.It Ic __constfunc 136A 137.Dq const function 138is a stricter variant of 139.Dq pure functions . 140In addition to the restrictions of pure functions, a function declared with 141.Ic __constfunc 142can never access global variables nor take pointers as parameters. 143The return value of these functions must depend 144only on the passed-by-value parameters. 145Note also that a function that calls non-const functions can not be 146.Ic __constfunc . 147The canonical example of a const function would be 148.Xr abs 3 . 149As with pure functions, 150certain micro-optimizations are possible for functions declared with 151.Ic __constfunc . 152.It Ic __noinline 153Sometimes it is known that inlining is undesirable or that 154a function will perform incorrectly when inlined. 155The 156.Ic __noinline 157macro expands to a function attribute that prevents 158the compiler from inlining the function, irrespective 159of whether the function was declared with the 160.Em inline 161keyword. 162The attribute takes precedence over all 163other compiler options related to inlining. 164.It Ic __unused 165Marking an unused function with the 166.Ic __unused 167macro inhibits warnings that a function is defined but not used. 168Marking a variable with the 169.Ic __unused 170macro inhibits warnings that the variable is unused, 171or that it is set but never read. 172.It Ic __used 173The 174.Ic __used 175macro expands to an attribute that informs the compiler 176that a static variable or function is to be always retained 177in the object file even if it is unreferenced. 178.It Ic __diagused 179The 180.Ic __diagused 181macro expands to an attribute that informs the compiler 182that a variable or function is used only in diagnostic code, 183and may be unused in non-diagnostic code. 184.Pp 185In the kernel, variables that are used when 186.Dv DIAGNOSTIC 187is defined, but unused when 188.Dv DIAGNOSTIC 189is not defined, may be declared with 190.Ic __diagused . 191In userland, variables that are used when 192.Dv NDEBUG 193is not defined, but unused when 194.Dv NDEBUG 195is defined, may be declared with 196.Ic __diagused . 197.Pp 198Variables used only in 199.Xr assert 3 200or 201.Xr KASSERT 9 202macros are likely candidates for being declared with 203.Ic __diagused . 204.It Ic __debugused 205The 206.Ic __debugused 207macro expands to an attribute that informs the compiler 208that a variable or function is used only in debug code, 209and may be unused in non-debug code. 210.Pp 211In either the kernel or userland, variables that are used when 212.Dv DEBUG 213is defined, but unused when 214.Dv DEBUG 215is not defined, may be declared with 216.Ic __debugused . 217.Pp 218In the kernel, variables used only in 219.Xr KDASSERT 9 220macros are likely candidates for being declared with 221.Ic __debugused . 222There is no established convention for the use of 223.Dv DEBUG 224in userland code. 225.It Ic __packed 226The 227.Ic __packed 228macro expands to an attribute that forces a variable or 229structure field to have the smallest possible alignment, 230potentially disregarding architecture specific alignment requirements. 231The smallest possible alignment is effectively one byte 232for variables and one bit for fields. 233If specified on a 234.Vt struct 235or 236.Vt union , 237all variables therein are also packed. 238The 239.Ic __packed 240macro is often useful when dealing with data that 241is in a particular static format on the disk, wire, or memory. 242.It Fn __aligned "x" 243The 244.Fn __aligned 245macro expands to an attribute that specifies the minimum alignment 246in bytes for a variable, structure field, or function. 247In other words, the specified object should have an alignment of at least 248.Fa x 249bytes, as opposed to the minimum alignment requirements dictated 250by the architecture and the 251.Tn ABI . 252Possible use cases include: 253.Bl -bullet -offset indent 254.It 255Mixing assembly and C code. 256.It 257Dealing with hardware that may impose alignment requirements 258greater than the architecture itself. 259.It 260Using instructions that may impose special alignment requirements. 261Typical example would be alignment of frequently used objects along 262processor cache lines. 263.El 264.Pp 265Note that when used with functions, structures, or structure members, 266.Fn __aligned 267can only be used to increase the alignment. 268If the macro is however used as part of a 269.Vt typedef , 270the alignment can both increase and decrease. 271Otherwise it is only possible to decrease the alignment 272for variables and fields by using the 273.Ic __packed 274macro. 275The effectiveness of 276.Fn __aligned 277is largely dependent on the linker. 278The 279.Xr __alignof__ 3 280operator can be used to examine the alignment. 281.It Fn __section "section" 282The 283.Fn __section 284macro expands to an attribute that specifies a particular 285.Fa section 286to which a variable or function should be placed. 287Normally the compiler places the generated objects to sections such as 288.Dq data 289or 290.Dq text . 291By using 292.Fn __section , 293it is possible to override this behavior, perhaps in order to place 294some variables into particular sections specific to unique hardware. 295.It Ic __read_mostly 296The 297.Ic __read_mostly 298macro uses 299.Fn __section 300to place a variable or function into the 301.Dq .data.read_mostly 302section of the (kernel) 303.Xr elf 5 . 304The use of 305.Ic __read_mostly 306allows infrequently modified data to be grouped together; 307it is expected that the cachelines of rarely and frequently modified 308data structures are this way separated. 309Candidates for 310.Ic __read_mostly 311include variables that are initialized once, 312read very often, and seldom written to. 313.It Ic __cacheline_aligned 314The 315.Ic __cacheline_aligned 316macro behaves like 317.Ic __read_mostly , 318but the used section is 319.Dq .data.cacheline_aligned 320instead. 321It also uses 322.Fn __aligned 323to set the minimum alignment into a predefined coherency unit. 324This should ensure that frequently used data structures are 325aligned on cacheline boundaries. 326Both 327.Ic __cacheline_aligned 328and 329.Ic __read_mostly 330are only available for the kernel. 331.It Ic __predict_true 332A branch is generally defined to be a conditional execution of a 333program depending on whether a certain flow control mechanism is altered. 334Typical example would be a 335.Dq if-then-else 336sequence used in high-level languages or 337a jump instruction used in machine-level code. 338A branch prediction would then be defined as an 339attempt to guess whether a conditional branch will be taken. 340.Pp 341The macros 342.Fn __predict_true 343and 344.Fn __predict_false 345annotate the likelihood of whether 346a branch will evaluate to true or false. 347The rationale is to improve instruction pipelining. 348Semantically 349.Ic __predict_true 350expects that the integral expression 351.Fa exp 352yields nonzero. 353.It Ic __predict_false 354The 355.Ic __predict_false 356expands to an attribute that instructs the compiler 357to predict that a given branch will be likely false. 358As programmers are notoriously bad at predicting 359the likely behavior of their code, profiling and 360empirical evidence should precede the use of 361.Ic __predict_false 362and 363.Ic __predict_true . 364.It Fn __printflike "fmtarg" "firstvararg" 365Marks a function as taking printf-like arguments. 366.Fa fmtarg 367is the index of the format string in the argument list, and 368.Fa firstvararg 369is the index of the first item of the vararg list. 370.It Fn __sysloglike "fmtarg" "firstvararg" 371Marks a function as taking syslog-like arguments. 372Allows use of the %m formatting code. 373.Fa fmtarg 374is the index of the format string in the argument list, and 375.Fa firstvararg 376is the index of the first item of the vararg list, or 377.Dv 0 378if the argument is a 379.Ft va_list . 380.El 381.Sh SEE ALSO 382.Xr clang 1 , 383.Xr gcc 1 , 384.Xr __builtin_object_size 3 , 385.Xr cdefs 3 , 386.Xr c 7 387.Sh CAVEATS 388It goes without saying that portable applications 389should steer clear from non-standard extensions specific 390to any given compiler. 391Even when portability is not a concern, 392use these macros sparsely and wisely. 393