chiark - git - mdw - 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 .\" @ISALNUM
  10 .\" @ISALPHA
  11 .\" @ISASCII
  12 .\" @ISBLANK
  13 .\" @ISCNTRL
  14 .\" @ISDIGIT
  15 .\" @ISGRAPH
  16 .\" @ISLOWER
  17 .\" @ISPRINT
  18 .\" @ISPUNCT
  19 .\" @ISSPACE
  20 .\" @ISUPPER
  21 .\" @ISXDIGIT
  22 .\" @TOASCII
  23 .\" @TOLOWER
  24 .\" @TOUPPER
  25 .\" @MEMCMP
  26 .\" @STRCMP
  27 .\" @STRNCMP
  28 .\" @DISCARD
  29 .\" @IGNORE
  30 .\" @DEPRECATED
  31 .\" @EXECL_LIKE
  32 .\" @IGNORABLE
  33 .\" @MUST_CHECK
  34 .\" @NORETURN
  35 .\" @PRINTF_LIKE
  36 .\" @SCANF_LIKE
  37 .\" @MUFFLE_WARNINGS_DECL
  38 .\" @MUFFLE_WARNINGS_EXPR
  39 .\" @MUFFLE_WARNINGS_STMT
  40 .\" @GCC_WARNING
  41 .\" @CLANG_WARNING
  42 .SH SYNOPSIS
  43 .nf
  44 .B "#include <mLib/macros.h>"
  45
  46 .BI "size_t N(" array ");"
  47 .BI "STR(" tokens\fR... ")"
  48 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
  49 .BI "STATIC_ASSERT(" cond ", " msg ");"
  50
  51 .BI "ISALNUM(int " ch ");"
  52 .BI "ISALPHA(int " ch ");"
  53 .BI "ISASCII(int " ch ");"
  54 .BI "ISBLANK(int " ch ");"
  55 .BI "ISCNTRL(int " ch ");"
  56 .BI "ISDIGIT(int " ch ");"
  57 .BI "ISGRAPH(int " ch ");"
  58 .BI "ISLOWER(int " ch ");"
  59 .BI "ISPRINT(int " ch ");"
  60 .BI "ISPUNCT(int " ch ");"
  61 .BI "ISSPACE(int " ch ");"
  62 .BI "ISUPPER(int " ch ");"
  63 .BI "ISXDIGIT(int " ch ");"
  64 .BI "TOASCII(int " ch ");"
  65 .BI "TOLOWER(int " ch ");"
  66 .BI "TOUPPER(int " ch ");"
  67
  68 .BI "MEMCMP(const void *" x ", " op ", const void *" y ", size_t " n ");"
  69 .BI "STRCMP(const char *" x ", " op ", const char *" y ");"
  70 .BI "STRNCMP(const char *" x ", " op ", const char *" y ", size_t " n ");"
  71
  72 .BI "void DISCARD(" scalar ");"
  73 .BI "void IGNORE(" variable ");"
  74
  75 .BI "DEPRECATED(" msg ")"
  76 .BI "EXECL_LIKE(" ntrail ")"
  77 .BI "IGNORABLE"
  78 .BI "MUST_CHECK"
  79 .BI "NORETURN"
  80 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
  81 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
  82
  83 .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
  84 .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
  85 .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
  86
  87 .BI "GCC_WARNING(" option ")"
  88 .BI "CLANG_WARNING(" option ")"
  89 .fi
  90 .SH DESCRIPTION
  91 .SS Utilities
  92 The
  93 .B N
  94 macro returns the number of elements in the named
  95 .IR array .
  96 .PP
  97 The
  98 .B STR
  99 macro expands to a string literal containing the result of expanding its
 100 argument
 101 .IR tokens .
 102 .PP
 103 The
 104 .B GLUE
 105 macro expands to a single token, which is the result of gluing together
 106 the tokens resulting from expanding its argument token lists.  Each of
 107 the argument token lists must expand to a single preprocessing token,
 108 and the result of gluing these tokens together must be valid
 109 preprocessing token.
 110 .PP
 111 The
 112 .B STATIC_ASSERT
 113 causes compilation to fail if the integer constant expression
 114 .I cond
 115 evaluates to zero.  This macro uses the C11
 116 .B static_assert
 117 declaration if available, and the
 118 .I msg
 119 will be reported in the compiler's diagnostic messsage; otherwise, the macro
 120 falls back to a somewhat ugly hack which currently ignores the
 121 .IR msg .
 122 .PP
 123 The
 124 .BR IS ...\&
 125 and
 126 .BR TO ...\&
 127 macros are wrappers around the corresponding standard
 128 .B <ctype.h>
 129 macros with the corresponding lowercase names.  They take care of
 130 forcing the character argument
 131 .I ch
 132 to
 133 .BR "unsigned char" :
 134 this conversion is necessary on platforms with signed
 135 .B char
 136 to avoid passing negative values into the standard macros.
 137 .PP
 138 The
 139 .BR MEMCMP ,
 140 .BR STRCMP ,
 141 and
 142 .B STRNCMP
 143 macros are wrappers around the standard
 144 .B <string.h>
 145 functions with the corresponding lowercase names.  They take an
 146 additional argument
 147 .I op
 148 which is a equality or ordering operator (e.g.,
 149 .B ==
 150 or
 151 .BR > )
 152 inserted between the two operands.  The standard functions return a
 153 false value if and only if the operands are equal, which is
 154 counterintuitive and leads to mistakes; requiring an explicit relational
 155 operator should reduce the number of such mistakes.
 156 .PP
 157 The
 158 .B DISCARD
 159 macro discards its argument, which must be of some scalar type.  This
 160 can be useful in muffling warnings about ignoring return codes in cases
 161 where you really don't care.
 162 .PP
 163 The
 164 .B IGNORE
 165 macro ignores its argument, which may be an expression of any type.
 166 This can be useful in muffling warnings about unused variables.
 167 .SS Annotations
 168 The following annotations can be attached to function declarations and
 169 definitions, as part of the declaration specifiers.  (Other positions
 170 may also work, depending on your compiler, but don't bet on it.)  They
 171 might not have any effect, depending on your specific compiler.
 172 Currently only GCC is well supported, but exactly which features are
 173 available depend on the compiler version.
 174 .PP
 175 Using a function or variable marked as
 176 .B DEPRECATED
 177 may provoke a compiler warning; this warning may (depending on your
 178 compiler version) include the given
 179 .IR msg .
 180 .PP
 181 A variadic function marked as
 182 .B EXECL_LIKE
 183 must be called with a null pointer (i.e., an integer constant
 184 expression with value 0, cast to
 185 .BR "void *")
 186 in the variadic part of its argument list, followed by
 187 .I ntrail
 188 further arguments.  Typically,
 189 .I ntrail
 190 is zero.  Compilers may warn about misuse of such functions.
 191 .PP
 192 A function or variable marked as
 193 .B IGNORABLE
 194 need not be used.  This may muffle warnings about leaving the marked
 195 definition unused.
 196 .PP
 197 A function marked as
 198 .B MUST_CHECK
 199 returns an important value: a warning may be issued if a caller
 200 ignores the value.  The return type must not be
 201 .BR void .
 202 .PP
 203 A function marked as
 204 .B NORETURN
 205 must not return.  It must have return type
 206 .BR void .
 207 This may be useful in muffling warnings about uninitialized variables,
 208 for example.
 209 .PP
 210 A variadic function marked as
 211 .B PRINTF_LIKE
 212 takes a
 213 .BR printf (3)-style
 214 format argument (in position
 215 .IR fmt-index ,
 216 counting from 1) and a variable-length list of arguments to be formatted
 217 (starting from position
 218 .IR arg-index ).
 219 Compilers may warn about misuse of such functions.
 220 .PP
 221 A variadic function marked as
 222 .B SCANF_LIKE
 223 takes a
 224 .BR scanf (3)-style
 225 format argument (in position
 226 .IR fmt-index ,
 227 counting from 1) and a variable-length list of arguments to be formatted
 228 (starting from position
 229 .IR arg-index ).
 230 Compilers may warn about misuse of such functions.
 231 .SS Muffling warnings
 232 Some compilers allow you to muffle warnings in particular pieces of
 233 code.  These macros provide a compiler-neutral interface to such
 234 facilities.  Each macro takes an argument
 235 .IR warns ,
 236 which is a sequence of calls to
 237 .IB compiler _WARNING
 238 macros listing the warnings to be muffled.  The list may contain
 239 warnings for several different compilers.  The other argument is a
 240 .I body
 241 consisting of declarations (in the case of
 242 .BR MUFFLE_WARNINGS_DECL ),
 243 an expression (for
 244 .BR MUFFLE_WARNINGS_EXPR ),
 245 or a statement (for
 246 .BR MUFFLE_WARNINGS_STMT ).
 247 .SS GCC-specific features
 248 The
 249 .B GCC_VERSION_P
 250 macro returns a nonzero value if the compiler is at least version
 251 .IB maj . min
 252 of GCC, and zero otherwise.  It's useful in preprocessor conditions.
 253 .PP
 254 The
 255 .B GCC_WARNING
 256 macro is intended to be used in
 257 .I warns
 258 lists (see above).  It takes a string-literal argument
 259 .I option
 260 naming a GCC warning option, e.g.,
 261 .BR """\-Wdiv-by-zero""" .
 262 .PP
 263 The
 264 .B CLANG_WARNING
 265 is similar, except that it works with the Clang compiler.
 266 .PP
 267 Note that including
 268 .B <mLib/macros.h>
 269 also defines the compiler-test macros in
 270 .BR <mLib/compiler.h>;
 271 see
 272 .BR compiler (3).
 273 .SH "SEE ALSO"
 274 .BR mLib (3),
 275 .BR compiler (3).
 276 .SH "AUTHOR"
 277 Mark Wooding, <mdw@distorted.org.uk>