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