lib/attribute.h

   1 /* ATTRIBUTE_* macros for using attributes in GCC and similar compilers
   2
   3    Copyright 2020-2024 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    * C23 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 /* This file uses _GL_ATTRIBUTE_ALLOC_SIZE, _GL_ATTRIBUTE_ALWAYS_INLINE,
  45    _GL_ATTRIBUTE_ARTIFICIAL, _GL_ATTRIBUTE_COLD, _GL_ATTRIBUTE_CONST,
  46    _GL_ATTRIBUTE_DEALLOC, _GL_ATTRIBUTE_DEPRECATED, _GL_ATTRIBUTE_ERROR,
  47    _GL_ATTRIBUTE_WARNING, _GL_ATTRIBUTE_EXTERNALLY_VISIBLE,
  48    _GL_ATTRIBUTE_FALLTHROUGH, _GL_ATTRIBUTE_FORMAT, _GL_ATTRIBUTE_LEAF,
  49    _GL_ATTRIBUTE_MALLOC, _GL_ATTRIBUTE_MAY_ALIAS, _GL_ATTRIBUTE_MAYBE_UNUSED,
  50    _GL_ATTRIBUTE_NODISCARD, _GL_ATTRIBUTE_NOINLINE, _GL_ATTRIBUTE_NONNULL,
  51    _GL_ATTRIBUTE_NONSTRING, _GL_ATTRIBUTE_NOTHROW, _GL_ATTRIBUTE_PACKED,
  52    _GL_ATTRIBUTE_PURE, _GL_ATTRIBUTE_RETURNS_NONNULL,
  53    _GL_ATTRIBUTE_SENTINEL.  */
  54 #if !_GL_CONFIG_H_INCLUDED
  55  #error "Please include config.h first."
  56 #endif
  57
  58
  59 /* =============== Attributes for specific kinds of functions =============== */
  60
  61 /* Attributes for functions that should not be used.  */
  62
  63 /* Warn if the entity is used.  */
  64 /* Applies to:
  65      - function, variable,
  66      - struct, union, struct/union member,
  67      - enumeration, enumeration item,
  68      - typedef,
  69    in C++ also: namespace, class, template specialization.  */
  70 #define DEPRECATED _GL_ATTRIBUTE_DEPRECATED
  71
  72 /* If a function call is not optimized way, warn with MSG.  */
  73 /* Applies to: functions.  */
  74 #define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg)
  75
  76 /* If a function call is not optimized way, report an error with MSG.  */
  77 /* Applies to: functions.  */
  78 #define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg)
  79
  80
  81 /* Attributes for memory-allocating functions.  */
  82
  83 /* The function returns a pointer to freshly allocated memory.  */
  84 /* Applies to: functions.  */
  85 #define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC
  86
  87 /* ATTRIBUTE_ALLOC_SIZE ((N)) - The Nth argument of the function
  88    is the size of the returned memory block.
  89    ATTRIBUTE_ALLOC_SIZE ((M, N)) - Multiply the Mth and Nth arguments
  90    to determine the size of the returned memory block.  */
  91 /* Applies to: function, pointer to function, function types.  */
  92 #define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args)
  93
  94 /* ATTRIBUTE_DEALLOC (F, I) declares that the function returns pointers
  95    that can be freed by passing them as the Ith argument to the
  96    function F.
  97    ATTRIBUTE_DEALLOC_FREE declares that the function returns pointers that
  98    can be freed via 'free'; it can be used only after declaring 'free'.  */
  99 /* Applies to: functions.  Cannot be used on inline functions.  */
 100 #define ATTRIBUTE_DEALLOC(f, i) _GL_ATTRIBUTE_DEALLOC(f, i)
 101 #define ATTRIBUTE_DEALLOC_FREE _GL_ATTRIBUTE_DEALLOC_FREE
 102
 103 /* Attributes for variadic functions.  */
 104
 105 /* The variadic function expects a trailing NULL argument.
 106    ATTRIBUTE_SENTINEL () - The last argument is NULL (requires C99).
 107    ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL.  */
 108 /* Applies to: functions.  */
 109 #define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos)
 110
 111
 112 /* ================== Attributes for compiler diagnostics ================== */
 113
 114 /* Attributes that help the compiler diagnose programmer mistakes.
 115    Some of them may also help for some compiler optimizations.  */
 116
 117 /* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) -
 118    The STRING-INDEXth function argument is a format string of style
 119    ARCHETYPE, which is one of:
 120      printf, gnu_printf
 121      scanf, gnu_scanf,
 122      strftime, gnu_strftime,
 123      strfmon,
 124    or the same thing prefixed and suffixed with '__'.
 125    If FIRST-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK
 126    are suitable for the format string.  */
 127 /* Applies to: functions.  */
 128 #define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec)
 129
 130 /* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL.
 131    ATTRIBUTE_NONNULL () - All pointer arguments must not be null.  */
 132 /* Applies to: functions.  */
 133 #define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args)
 134
 135 /* The function's return value is a non-NULL pointer.  */
 136 /* Applies to: functions.  */
 137 #define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL
 138
 139 /* Warn if the caller does not use the return value,
 140    unless the caller uses something like ignore_value.  */
 141 /* Applies to: function, enumeration, class.  */
 142 #define NODISCARD _GL_ATTRIBUTE_NODISCARD
 143
 144
 145 /* Attributes that disable false alarms when the compiler diagnoses
 146    programmer "mistakes".  */
 147
 148 /* Do not warn if the entity is not used.  */
 149 /* Applies to:
 150      - function, variable,
 151      - struct, union, struct/union member,
 152      - enumeration, enumeration item,
 153      - typedef,
 154    in C++ also: class.  */
 155 #define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED
 156
 157 /* The contents of a character array is not meant to be NUL-terminated.  */
 158 /* Applies to: struct/union members and variables that are arrays of element
 159    type '[[un]signed] char'.  */
 160 #define ATTRIBUTE_NONSTRING _GL_ATTRIBUTE_NONSTRING
 161
 162 /* Do not warn if control flow falls through to the immediately
 163    following 'case' or 'default' label.  */
 164 /* Applies to: Empty statement (;), inside a 'switch' statement.  */
 165 #define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH
 166
 167
 168 /* ================== Attributes for debugging information ================== */
 169
 170 /* Attributes regarding debugging information emitted by the compiler.  */
 171
 172 /* Omit the function from stack traces when debugging.  */
 173 /* Applies to: function.  */
 174 #define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL
 175
 176 /* Make the entity visible to debuggers etc., even with '-fwhole-program'.  */
 177 /* Applies to: functions, variables.  */
 178 #define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE
 179
 180
 181 /* ========== Attributes that mainly direct compiler optimizations ========== */
 182
 183 /* The function does not throw exceptions.  */
 184 /* Applies to: functions.  */
 185 /* After a function's parameter list, this attribute must come first, before
 186    other attributes.  */
 187 #define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW
 188
 189 /* Do not inline the function.  */
 190 /* Applies to: functions.  */
 191 #define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE
 192
 193 /* Always inline the function, and report an error if the compiler
 194    cannot inline.  */
 195 /* Applies to: function.  */
 196 #define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE
 197
 198 /* It is OK for a compiler to omit duplicate calls with the same arguments.
 199    This attribute is safe for a function that neither depends on
 200    nor affects observable state, and always returns exactly once -
 201    e.g., does not loop forever, and does not call longjmp.
 202    (This attribute is stricter than ATTRIBUTE_PURE.)  */
 203 /* Applies to: functions.  */
 204 #define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
 205
 206 /* It is OK for a compiler to omit duplicate calls with the same
 207    arguments if observable state is not changed between calls.
 208    This attribute is safe for a function that does not affect
 209    observable state, and always returns exactly once.
 210    (This attribute is looser than ATTRIBUTE_CONST.)  */
 211 /* Applies to: functions.  */
 212 #define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE
 213
 214 /* The function is rarely executed.  */
 215 /* Applies to: functions.  */
 216 #define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD
 217
 218 /* If called from some other compilation unit, the function executes
 219    code from that unit only by return or by exception handling,
 220    letting the compiler optimize that unit more aggressively.  */
 221 /* Applies to: functions.  */
 222 #define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF
 223
 224 /* For struct members: The member has the smallest possible alignment.
 225    For struct, union, class: All members have the smallest possible alignment,
 226    minimizing the memory required.  */
 227 /* Applies to: struct members, struct, union,
 228    in C++ also: class.  */
 229 #define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED
 230
 231
 232 /* ================ Attributes that make invalid code valid ================ */
 233
 234 /* Attributes that prevent fatal compiler optimizations for code that is not
 235    fully ISO C compliant.  */
 236
 237 /* Pointers to the type may point to the same storage as pointers to
 238    other types, thus disabling strict aliasing optimization.  */
 239 /* Applies to: types.  */
 240 #define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS
 241
 242
 243 #endif /* _GL_ATTRIBUTE_H */