mdw@git.distorted.org.uk Git - mLib/blob - utils/macros.3

   1 .\" -*-nroff-*-
   2 .TH macros 3 "13 December 2003" "Straylight/Edgeware" "mLib utilities library"
   3 .SH NAME
   4 macros \- useful macros
   5 .\" @N
   6 .\" @STR
   7 .\" @GLUE
   8 .\" @STATIC_ASSERT
   9 .\" @DISCARD
  10 .\" @IGNORE
  11 .\" @DEPRECATED
  12 .\" @EXECL_LIKE
  13 .\" @IGNORABLE
  14 .\" @NORETURN
  15 .\" @PRINTF_LIKE
  16 .\" @SCANF_LIKE
  17 .\" @MUFFLE_WARNINGS_DECL
  18 .\" @MUFFLE_WARNINGS_EXPR
  19 .\" @MUFFLE_WARNINGS_STMT
  20 .\" @GCC_WARNING
  21 .SH SYNOPSIS
  22 .nf
  23 .B "#include <mLib/macros.h>"
  24
  25 .BI "size_t N(" array ");"
  26 .BI "STR(" tokens\fR... ")"
  27 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
  28 .BI "STATIC_ASSERT(" cond ", " msg ");"
  29
  30 .BI "void DISCARD(" scalar ");"
  31 .BI "void IGNORE(" variable ");"
  32
  33 .BI "DEPRECATED(" msg ")"
  34 .BI "EXECL_LIKE(" ntrail ")"
  35 .BI "IGNORABLE"
  36 .BI "NORETURN"
  37 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
  38 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
  39
  40 .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
  41 .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
  42 .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
  43
  44 .BI "GCC_WARNING(" option ")"
  45 .BI "CLANG_WARNING(" option ")"
  46 .fi
  47 .SH DESCRIPTION
  48 .SS Utilities
  49 The
  50 .B N
  51 macro returns the number of elements in the named
  52 .IR array .
  53 .PP
  54 The
  55 .B STR
  56 macro expands to a string literal containing the result of expanding its
  57 argument
  58 .IR tokens .
  59 .PP
  60 The
  61 .B GLUE
  62 macro expands to a single token, which is the result of gluing together
  63 the tokens resulting from expanding its argument token lists.  Each of
  64 the argument token lists must expand to a single preprocessing token,
  65 and the result of gluing these tokens together must be valid
  66 preprocessing token.
  67 .PP
  68 The
  69 .B STATIC_ASSERT
  70 causes compilation to fail if the integer constant expression
  71 .I cond
  72 evaluates to zero.  This macro uses the C11
  73 .B static_assert
  74 declaration if available, and the
  75 .I msg
  76 will be reported in the compiler's diagnostic messsage; otherwise, the macro
  77 falls back to a somewhat ugly hack which currently ignores the
  78 .IR msg .
  79 .PP
  80 The
  81 .B DISCARD
  82 macro discards its argument, which must be of some scalar type.  This
  83 can be useful in muffling warnings about ignoring return codes in cases
  84 where you really don't care.
  85 .PP
  86 The
  87 .B IGNORE
  88 macro ignores its argument, which may be an expression of any type.
  89 This can be useful in muffling warnings about unused variables.
  90 .SS Annotations
  91 The following annotations can be attached to function declarations and
  92 definitions, as part of the declaration specifiers.  (Other positions
  93 may also work, depending on your compiler, but don't bet on it.)  They
  94 might not have any effect, depending on your specific compiler.
  95 Currently only GCC is well supported, but exactly which features are
  96 available depend on the compiler version.
  97 .PP
  98 Using a function or variable marked as
  99 .B DEPRECATED
 100 may provoke a compiler warning; this warning may (depending on your
 101 compiler version) include the given
 102 .IR msg .
 103 .PP
 104 A variadic function marked as
 105 .B EXECL_LIKE
 106 must be called with a null pointer (i.e., an integer constant
 107 expression with value 0, cast to
 108 .BR "void *")
 109 in the variadic part of its argument list, followed by
 110 .I ntrail
 111 further arguments.  Typically,
 112 .I ntrail
 113 is zero.  Compilers may warn about misuse of such functions.
 114 .PP
 115 A function or variable marked as
 116 .B IGNORABLE
 117 need not be used.  This may muffle warnings about leaving the marked
 118 definition unused.
 119 .PP
 120 A function marked as
 121 .B NORETURN
 122 must not return.  It must have return type
 123 .BR void .
 124 This may be useful in muffling warnings about uninitialized variables,
 125 for example.
 126 .PP
 127 A variadic function marked as
 128 .B PRINTF_LIKE
 129 takes a
 130 .BR printf (3)-style
 131 format argument (in position
 132 .IR fmt-index ,
 133 counting from 1) and a variable-length list of arguments to be formatted
 134 (starting from position
 135 .IR arg-index ).
 136 Compilers may warn about misuse of such functions.
 137 .PP
 138 A variadic function marked as
 139 .B SCANF_LIKE
 140 takes a
 141 .BR scanf (3)-style
 142 format argument (in position
 143 .IR fmt-index ,
 144 counting from 1) and a variable-length list of arguments to be formatted
 145 (starting from position
 146 .IR arg-index ).
 147 Compilers may warn about misuse of such functions.
 148 .SS Muffling warnings
 149 Some compilers allow you to muffle warnings in particular pieces of
 150 code.  These macros provide a compiler-neutral interface to such
 151 facilities.  Each macro takes an argument
 152 .IR warns ,
 153 which is a sequence of calls to
 154 .IB compiler _WARNING
 155 macros listing the warnings to be muffled.  The list may contain
 156 warnings for several different compilers.  The other argument is a
 157 .I body
 158 consisting of declarations (in the case of
 159 .BR MUFFLE_WARNINGS_DECL ),
 160 an expression (for
 161 .BR MUFFLE_WARNINGS_EXPR ),
 162 or a statement (for
 163 .BR MUFFLE_WARNINGS_STMT ).
 164 .SS GCC-specific features
 165 The
 166 .B GCC_VERSION_P
 167 macro returns a nonzero value if the compiler is at least version
 168 .IB maj . min
 169 of GCC, and zero otherwise.  It's useful in preprocessor conditions.
 170 .PP
 171 The
 172 .B GCC_WARNING
 173 macro is intended to be used in
 174 .I warns
 175 lists (see above).  It takes a string-literal argument
 176 .I option
 177 naming a GCC warning option, e.g.,
 178 .BR """\-Wdiv-by-zero""" .
 179 .PP
 180 The
 181 .B CLANG_WARNING
 182 is similar, except that it works with the Clang compiler.
 183 .PP
 184 Note that including
 185 .B <mLib/macros.h>
 186 also defines the compiler-test macros in
 187 .BR <mLib/compiler.h>;
 188 see
 189 .BR compiler (3).
 190 .SH "SEE ALSO"
 191 .BR mLib (3),
 192 .BR compiler (3).
 193 .SH "AUTHOR"
 194 Mark Wooding, <mdw@distorted.org.uk>