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 modify it 6 under the terms of the GNU General Public License as published 7 by the Free Software Foundation; either version 3 of the License, or 8 (at your option) any later version. 9 10 This program 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 GNU 13 General Public License for more details. 14 15 You should have received a copy of the GNU 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 80/* Attributes for variadic functions. */ 81 82/* The variadic function expects a trailing NULL argument. 83 ATTRIBUTE_SENTINEL () - The last argument is NULL. 84 ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL. */ 85/* Applies to: functions. */ 86#define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos) 87 88 89/* ================== Attributes for compiler diagnostics ================== */ 90 91/* Attributes that help the compiler diagnose programmer mistakes. 92 Some of them may also help for some compiler optimizations. */ 93 94/* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) - 95 The STRING-INDEXth function argument is a format string of style 96 ARCHETYPE, which is one of: 97 printf, gnu_printf 98 scanf, gnu_scanf, 99 strftime, gnu_strftime, 100 strfmon, 101 or the same thing prefixed and suffixed with '__'. 102 If FIRST-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK 103 are suitable for the format string. */ 104/* Applies to: functions. */ 105#define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec) 106 107/* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL. 108 ATTRIBUTE_NONNULL () - All pointer arguments must not be null. */ 109/* Applies to: functions. */ 110#define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args) 111 112/* The function's return value is a non-NULL pointer. */ 113/* Applies to: functions. */ 114#define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL 115 116/* Warn if the caller does not use the return value, 117 unless the caller uses something like ignore_value. */ 118/* Applies to: function, enumeration, class. */ 119#define NODISCARD _GL_ATTRIBUTE_NODISCARD 120 121 122/* Attributes that disable false alarms when the compiler diagnoses 123 programmer "mistakes". */ 124 125/* Do not warn if the entity is not used. */ 126/* Applies to: 127 - function, variable, 128 - struct, union, struct/union member, 129 - enumeration, enumeration item, 130 - typedef, 131 in C++ also: class. */ 132#define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED 133 134/* The contents of a character array is not meant to be NUL-terminated. */ 135/* Applies to: struct/union members and variables that are arrays of element 136 type '[[un]signed] char'. */ 137#define ATTRIBUTE_NONSTRING _GL_ATTRIBUTE_NONSTRING 138 139/* Do not warn if control flow falls through to the immediately 140 following 'case' or 'default' label. */ 141/* Applies to: Empty statement (;), inside a 'switch' statement. */ 142#define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH 143 144 145/* ================== Attributes for debugging information ================== */ 146 147/* Attributes regarding debugging information emitted by the compiler. */ 148 149/* Omit the function from stack traces when debugging. */ 150/* Applies to: function. */ 151#define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL 152 153/* Make the entity visible to debuggers etc., even with '-fwhole-program'. */ 154/* Applies to: functions, variables. */ 155#define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE 156 157 158/* ========== Attributes that mainly direct compiler optimizations ========== */ 159 160/* The function does not throw exceptions. */ 161/* Applies to: functions. */ 162#define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW 163 164/* Do not inline the function. */ 165/* Applies to: functions. */ 166#define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE 167 168/* Always inline the function, and report an error if the compiler 169 cannot inline. */ 170/* Applies to: function. */ 171#define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE 172 173/* The function does not affect observable state, and always returns a value. 174 Compilers can omit duplicate calls with the same arguments if 175 observable state is not changed between calls. (This attribute is 176 looser than ATTRIBUTE_CONST.) */ 177/* Applies to: functions. */ 178#define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE 179 180/* The function neither depends on nor affects observable state, 181 and always returns a value. Compilers can omit duplicate calls with 182 the same arguments. (This attribute is stricter than ATTRIBUTE_PURE.) */ 183/* Applies to: functions. */ 184#define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST 185 186/* The function is rarely executed. */ 187/* Applies to: functions. */ 188#define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD 189 190/* If called from some other compilation unit, the function executes 191 code from that unit only by return or by exception handling, 192 letting the compiler optimize that unit more aggressively. */ 193/* Applies to: functions. */ 194#define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF 195 196/* For struct members: The member has the smallest possible alignment. 197 For struct, union, class: All members have the smallest possible alignment, 198 minimizing the memory required. */ 199/* Applies to: struct members, struct, union, 200 in C++ also: class. */ 201#define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED 202 203 204/* ================ Attributes that make invalid code valid ================ */ 205 206/* Attributes that prevent fatal compiler optimizations for code that is not 207 fully ISO C compliant. */ 208 209/* Pointers to the type may point to the same storage as pointers to 210 other types, thus disabling strict aliasing optimization. */ 211/* Applies to: types. */ 212#define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS 213 214 215#endif /* _GL_ATTRIBUTE_H */ 216