1.\" $NetBSD: attribute.3,v 1.11 2011/09/18 17:43:20 jym 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 December 19, 2010 31.Dt ATTRIBUTE 3 32.Os 33.Sh NAME 34.Nm attribute 35.Nd non-standard GCC 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 __packed 52.Pp 53.Fn __aligned "x" 54.Fn __section "section" 55.Pp 56.Ic __read_mostly 57.Pp 58.Ic __cacheline_aligned 59.Pp 60.Fn __predict_true "exp" 61.Pp 62.Fn __predict_false "exp" 63.Sh DESCRIPTION 64The 65.Tn GNU 66Compiler Collection 67.Pq Tn GCC 68provides many extensions to the standard C language. 69Among these are the so-called attributes. 70In 71.Nx 72all attributes are provided in a restricted namespace. 73The described macros should be preferred instead of using the 74.Tn GCC's 75.Em __attribute__ 76extension directly. 77.Sh ATTRIBUTES 78.Bl -tag -width abc 79.It Ic __dead 80The 81.Xr gcc 1 82compiler knows that certain functions such as 83.Xr abort 3 84and 85.Xr exit 3 86can never return any value. 87When such a function is equipped with 88.Ic __dead , 89certain optimizations are possible. 90Obviously a 91.Ic __dead 92function can never have return type other than 93.Vt void . 94.It Ic __pure 95A 96.Ic __pure 97function is defined to be one that has no effects except 98the return value, which is assumed to depend only on the 99function parameters and/or global variables. 100Any access to parameters and/or global variables must also be read-only. 101A function that depends on volatile memory, or other comparable 102system resource that can change between two consecutive calls, 103can never be 104.Ic __pure . 105Many 106.Xr math 3 107functions satisfy the definition of a 108.Ic __pure 109function, at least in theory. 110Other examples include 111.Xr strlen 3 112and 113.Xr strcmp 3 . 114.It Ic __constfunc 115A 116.Dq const function 117is a stricter variant of 118.Dq pure functions . 119In addition to the restrictions of pure functions, a function declared with 120.Ic __constfunc 121can never access global variables nor take pointers as parameters. 122The return value of these functions must depend 123only on the passed-by-value parameters. 124Note also that a function that calls non-const functions can not be 125.Ic __constfunc . 126The canonical example of a const function would be 127.Xr abs 3 . 128As with pure functions, 129certain micro-optimizations are possible for functions declared with 130.Ic __constfunc . 131.It Ic __noinline 132.Tn GCC 133is known for aggressive function inlining. 134Sometimes it is known that inlining is undesirable or that 135a function will perform incorrectly when inlined. 136The 137.Ic __noinline 138macro expands to a function attribute that prevents 139.Tn GCC 140for inlining the function, irrespective 141whether the function was declared with the 142.Em inline 143keyword. 144The attribute takes precedence over all 145other compiler options related to inlining. 146.It Ic __unused 147In most 148.Tn GCC 149versions the common 150.Fl Wall 151flag enables warnings produced by functions that are defined but unused. 152Marking an unused function with the 153.Ic __unused 154macro inhibits these warnings. 155.It Ic __used 156The 157.Ic __used 158macro expands to an attribute that informs 159.Tn GCC 160that a static variable or function is to be always retained 161in the object file even if it is unreferenced. 162.It Ic __packed 163The 164.Ic __packed 165macro expands to an attribute that forces a variable or 166structure field to have the smallest possible alignment, 167potentially disregarding architecture specific alignment requirements. 168The smallest possible alignment is effectively one byte 169for variables and one bit for fields. 170If specified on a 171.Vt struct 172or 173.Vt union , 174all variables therein are also packed. 175The 176.Ic __packed 177macro is often useful when dealing with data that 178is in a particular static format on the disk, wire, or memory. 179.It Fn __aligned "x" 180The 181.Fn __aligned 182macro expands to an attribute that specifies the minimum alignment 183in bytes for a variable, structure field, or function. 184In other words, the specified object should have an alignment of at least 185.Fa x 186bytes, as opposed to the minimum alignment requirements dictated 187by the architecture and the 188.Tn ABI . 189Possible use cases include: 190.Bl -bullet -offset indent 191.It 192Mixing assembly and C code. 193.It 194Dealing with hardware that may impose alignment requirements 195greater than the architecture itself. 196.It 197Using instructions that may impose special alignment requirements. 198Typical example would be alignment of frequently used objects along 199processor cache lines. 200.El 201.Pp 202Note that when used with functions, structures, or structure members, 203.Fn __aligned 204can only be used to increase the alignment. 205If the macro is however used as part of a 206.Vt typedef , 207the alignment can both increase and decrease. 208Otherwise it is only possible to decrease the alignment 209for variables and fields by using the 210.Ic __packed 211macro. 212The effectiveness of 213.Fn __aligned 214is largely dependent on the linker. 215The 216.Xr __alignof__ 3 217operator can be used to examine the alignment. 218.It Fn __section "section" 219The 220.Fn __section 221macro expands to an attribute that specifies a particular 222.Fa section 223to which a variable or function should be placed. 224Normally the compiler places the generated objects to sections such as 225.Dq data 226or 227.Dq text . 228By using 229.Fn __section , 230it is possible to override this behavior, perhaps in order to place 231some variables into particular sections specific to unique hardware. 232.It Ic __read_mostly 233The 234.Ic __read_mostly 235macro uses 236.Fn __section 237to place a variable or function into the 238.Dq .data.read_mostly 239section of the (kernel) 240.Xr elf 5 . 241The use of 242.Ic __read_mostly 243allows infrequently modified data to be grouped together; 244it is expected that the cachelines of rarely and frequently modified 245data structures are this way separated. 246Candidates for 247.Ic __read_mostly 248include variables that are initialized once, 249read very often, and seldom written to. 250.It Ic __cacheline_aligned 251The 252.Ic __cacheline_aligned 253macro behaves like 254.Ic __read_mostly , 255but the used section is 256.Dq .data.cacheline_aligned 257instead. 258It also uses 259.Fn __aligned 260to set the minimum alignment into a predefined coherency unit. 261This should ensure that frequently used data structures are 262aligned on cacheline boundaries. 263Both 264.Ic __cacheline_aligned 265and 266.Ic __read_mostly 267are only available for the kernel. 268.It Ic __predict_true 269A branch is generally defined to be a conditional execution of a 270program depending on whether a certain flow control mechanism is altered. 271Typical example would be a 272.Dq if-then-else 273sequence used in high-level languages or 274a jump instruction used in machine-level code. 275A branch prediction would then be defined as an 276attempt to guess whether a conditional branch will be taken. 277.Pp 278The macros 279.Fn __predict_true 280and 281.Fn __predict_false 282annotate the likelihood of whether 283a branch will evaluate to true or false. 284The rationale is to improve instruction pipelining. 285Semantically 286.Ic __predict_true 287expects that the integral expression 288.Fa exp 289equals 1. 290.It Ic __predict_false 291The 292.Ic __predict_false 293expands to an attribute that instructs the compiler 294to predict that a given branch will be likely false. 295As programmers are notoriously bad at predicting 296the likely behavior of their code, profiling and 297empirical evidence should precede the use of 298.Ic __predict_false 299and 300.Ic __predict_true . 301.El 302.Sh SEE ALSO 303.Xr gcc 1 , 304.Xr __builtin_object_size 3 , 305.Xr cdefs 3 , 306.Xr c 7 307.Sh CAVEATS 308It goes without saying that portable applications 309should steer clear from non-standard extensions specific 310to any given compiler. 311Even when portability is not a concern, 312use these macros sparsely and wisely. 313