/* C2X standard attributes have macro names that do not begin with
'ATTRIBUTE_'. */
-/* Tells that the entity is deprecated. A use of the entity produces a
- warning. */
+/* Warn if the entity is used. */
/* Applies to:
- function, variable,
- struct, union, struct/union member,
in C++ also: namespace, class, template specialization. */
#define DEPRECATED _GL_ATTRIBUTE_DEPRECATED
-/* Tells that it's intentional that the control flow can go on to the
- immediately following 'case' or 'default' label. */
+/* Do not warn if control flow falls through to the immediately
+ following 'case' or 'default' label. */
/* Applies to: Empty statement (;), inside a 'switch' statement. */
#define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH
-/* Tells that it's OK if the entity is not used. No "is not used" warning
- shall be produced for the entity. */
+/* Do not warn if the entity is not used. */
/* Applies to:
- function, variable,
- struct, union, struct/union member,
in C++ also: class. */
#define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED
-/* Tells that it is important for the caller of a function to inspect its
- return value. Discarding the return value produces a warning. */
+/* Warn if the caller does not use the return value,
+ unless the caller uses something like ignore_value. */
/* Applies to: function, enumeration, class. */
#define NODISCARD _GL_ATTRIBUTE_NODISCARD
https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html
These names begin with 'ATTRIBUTE_' to avoid name clashes. */
-/* Used for memory allocation functions.
- ATTRIBUTE_ALLOC_SIZE ((n)) specifies that the function returns a block
- of memory whose size is the n-th argument (n counts from 1).
- ATTRIBUTE_ALLOC_SIZE ((m, n)) specifies that the function returns a block
- of memory whose size is the product of the m-th argument and the n-th
- argument. */
-/* Applies to: functions, pointers to functions, function types */
+/* ATTRIBUTE_ALLOC_SIZE ((N)) - The Nth argument of the function
+ is the size of the returned memory block.
+ ATTRIBUTE_ALLOC_SIZE ((M, N)) - Multiply the Mth and Nth arguments
+ to determine the size of the returned memory block. */
+/* Applies to: function, pointer to function, function types. */
#define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args)
-/* Forces the function to be inlined. Results in an error if the compiler
- cannot honour the inlining request. */
-/* Applies to: functions */
+/* Always inline the function, and report an error if the compiler
+ cannot inline. */
+/* Applies to: function. */
#define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE
-/* Used for small inline functions.
- Specifies that the function should be omitted from stack traces. */
-/* Applies to: functions */
+/* Omit the function from stack traces when debugging. */
+/* Applies to: function. */
#define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL
-/* Used to denote the result of manual profiling.
- Specifies that the function is unlikely to be executed. */
-/* Applies to: functions */
+/* The function is rarely executed. */
+/* Applies to: functions. */
#define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD
-/* Used on functions that don't inspect memory and don't do side effects
- and don't invoke random behaviour.
- Specifies that the compiler is allowed to replace multiple invocations
- of the function with the same arguments with a single invocation. */
-/* Applies to: functions */
+/* The function neither depends on nor affects observable state,
+ and always returns a value. Compilers can omit duplicate calls with
+ the same arguments. (This attribute is stricter than ATTRIBUTE_PURE.) */
+/* Applies to: functions. */
#define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
-/* Same as DEPRECATED, above. */
-#define ATTRIBUTE_DEPRECATED _GL_ATTRIBUTE_DEPRECATED
-
-/* Used on functions that should not be called.
- ATTRIBUTE_ERROR (MSG) specifies that the compiler is allowed to produce
- an error when an invocation of the function cannot be optimized away.
- The error message will include MSG. */
-/* Applies to: functions */
+/* If a function call is not optimized way, report an error with MSG. */
+/* Applies to: functions. */
#define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg)
-/* Used on functions or variables that shall persist across the
- '-fwhole-program' optimization. */
-/* Applies to: functions */
+/* Make the entity visible to debuggers etc., even with '-fwhole-program'. */
+/* Applies to: functions, variables. */
#define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE
-/* Used on functions that consume arguments according to a format string.
- ATTRIBUTE_FORMAT ((FORMAT-STRING-TYPE, FORMAT-STRING-ARGUMENT-NUMBER,
- FIRST-CONSUMED-ARGUMENT-NUMBER))
- specifies that the argument FORMAT-STRING-ARGUMENT-NUMBER is a format string.
- The syntax of this format string is described by FORMAT-STRING-TYPE, namely
- one of:
+/* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) -
+ The STRING-INDEXth function argument is a format string of style
+ ARCHETYPE, which is one of:
printf, gnu_printf
scanf, gnu_scanf,
strftime, gnu_strftime,
strfmon,
or the same thing prefixed and suffixed with '__'.
- If FIRST-CONSUMED-ARGUMENT-NUMBER is not 0, the compiler checks that the
- arguments starting at FIRST-CONSUMED-ARGUMENT-NUMBER are suitable for the
- format string. */
-/* Applies to: functions */
+ If FIRST-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK
+ are suitable for the format string. */
+/* Applies to: functions. */
#define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec)
-/* Specifies that the function does not - directly or indirectly - invoke any
- code from the current compilation unit.
- This attribute allows the compiler to do more aggressive optimizations on
- the current compilation unit. */
-/* Applies to: functions */
+/* If called from some other compilation unit, the function executes
+ code from that unit only by return or by exception handling,
+ letting the compiler optimize that unit more aggressively. */
+/* Applies to: functions. */
#define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF
-/* Specifies that pointers to the type may point to the same storage as
- pointers to other types.
- This attribute disables compiler optimizations that are based on
- "no aliasing" assumptions for the given type. */
-/* Applies to: types */
+/* Pointers to the type may point to the same storage as pointers to
+ other types, thus disabling strict aliasing optimization. */
+/* Applies to: types. */
#define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS
-/* Used for memory allocation functions.
- Specifies that the function returns a pointer to freshly allocated
- memory. */
-/* Applies to: functions */
+/* The function returns a pointer to freshly allocated memory. */
+/* Applies to: functions. */
#define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC
-/* Specifies that the function should not be inlined. */
-/* Applies to: functions */
+/* Do not inline the function. */
+/* Applies to: functions. */
#define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE
-/* ATTRIBUTE_NONNULL ((ARGNO1, ARGNO2, ...)) specifies that the argument number
- ARGNO1, the argument number ARGNO2, etc. must not be NULL pointers. */
-/* Applies to: functions */
+/* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL.
+ ATTRIBUTE_NONNULL () - All pointer arguments must not be null. */
+/* Applies to: functions. */
#define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args)
-/* Specifies that the contents of a character array is not meant to be NUL-
- terminated. */
+/* The contents of a character array is not meant to be NUL-terminated. */
/* Applies to: struct/union members and variables that are arrays of element
type '[[un]signed] char'. */
#define ATTRIBUTE_NONSTRING _GL_ATTRIBUTE_NONSTRING
-/* Specifies that the function does not throw exceptions. */
-/* Applies to: functions */
+/* The function does not throw exceptions. */
+/* Applies to: functions. */
#define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW
-/* For struct members: Specifies that the struct member shall have the minimum
- possible alignment.
- For struct, union, class: Specifies that all members shall have the minimum
- possible alignment, thus minimizing the memory size of the type. */
+/* For struct members: The member has the smallest possible alignment.
+ For struct, union, class: All members have the smallest possible alignment,
+ minimizing the memory required. */
/* Applies to: struct members, struct, union,
in C++ also: class. */
#define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED
-/* Used on functions that don't do side effects and don't invoke random
- behaviour.
- Specifies that the compiler is allowed to replace multiple invocations
- of the function with the same arguments with a single invocation, if
- there are no memory stores in between the invocations. */
-/* Applies to: functions */
+/* The function does not affect observable state, and always returns a value.
+ Compilers can omit duplicate calls with the same arguments if
+ observable state is not changed between calls. (This attribute is
+ looser than ATTRIBUTE_CONST.) */
+/* Applies to: functions. */
#define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE
-/* Specifies that the function's return value is a non-NULL pointer. */
-/* Applies to: functions */
+/* The function's return value is a non-NULL pointer. */
+/* Applies to: functions. */
#define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL
-/* Used on variadic functions.
- ATTRIBUTE_SENTINEL () and ATTRIBUTE_SENTINEL (0) specify that the last
- argument must be NULL.
- ATTRIBUTE_SENTINEL (n) specifies that the (n+1)st argument from the end
- must be NULL. */
-/* Applies to: functions */
+/* The variadic function expects a trailing NULL argument.
+ ATTRIBUTE_SENTINEL () - The last argument is NULL.
+ ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL. */
+/* Applies to: functions. */
#define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos)
-/* Used on functions that should not be called.
- ATTRIBUTE_WARNING (MSG) specifies that the compiler is allowed to produce
- a warning when an invocation of the function cannot be optimized away.
- The warning message will include MSG. */
-/* Applies to: functions */
+/* If a function call is not optimized way, warn with MSG. */
+/* Applies to: functions. */
#define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg)