mirror of
https://https.git.savannah.gnu.org/git/gnulib.git
synced 2026-04-28 06:33:36 +00:00
70 lines
2.4 KiB
Plaintext
70 lines
2.4 KiB
Plaintext
@c attribute module documentation
|
|
|
|
@c Copyright 2020--2026 Free Software Foundation, Inc.
|
|
|
|
@c Permission is granted to copy, distribute and/or modify this document
|
|
@c under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
@c any later version published by the Free Software Foundation; with no
|
|
@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
|
@c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
|
|
|
|
@node Attributes
|
|
@section Attributes
|
|
|
|
@cindex Attributes
|
|
@findex __attribute__
|
|
@mindex attribute
|
|
The module @samp{attribute} provides a header file @file{attribute.h} that
|
|
defines macros related to C and C++ attributes and the GCC
|
|
@code{__attribute__} keyword.
|
|
|
|
Here is an example of its use:
|
|
|
|
@example
|
|
#include <attribute.h>
|
|
|
|
NODISCARD
|
|
extern char *crypt (char const *, char const *)
|
|
ATTRIBUTE_NOTHROW ATTRIBUTE_LEAF ATTRIBUTE_NONNULL ((1, 2));
|
|
@end example
|
|
|
|
@noindent
|
|
@code{NODISCARD} expands to @code{[[nodiscard]]} if the compiler
|
|
supports this C23 syntax, otherwise to
|
|
@code{__attribute__ ((__warn_unused_result__))} if the compiler
|
|
is a recent-enough GCC or GCC-like compiler, otherwise to nothing.
|
|
@code{ATTRIBUTE_NOTHROW} expands to @code{__attribute__
|
|
((__nothrow__))} if the compiler is a recent-enough GCC or GCC-like
|
|
compiler, and to nothing otherwise. Similarly for
|
|
@code{ATTRIBUTE_LEAF}. @code{ATTRIBUTE_NONNULL ((1, 2))} expands to
|
|
@code{__attribute__ ((__nonnull__ (1, 2)))} if the compiler is
|
|
recent-enough GCC, and to nothing otherwise.
|
|
|
|
Most of these attribute names begin with @code{ATTRIBUTE_}.
|
|
A few do not, because they are part of C23 and their
|
|
names are not likely to clash with other macro names.
|
|
These macros are @code{DEPRECATED}, @code{FALLTHROUGH},
|
|
@code{MAYBE_UNUSED}, and @code{NODISCARD}, which can
|
|
be defined to @code{[[deprecated]]} etc.@: on C23 platforms.
|
|
Also, these exceptional macros should be placed at the start of
|
|
function declarations, whereas the @code{ATTRIBUTE_*} macros can be
|
|
placed at the end.
|
|
|
|
The module also defines the macro @code{UNNAMED},
|
|
designed for function parameters that are never used,
|
|
whereas the @code{MAYBE_UNUSED} attribute is better suited for parameters
|
|
that might or might not be unused depending on preprocessor macro settings.
|
|
For example:
|
|
|
|
@example
|
|
int
|
|
f (int a, MAYBE_UNUSED int b, int UNNAMED (c))
|
|
@{
|
|
int r = a;
|
|
#ifdef B_FEATURE
|
|
r |= b;
|
|
#endif
|
|
return r;
|
|
@}
|
|
@end example
|