blob: 82245279eb19d676e79f2d0215517f3c96c08d53 [file] [log] [blame]
/* ATTRIBUTE_* macros for using attributes in GCC and similar compilers
Copyright 2020-2021 Free Software Foundation, Inc.
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published
by the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <>. */
/* Written by Paul Eggert. */
/* 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. */
/* This file defines two types of attributes:
* C2X standard attributes. These have macro names that do not begin with
* Selected GCC attributes; see:
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. */
/* If a function call is not optimized way, warn with MSG. */
/* Applies to: functions. */
/* If a function call is not optimized way, report an error with MSG. */
/* Applies to: functions. */
/* Attributes for memory-allocating functions. */
/* The function returns a pointer to freshly allocated memory. */
/* Applies to: functions. */
/* 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. */
/* Attributes for variadic functions. */
/* The variadic function expects a trailing NULL argument.
ATTRIBUTE_SENTINEL () - The last argument is NULL (requires C99).
ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL. */
/* Applies to: functions. */
/* ================== Attributes for compiler diagnostics ================== */
/* Attributes that help the compiler diagnose programmer mistakes.
Some of them may also help for some compiler optimizations. */
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,
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. */
/* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL.
ATTRIBUTE_NONNULL () - All pointer arguments must not be null. */
/* Applies to: functions. */
/* The function's return value is a non-NULL pointer. */
/* Applies to: functions. */
/* Warn if the caller does not use the return value,
unless the caller uses something like ignore_value. */
/* Applies to: function, enumeration, class. */
/* 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. */
/* 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'. */
/* Do not warn if control flow falls through to the immediately
following 'case' or 'default' label. */
/* Applies to: Empty statement (;), inside a 'switch' statement. */
/* ================== Attributes for debugging information ================== */
/* Attributes regarding debugging information emitted by the compiler. */
/* Omit the function from stack traces when debugging. */
/* Applies to: function. */
/* Make the entity visible to debuggers etc., even with '-fwhole-program'. */
/* Applies to: functions, variables. */
/* ========== Attributes that mainly direct compiler optimizations ========== */
/* The function does not throw exceptions. */
/* Applies to: functions. */
/* Do not inline the function. */
/* Applies to: functions. */
/* Always inline the function, and report an error if the compiler
cannot inline. */
/* Applies to: function. */
/* It is OK for a compiler to omit duplicate calls 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 ATTRIBUTE_PURE.) */
/* Applies to: functions. */
/* It is OK for a compiler to omit duplicate calls 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 ATTRIBUTE_CONST.) */
/* Applies to: functions. */
/* The function is rarely executed. */
/* 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. */
/* 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. */
/* ================ 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. */
#endif /* _GL_ATTRIBUTE_H */