From 55b5ab511457fb8e4bcc175e78ecdce5e90c5cd9 Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Sun, 10 May 2020 19:18:44 +0200 Subject: [PATCH] attribute: Clarify list of attributes. * lib/attribute.h: Reorder the list of attributes, and group them by purpose. --- ChangeLog | 6 ++ lib/attribute.h | 183 ++++++++++++++++++++++++++++-------------------- 2 files changed, 114 insertions(+), 75 deletions(-) diff --git a/ChangeLog b/ChangeLog index 111cf89def..019e45bec4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2020-05-10 Bruno Haible + + attribute: Clarify list of attributes. + * lib/attribute.h: Reorder the list of attributes, and group them by + purpose. + 2020-05-10 Bruno Haible string: Fix compilation error in C++ mode. diff --git a/lib/attribute.h b/lib/attribute.h index 3bd23faae0..e9a81bba69 100644 --- a/lib/attribute.h +++ b/lib/attribute.h @@ -31,8 +31,19 @@ #define _GL_ATTRIBUTE_H -/* C2X standard attributes have macro names that do not begin with - 'ATTRIBUTE_'. */ +/* This file defines two types of attributes: + * C2X standard attributes. These have macro names that do not begin with + 'ATTRIBUTE_'. + * Selected GCC attributes; see: + https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html + https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html + https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html + These names begin with 'ATTRIBUTE_' to avoid name clashes. */ + + +/* =============== Attributes for specific kinds of functions =============== */ + +/* Attributes for functions that should not be used. */ /* Warn if the entity is used. */ /* Applies to: @@ -43,31 +54,20 @@ in C++ also: namespace, class, template specialization. */ #define DEPRECATED _GL_ATTRIBUTE_DEPRECATED -/* 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 +/* If a function call is not optimized way, warn with MSG. */ +/* Applies to: functions. */ +#define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg) -/* Do 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. */ -#define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED +/* If a function call is not optimized way, report an error with MSG. */ +/* Applies to: functions. */ +#define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg) -/* 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 +/* Attributes for memory-allocating functions. */ -/* Selected GCC attributes; see: - https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html - https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html - https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html - These names begin with 'ATTRIBUTE_' to avoid name clashes. */ +/* The function returns a pointer to freshly allocated memory. */ +/* Applies to: functions. */ +#define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC /* ATTRIBUTE_ALLOC_SIZE ((N)) - The Nth argument of the function is the size of the returned memory block. @@ -76,32 +76,19 @@ /* Applies to: function, pointer to function, function types. */ #define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args) -/* Always inline the function, and report an error if the compiler - cannot inline. */ -/* Applies to: function. */ -#define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE -/* Omit the function from stack traces when debugging. */ -/* Applies to: function. */ -#define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL +/* Attributes for variadic functions. */ -/* The function is rarely executed. */ +/* 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_COLD _GL_ATTRIBUTE_COLD +#define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos) -/* 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 -/* If a function call is not optimized way, report an error with MSG. */ -/* Applies to: functions. */ -#define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg) +/* ================== Attributes for compiler diagnostics ================== */ -/* Make the entity visible to debuggers etc., even with '-fwhole-program'. */ -/* Applies to: functions, variables. */ -#define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE +/* Attributes that help the compiler diagnose programmer mistakes. */ /* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) - The STRING-INDEXth function argument is a format string of style @@ -116,45 +103,71 @@ /* Applies to: functions. */ #define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec) -/* 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. */ +/* 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_LEAF _GL_ATTRIBUTE_LEAF - -/* 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 +#define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args) -/* The function returns a pointer to freshly allocated memory. */ +/* The function's return value is a non-NULL pointer. */ /* Applies to: functions. */ -#define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC +#define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL -/* Do not inline the function. */ -/* Applies to: functions. */ -#define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE +/* 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 -/* 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) + +/* Attributes that disable false alarms when the compiler diagnoses + programmer "mistakes". */ + +/* Do 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. */ +#define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED /* 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 +/* 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 + + +/* ================== Attributes for debugging information ================== */ + +/* Attributes regarding debugging information emitted by the compiler. */ + +/* Omit the function from stack traces when debugging. */ +/* Applies to: function. */ +#define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL + +/* Make the entity visible to debuggers etc., even with '-fwhole-program'. */ +/* Applies to: functions, variables. */ +#define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE + + +/* ========== Attributes that mainly direct compiler optimizations ========== */ + /* The function does not throw exceptions. */ /* Applies to: functions. */ #define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW -/* 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 +/* Do not inline the function. */ +/* Applies to: functions. */ +#define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE + +/* Always inline the function, and report an error if the compiler + cannot inline. */ +/* Applies to: function. */ +#define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE /* The function does not affect observable state, and always returns a value. Compilers can omit duplicate calls with the same arguments if @@ -163,19 +176,39 @@ /* Applies to: functions. */ #define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE -/* The function's return value is a non-NULL pointer. */ +/* 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_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL +#define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST -/* 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. */ +/* The function is rarely executed. */ /* Applies to: functions. */ -#define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos) +#define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD -/* If a function call is not optimized way, warn with MSG. */ +/* 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_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg) +#define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF + +/* 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 + + +/* ================ Attributes that make invalid code valid ================ */ + +/* Attributes that prevent fatal compiler optimizations for code that is not + fully ISO C compliant. */ + +/* 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 #endif /* _GL_ATTRIBUTE_H */ -- 2.39.5