doc/attribute.texi

   1 @c attribute module documentation
   2
   3 @c Copyright 2020--2024 Free Software Foundation, Inc.
   4
   5 @c Permission is granted to copy, distribute and/or modify this document
   6 @c under the terms of the GNU Free Documentation License, Version 1.3 or
   7 @c any later version published by the Free Software Foundation; with no
   8 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
   9 @c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
  10
  11 @node Attributes
  12 @section Attributes
  13
  14 @cindex Attributes
  15 @findex __attribute__
  16
  17 This module provides a header file @file{attribute.h} that defines
  18 macros related to C and C++ attributes and the GCC
  19 @code{__attribute__} keyword.
  20
  21 Here is an example of its use:
  22
  23 @example
  24 #include <attribute.h>
  25
  26 NODISCARD
  27 extern char *crypt (char const *, char const *)
  28   ATTRIBUTE_NOTHROW ATTRIBUTE_LEAF ATTRIBUTE_NONNULL ((1, 2));
  29 @end example
  30
  31 @noindent
  32 @code{NODISCARD} expands to @code{[[nodiscard]]} if the compiler
  33 supports this C23 syntax, otherwise to
  34 @code{__attribute__ ((__warn_unused_result__))} if the compiler
  35 is a recent-enough GCC or GCC-like compiler, otherwise to nothing.
  36 @code{ATTRIBUTE_NOTHROW} expands to @code{__attribute__
  37 ((__nothrow__))} if the compiler is a recent-enough GCC or GCC-like
  38 compiler, and to nothing otherwise.  Similarly for
  39 @code{ATTRIBUTE_LEAF}.  @code{ATTRIBUTE_NONNULL ((1, 2))} expands to
  40 @code{__attribute__ ((__nonnull__ (1, 2)))} if the compiler is
  41 recent-enough GCC, and to nothing otherwise.
  42
  43 Most of these attribute names begin with @code{ATTRIBUTE_}.
  44 A few do not, because they are part of C23 and their
  45 names are not likely to clash with other macro names.
  46 These macros are @code{DEPRECATED}, @code{FALLTHROUGH},
  47 @code{MAYBE_UNUSED}, and @code{NODISCARD}, which can
  48 be defined to @code{[[deprecated]]} etc.@: on C23 platforms.
  49 Also, these exceptional macros should be placed at the start of
  50 function declarations, whereas the @code{ATTRIBUTE_*} macros can be
  51 placed at the end.