diff options
| author | Paul Eggert <eggert@cs.ucla.edu> | 2020-05-11 17:28:23 -0700 |
|---|---|---|
| committer | Paul Eggert <eggert@cs.ucla.edu> | 2020-05-11 17:54:23 -0700 |
| commit | 00f0ad55cd7cbb71e42de0d52b7607ffb6a3c220 (patch) | |
| tree | c7ea55a573abdb8a1583d59ca38ef035e33978f7 /lib/attribute.h | |
| parent | dd0b910f1a9d08e65f59cc7ebc10fb6cd0fecfc9 (diff) | |
| download | emacs-00f0ad55cd7cbb71e42de0d52b7607ffb6a3c220.tar.gz emacs-00f0ad55cd7cbb71e42de0d52b7607ffb6a3c220.tar.bz2 emacs-00f0ad55cd7cbb71e42de0d52b7607ffb6a3c220.zip | |
Update from gnulib
This incorporates:
2020-05-11 careadlinkat: fix GCC 10 workaround
2020-05-10 careadlinkat: limit GCC workaround
2020-05-10 attribute: clarify list of attributes
2020-05-10 string: fix compilation error in C++ mode
2020-05-09 manywarnings: port to GCC 10.1
2020-05-09 careadlinkat: pacify -Wreturn-local-addr
2020-05-09 attribute: remove ATTRIBUTE_DEPRECATED
2020-05-09 attribute: Add comments
* lib/attribute.h, lib/careadlinkat.c, lib/string.in.h:
* lib/warn-on-use.h, m4/manywarnings.m4: Copy from Gnulib.
Diffstat (limited to 'lib/attribute.h')
| -rw-r--r-- | lib/attribute.h | 203 |
1 files changed, 180 insertions, 23 deletions
diff --git a/lib/attribute.h b/lib/attribute.h index c5919d97005..2836b99dad0 100644 --- a/lib/attribute.h +++ b/lib/attribute.h @@ -20,39 +20,196 @@ /* Provide public ATTRIBUTE_* names for the private _GL_ATTRIBUTE_* macros used within Gnulib. */ +/* These attributes can be placed in two ways: + - At the start of a declaration (i.e. even before storage-class + specifiers!); then they apply to all entities that are declared + by the declaration. + - Immediately after the name of an entity being declared by the + declaration; then they apply to that entity only. */ + #ifndef _GL_ATTRIBUTE_H #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: + - function, variable, + - struct, union, struct/union member, + - enumeration, enumeration item, + - typedef, + in C++ also: namespace, class, template specialization. */ #define DEPRECATED _GL_ATTRIBUTE_DEPRECATED -#define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH -#define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED -#define NODISCARD _GL_ATTRIBUTE_NODISCARD -/* Selected GCC attributes; see: - https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html - These names begin with 'ATTRIBUTE_' to avoid name clashes. */ -#define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args) -#define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE -#define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL -#define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD -#define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST -#define ATTRIBUTE_DEPRECATED _GL_ATTRIBUTE_DEPRECATED +/* If a function call is not optimized way, warn with MSG. */ +/* Applies to: functions. */ +#define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg) + +/* If a function call is not optimized way, report an error with MSG. */ +/* Applies to: functions. */ #define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg) -#define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE -#define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec) -#define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF -#define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS + + +/* Attributes for memory-allocating functions. */ + +/* The function returns a pointer to freshly allocated memory. */ +/* Applies to: functions. */ #define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC -#define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE + +/* 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) + + +/* Attributes for variadic 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) + + +/* ================== Attributes for compiler diagnostics ================== */ + +/* Attributes that help the compiler diagnose programmer mistakes. + Some of them may also help for some compiler optimizations. */ + +/* 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-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) + +/* 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) + +/* The function's return value is a non-NULL pointer. */ +/* Applies to: functions. */ +#define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL + +/* 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 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 -#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 + observable state is not changed between calls. (This attribute is + looser than ATTRIBUTE_CONST.) */ +/* Applies to: functions. */ #define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE -#define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL -#define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos) -#define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg) + +/* 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 + +/* The function is rarely executed. */ +/* Applies to: functions. */ +#define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD + +/* 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 + +/* 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 */ |