doc/attribute.texi

@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