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