1 /* ATTRIBUTE_* macros for using attributes in GCC and similar compilers 2 3 Copyright 2020-2021 Free Software Foundation, Inc. 4 5 This file is free software: you can redistribute it and/or modify 6 it under the terms of the GNU Lesser General Public License as 7 published by the Free Software Foundation; either version 2.1 of the 8 License, or (at your option) any later version. 9 10 This file is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU Lesser General Public License for more details. 14 15 You should have received a copy of the GNU Lesser General Public License 16 along with this program. If not, see <https://www.gnu.org/licenses/>. */ 17 18 /* Written by Paul Eggert. */ 19 20 /* Provide public ATTRIBUTE_* names for the private _GL_ATTRIBUTE_* 21 macros used within Gnulib. */ 22 23 /* These attributes can be placed in two ways: 24 - At the start of a declaration (i.e. even before storage-class 25 specifiers!); then they apply to all entities that are declared 26 by the declaration. 27 - Immediately after the name of an entity being declared by the 28 declaration; then they apply to that entity only. */ 29 30 #ifndef _GL_ATTRIBUTE_H 31 #define _GL_ATTRIBUTE_H 32 33 34 /* This file defines two types of attributes: 35 * C2x standard attributes. These have macro names that do not begin with 36 'ATTRIBUTE_'. 37 * Selected GCC attributes; see: 38 https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html 39 https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html 40 https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html 41 These names begin with 'ATTRIBUTE_' to avoid name clashes. */ 42 43 44 /* =============== Attributes for specific kinds of functions =============== */ 45 46 /* Attributes for functions that should not be used. */ 47 48 /* Warn if the entity is used. */ 49 /* Applies to: 50 - function, variable, 51 - struct, union, struct/union member, 52 - enumeration, enumeration item, 53 - typedef, 54 in C++ also: namespace, class, template specialization. */ 55 #define DEPRECATED _GL_ATTRIBUTE_DEPRECATED 56 57 /* If a function call is not optimized way, warn with MSG. */ 58 /* Applies to: functions. */ 59 #define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg) 60 61 /* If a function call is not optimized way, report an error with MSG. */ 62 /* Applies to: functions. */ 63 #define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg) 64 65 66 /* Attributes for memory-allocating functions. */ 67 68 /* The function returns a pointer to freshly allocated memory. */ 69 /* Applies to: functions. */ 70 #define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC 71 72 /* ATTRIBUTE_ALLOC_SIZE ((N)) - The Nth argument of the function 73 is the size of the returned memory block. 74 ATTRIBUTE_ALLOC_SIZE ((M, N)) - Multiply the Mth and Nth arguments 75 to determine the size of the returned memory block. */ 76 /* Applies to: function, pointer to function, function types. */ 77 #define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args) 78 79 /* ATTRIBUTE_DEALLOC (F, I) declares that the function returns pointers 80 that can be freed by passing them as the Ith argument to the 81 function F. 82 ATTRIBUTE_DEALLOC_FREE declares that the function returns pointers that 83 can be freed via 'free'; it can be used only after including <stdlib.h>. */ 84 /* Applies to: functions. Cannot be used on inline functions. */ 85 #define ATTRIBUTE_DEALLOC(f, i) _GL_ATTRIBUTE_DEALLOC(f, i) 86 #define ATTRIBUTE_DEALLOC_FREE _GL_ATTRIBUTE_DEALLOC_FREE 87 88 /* Attributes for variadic functions. */ 89 90 /* The variadic function expects a trailing NULL argument. 91 ATTRIBUTE_SENTINEL () - The last argument is NULL (requires C99). 92 ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL. */ 93 /* Applies to: functions. */ 94 #define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos) 95 96 97 /* ================== Attributes for compiler diagnostics ================== */ 98 99 /* Attributes that help the compiler diagnose programmer mistakes. 100 Some of them may also help for some compiler optimizations. */ 101 102 /* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) - 103 The STRING-INDEXth function argument is a format string of style 104 ARCHETYPE, which is one of: 105 printf, gnu_printf 106 scanf, gnu_scanf, 107 strftime, gnu_strftime, 108 strfmon, 109 or the same thing prefixed and suffixed with '__'. 110 If FIRST-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK 111 are suitable for the format string. */ 112 /* Applies to: functions. */ 113 #define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec) 114 115 /* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL. 116 ATTRIBUTE_NONNULL () - All pointer arguments must not be null. */ 117 /* Applies to: functions. */ 118 #define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args) 119 120 /* The function's return value is a non-NULL pointer. */ 121 /* Applies to: functions. */ 122 #define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL 123 124 /* Warn if the caller does not use the return value, 125 unless the caller uses something like ignore_value. */ 126 /* Applies to: function, enumeration, class. */ 127 #define NODISCARD _GL_ATTRIBUTE_NODISCARD 128 129 130 /* Attributes that disable false alarms when the compiler diagnoses 131 programmer "mistakes". */ 132 133 /* Do not warn if the entity is not used. */ 134 /* Applies to: 135 - function, variable, 136 - struct, union, struct/union member, 137 - enumeration, enumeration item, 138 - typedef, 139 in C++ also: class. */ 140 #define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED 141 142 /* The contents of a character array is not meant to be NUL-terminated. */ 143 /* Applies to: struct/union members and variables that are arrays of element 144 type '[[un]signed] char'. */ 145 #define ATTRIBUTE_NONSTRING _GL_ATTRIBUTE_NONSTRING 146 147 /* Do not warn if control flow falls through to the immediately 148 following 'case' or 'default' label. */ 149 /* Applies to: Empty statement (;), inside a 'switch' statement. */ 150 #define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH 151 152 153 /* ================== Attributes for debugging information ================== */ 154 155 /* Attributes regarding debugging information emitted by the compiler. */ 156 157 /* Omit the function from stack traces when debugging. */ 158 /* Applies to: function. */ 159 #define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL 160 161 /* Make the entity visible to debuggers etc., even with '-fwhole-program'. */ 162 /* Applies to: functions, variables. */ 163 #define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE 164 165 166 /* ========== Attributes that mainly direct compiler optimizations ========== */ 167 168 /* The function does not throw exceptions. */ 169 /* Applies to: functions. */ 170 #define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW 171 172 /* Do not inline the function. */ 173 /* Applies to: functions. */ 174 #define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE 175 176 /* Always inline the function, and report an error if the compiler 177 cannot inline. */ 178 /* Applies to: function. */ 179 #define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE 180 181 /* It is OK for a compiler to omit duplicate calls with the same arguments. 182 This attribute is safe for a function that neither depends on 183 nor affects observable state, and always returns exactly once - 184 e.g., does not loop forever, and does not call longjmp. 185 (This attribute is stricter than ATTRIBUTE_PURE.) */ 186 /* Applies to: functions. */ 187 #define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST 188 189 /* It is OK for a compiler to omit duplicate calls with the same 190 arguments if observable state is not changed between calls. 191 This attribute is safe for a function that does not affect 192 observable state, and always returns exactly once. 193 (This attribute is looser than ATTRIBUTE_CONST.) */ 194 /* Applies to: functions. */ 195 #define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE 196 197 /* The function is rarely executed. */ 198 /* Applies to: functions. */ 199 #define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD 200 201 /* If called from some other compilation unit, the function executes 202 code from that unit only by return or by exception handling, 203 letting the compiler optimize that unit more aggressively. */ 204 /* Applies to: functions. */ 205 #define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF 206 207 /* For struct members: The member has the smallest possible alignment. 208 For struct, union, class: All members have the smallest possible alignment, 209 minimizing the memory required. */ 210 /* Applies to: struct members, struct, union, 211 in C++ also: class. */ 212 #define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED 213 214 215 /* ================ Attributes that make invalid code valid ================ */ 216 217 /* Attributes that prevent fatal compiler optimizations for code that is not 218 fully ISO C compliant. */ 219 220 /* Pointers to the type may point to the same storage as pointers to 221 other types, thus disabling strict aliasing optimization. */ 222 /* Applies to: types. */ 223 #define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS 224 225 226 #endif /* _GL_ATTRIBUTE_H */ 227