]dnl There is no _GL_ATTRIBUTE_ALIGNED; use stdalign's _Alignas instead.
[
+/* _GL_ATTRIBUTE_ALLOC_SIZE ((N)) declares that the Nth argument of the function
+ is the size of the returned memory block.
+ _GL_ATTRIBUTE_ALLOC_SIZE ((M, N)) declares that the Mth argument multiplied
+ by the Nth argument of the function is the size of the returned memory block.
+ */
+/* Applies to: function, pointer to function, function types. */
#if _GL_HAS_ATTRIBUTE (alloc_size)
# define _GL_ATTRIBUTE_ALLOC_SIZE(args) __attribute__ ((__alloc_size__ args))
#else
# define _GL_ATTRIBUTE_ALLOC_SIZE(args)
#endif
+/* _GL_ATTRIBUTE_ALWAYS_INLINE tells that the compiler should always inline the
+ function and report an error if it cannot do so. */
+/* Applies to: function. */
#if _GL_HAS_ATTRIBUTE (always_inline)
# define _GL_ATTRIBUTE_ALWAYS_INLINE __attribute__ ((__always_inline__))
#else
# define _GL_ATTRIBUTE_ALWAYS_INLINE
#endif
+/* _GL_ATTRIBUTE_ARTIFICIAL declares that the function is not important to show
+ in stack traces when debugging. The compiler should omit the function from
+ stack traces. */
+/* Applies to: function. */
#if _GL_HAS_ATTRIBUTE (artificial)
# define _GL_ATTRIBUTE_ARTIFICIAL __attribute__ ((__artificial__))
#else
# define _GL_ATTRIBUTE_ARTIFICIAL
#endif
+/* _GL_ATTRIBUTE_COLD declares that the function is rarely executed. */
+/* Applies to: functions. */
/* Avoid __attribute__ ((cold)) on MinGW; see thread starting at
<https://lists.gnu.org/r/emacs-devel/2019-04/msg01152.html>.
Also, Oracle Studio 12.6 requires 'cold' not '__cold__'. */
# define _GL_ATTRIBUTE_COLD
#endif
+/* _GL_ATTRIBUTE_CONST declares that it is OK for a compiler to omit duplicate
+ calls to the function with the same arguments.
+ This attribute is safe for a function that neither depends on nor affects
+ observable state, and always returns exactly once - e.g., does not loop
+ forever, and does not call longjmp.
+ (This attribute is stricter than _GL_ATTRIBUTE_PURE.) */
+/* Applies to: functions. */
#if _GL_HAS_ATTRIBUTE (const)
# define _GL_ATTRIBUTE_CONST __attribute__ ((__const__))
#else
# define _GL_ATTRIBUTE_CONST
#endif
-/* _GL_ATTRIBUTE_DEALLOC (F, I) is for functions returning pointers
+/* _GL_ATTRIBUTE_DEALLOC (F, I) declares that the function returns pointers
that can be freed by passing them as the Ith argument to the
- function F. _GL_ATTRIBUTE_DEALLOC_FREE is for functions that
- return pointers that can be freed via 'free'; it can be used
- only after including stdlib.h. These macros cannot be used on
- inline functions. */
+ function F.
+ _GL_ATTRIBUTE_DEALLOC_FREE declares that the function returns pointers that
+ can be freed via 'free'; it can be used only after including <stdlib.h>. */
+/* Applies to: functions. Cannot be used on inline functions. */
#if _GL_GNUC_PREREQ (11, 0)
# define _GL_ATTRIBUTE_DEALLOC(f, i) __attribute__ ((__malloc__ (f, i)))
#else
#endif
#define _GL_ATTRIBUTE_DEALLOC_FREE _GL_ATTRIBUTE_DEALLOC (free, 1)
+/* _GL_ATTRIBUTE_DEPRECATED: Declares that an entity is deprecated.
+ The compiler may warn if the entity is used. */
+/* Applies to:
+ - function, variable,
+ - struct, union, struct/union member,
+ - enumeration, enumeration item,
+ - typedef,
+ in C++ also: namespace, class, template specialization. */
#if _GL_HAS_C_ATTRIBUTE (deprecated)
# define _GL_ATTRIBUTE_DEPRECATED [[__deprecated__]]
#elif _GL_HAS_ATTRIBUTE (deprecated)
# define _GL_ATTRIBUTE_DEPRECATED
#endif
+/* _GL_ATTRIBUTE_ERROR(msg) requests an error if a function is called and
+ the function call is not optimized away.
+ _GL_ATTRIBUTE_WARNING(msg) requests a warning if a function is called and
+ the function call is not optimized away. */
+/* Applies to: functions. */
#if _GL_HAS_ATTRIBUTE (error)
# define _GL_ATTRIBUTE_ERROR(msg) __attribute__ ((__error__ (msg)))
# define _GL_ATTRIBUTE_WARNING(msg) __attribute__ ((__warning__ (msg)))
# define _GL_ATTRIBUTE_WARNING(msg)
#endif
+/* _GL_ATTRIBUTE_EXTERNALLY_VISIBLE declares that the entity should remain
+ visible to debuggers etc., even with '-fwhole-program'. */
+/* Applies to: functions, variables. */
#if _GL_HAS_ATTRIBUTE (externally_visible)
# define _GL_ATTRIBUTE_EXTERNALLY_VISIBLE __attribute__ ((externally_visible))
#else
# define _GL_ATTRIBUTE_EXTERNALLY_VISIBLE
#endif
-/* FALLTHROUGH is special, because it always expands to something. */
+/* _GL_ATTRIBUTE_FALLTHROUGH declares that it is not a programming mistake if
+ the control flow falls through to the immediately following 'case' or
+ 'default' label. The compiler should not warn in this case. */
+/* Applies to: Empty statement (;), inside a 'switch' statement. */
+/* Always expands to something. */
#if _GL_HAS_C_ATTRIBUTE (fallthrough)
# define _GL_ATTRIBUTE_FALLTHROUGH [[__fallthrough__]]
#elif _GL_HAS_ATTRIBUTE (fallthrough)
# define _GL_ATTRIBUTE_FALLTHROUGH ((void) 0)
#endif
+/* _GL_ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK))
+ declares that 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-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK
+ are suitable for the format string. */
+/* Applies to: functions. */
#if _GL_HAS_ATTRIBUTE (format)
# define _GL_ATTRIBUTE_FORMAT(spec) __attribute__ ((__format__ spec))
#else
# define _GL_ATTRIBUTE_FORMAT(spec)
#endif
+/* _GL_ATTRIBUTE_LEAF declares that if the function is called from some other
+ compilation unit, it executes code from that unit only by return or by
+ exception handling. This declaration lets the compiler optimize that unit
+ more aggressively. */
+/* Applies to: functions. */
#if _GL_HAS_ATTRIBUTE (leaf)
# define _GL_ATTRIBUTE_LEAF __attribute__ ((__leaf__))
#else
# define _GL_ATTRIBUTE_LEAF
#endif
+/* _GL_ATTRIBUTE_MALLOC declares that the function returns a pointer to freshly
+ allocated memory. */
+/* Applies to: functions. */
#if _GL_HAS_ATTRIBUTE (malloc)
# define _GL_ATTRIBUTE_MALLOC __attribute__ ((__malloc__))
#else
# define _GL_ATTRIBUTE_MALLOC
#endif
+/* _GL_ATTRIBUTE_MAY_ALIAS declares that pointers to the type may point to the
+ same storage as pointers to other types. Thus this declaration disables
+ strict aliasing optimization. */
+/* Applies to: types. */
/* Oracle Studio 12.6 mishandles may_alias despite __has_attribute OK. */
#if _GL_HAS_ATTRIBUTE (may_alias) && !defined __SUNPRO_C
# define _GL_ATTRIBUTE_MAY_ALIAS __attribute__ ((__may_alias__))
# define _GL_ATTRIBUTE_MAY_ALIAS
#endif
+/* _GL_ATTRIBUTE_MAYBE_UNUSED declares that it is not a programming mistake if
+ the entity is not used. The compiler should not warn if the entity is not
+ used. */
+/* Applies to:
+ - function, variable,
+ - struct, union, struct/union member,
+ - enumeration, enumeration item,
+ - typedef,
+ in C++ also: class. */
+/* In C++ and C2x, this is spelled [[__maybe_unused__]].
+ GCC's syntax is __attribute__ ((__unused__)).
+ clang supports both syntaxes. */
#if _GL_HAS_C_ATTRIBUTE (maybe_unused)
# define _GL_ATTRIBUTE_MAYBE_UNUSED [[__maybe_unused__]]
#else
/* Earlier spellings of this macro. */
#define _UNUSED_PARAMETER_ _GL_ATTRIBUTE_MAYBE_UNUSED
+/* _GL_ATTRIBUTE_NODISCARD declares that the caller of the function should not
+ discard the return value. The compiler may warn if the caller does not use
+ the return value, unless the caller uses something like ignore_value. */
+/* Applies to: function, enumeration, class. */
#if _GL_HAS_C_ATTRIBUTE (nodiscard)
# define _GL_ATTRIBUTE_NODISCARD [[__nodiscard__]]
#elif _GL_HAS_ATTRIBUTE (warn_unused_result)
# define _GL_ATTRIBUTE_NODISCARD
#endif
+/* _GL_ATTRIBUTE_NOINLINE tells that the compiler should not inline the
+ function. */
+/* Applies to: functions. */
#if _GL_HAS_ATTRIBUTE (noinline)
# define _GL_ATTRIBUTE_NOINLINE __attribute__ ((__noinline__))
#else
# define _GL_ATTRIBUTE_NOINLINE
#endif
+/* _GL_ATTRIBUTE_NONNULL ((N1, N2,...)) declares that the arguments N1, N2,...
+ must not be NULL.
+ _GL_ATTRIBUTE_NONNULL () declares that all pointer arguments must not be
+ null. */
+/* Applies to: functions. */
#if _GL_HAS_ATTRIBUTE (nonnull)
# define _GL_ATTRIBUTE_NONNULL(args) __attribute__ ((__nonnull__ args))
#else
# define _GL_ATTRIBUTE_NONNULL(args)
#endif
+/* _GL_ATTRIBUTE_NONSTRING declares that 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'. */
#if _GL_HAS_ATTRIBUTE (nonstring)
# define _GL_ATTRIBUTE_NONSTRING __attribute__ ((__nonstring__))
#else
/* There is no _GL_ATTRIBUTE_NORETURN; use _Noreturn instead. */
+/* _GL_ATTRIBUTE_NOTHROW declares that the function does not throw exceptions.
+ */
+/* Applies to: functions. */
#if _GL_HAS_ATTRIBUTE (nothrow) && !defined __cplusplus
# define _GL_ATTRIBUTE_NOTHROW __attribute__ ((__nothrow__))
#else
# define _GL_ATTRIBUTE_NOTHROW
#endif
+/* _GL_ATTRIBUTE_PACKED declares:
+ 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. */
#if _GL_HAS_ATTRIBUTE (packed)
# define _GL_ATTRIBUTE_PACKED __attribute__ ((__packed__))
#else
# define _GL_ATTRIBUTE_PACKED
#endif
+/* _GL_ATTRIBUTE_PURE declares that It is OK for a compiler to omit duplicate
+ calls to the function with the same arguments if observable state is not
+ changed between calls.
+ This attribute is safe for a function that does not affect
+ observable state, and always returns exactly once.
+ (This attribute is looser than _GL_ATTRIBUTE_CONST.) */
+/* Applies to: functions. */
#if _GL_HAS_ATTRIBUTE (pure)
# define _GL_ATTRIBUTE_PURE __attribute__ ((__pure__))
#else
# define _GL_ATTRIBUTE_PURE
#endif
+/* _GL_ATTRIBUTE_RETURNS_NONNULL declares that the function's return value is
+ a non-NULL pointer. */
+/* Applies to: functions. */
#if _GL_HAS_ATTRIBUTE (returns_nonnull)
# define _GL_ATTRIBUTE_RETURNS_NONNULL __attribute__ ((__returns_nonnull__))
#else
# define _GL_ATTRIBUTE_RETURNS_NONNULL
#endif
+/* _GL_ATTRIBUTE_SENTINEL(pos) declares that the variadic function expects a
+ trailing NULL argument.
+ _GL_ATTRIBUTE_SENTINEL () - The last argument is NULL (requires C99).
+ _GL_ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL. */
+/* Applies to: functions. */
#if _GL_HAS_ATTRIBUTE (sentinel)
# define _GL_ATTRIBUTE_SENTINEL(pos) __attribute__ ((__sentinel__ pos))
#else
# define _GL_ATTRIBUTE_SENTINEL(pos)
#endif
+/* A helper macro. Don't use it directly. */
#if _GL_HAS_ATTRIBUTE (unused)
# define _GL_ATTRIBUTE_UNUSED __attribute__ ((__unused__))
#else
# define _GL_ATTRIBUTE_UNUSED
#endif
-/* Earlier spellings of this macro. */
+/* Alternative spelling of this macro, for convenience. */
#define _GL_UNUSED _GL_ATTRIBUTE_UNUSED
]dnl There is no _GL_ATTRIBUTE_VISIBILITY; see m4/visibility.m4 instead.
[
-/* To support C++ as well as C, use _GL_UNUSED_LABEL with trailing ';'. */
+/* _GL_UNUSED_LABEL; declares that it is not a programming mistake if the
+ immediately preceding label is not used. The compiler should not warn
+ if the label is not used. */
+/* Applies to: label (both in C and C++). */
#if !defined __cplusplus || _GL_GNUC_PREREQ (4, 5)
# define _GL_UNUSED_LABEL _GL_ATTRIBUTE_UNUSED
#else