chiark - git - mdw - mLib/blob - utils/macros.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for miscellaneous macros
   4 .\"
   5 .\" (c) 2003, 2005, 2009, 2013, 2018, 2019, 2022, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH macros 3mLib "13 December 2003" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @N
  33 .\" @STR
  34 .\" @GLUE
  35 .\" @GLUE3
  36 .\" @STATIC_ASSERT
  37 .\" @CHECK_TYPE
  38 .\" @CONVERT_CAREFULLY
  39 .\" @UNCONST
  40 .\" @UNVOLATILE
  41 .\" @UNQUALIFY
  42 .\" @COMMA
  43 .
  44 .\" @ISALNUM
  45 .\" @ISALPHA
  46 .\" @ISASCII
  47 .\" @ISBLANK
  48 .\" @ISCNTRL
  49 .\" @ISDIGIT
  50 .\" @ISGRAPH
  51 .\" @ISLOWER
  52 .\" @ISPRINT
  53 .\" @ISPUNCT
  54 .\" @ISSPACE
  55 .\" @ISUPPER
  56 .\" @ISXDIGIT
  57 .\" @TOASCII
  58 .\" @TOLOWER
  59 .\" @TOUPPER
  60 .
  61 .\" @MEMCMP
  62 .\" @STRCMP
  63 .\" @STRNCMP
  64 .
  65 .\" @DISCARD
  66 .\" @IGNORE
  67 .\" @LAUNDER
  68 .\" @ADMIRE
  69 .\" @ADMIRE_BUF
  70 .\" @RELAX
  71 .
  72 .\" @DEPRECATED
  73 .\" @IGNORABLE
  74 .\" @MUST_CHECK
  75 .\" @NORETURN
  76 .\" @PRINTF_LIKE
  77 .\" @SCANF_LIKE
  78 .\" @EXECL_LIKE
  79 .
  80 .\" @MUFFLE_WARNINGS_DECL
  81 .\" @MUFFLE_WARNINGS_EXPR
  82 .\" @MUFFLE_WARNINGS_STMT
  83 .\" @GCC_WARNING
  84 .\" @CLANG_WARNING
  85 .
  86 .\"--------------------------------------------------------------------------
  87 .SH NAME
  88 macros \- useful macros
  89 .
  90 .\"--------------------------------------------------------------------------
  91 .SH SYNOPSIS
  92 .
  93 .nf
  94 .B "#include <mLib/macros.h>"
  95 .PP
  96 .BI "size_t N(" type " " array "[]);"
  97 .BI "STR(" tokens\fR... ")"
  98 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
  99 .BI "GLUE3(" tokens\fR... ", " tokens\fR... ", " tokens\fR... ")"
 100 .BI "STATIC_ASSERT(" cond ", " msg ");"
 101 .BI "int CHECK_TYPE(" expty ", " expty " " x );
 102 .IB newty " CONVERT_CAREFULLY(" newty ", " expty ", " expty " " x );
 103 .IB type " *UNCONST(" type ", const " type " *" p );
 104 .IB type " *UNVOLATILE(" type ", volatile " type " *" p );
 105 .IB type " *UNQUALIFY(" type ", const volatile " type " *" p );
 106 .B "#define COMMA ,"
 107 .PP
 108 .BI "ISALNUM(int " ch ");"
 109 .BI "ISALPHA(int " ch ");"
 110 .BI "ISASCII(int " ch ");"
 111 .BI "ISBLANK(int " ch ");"
 112 .BI "ISCNTRL(int " ch ");"
 113 .BI "ISDIGIT(int " ch ");"
 114 .BI "ISGRAPH(int " ch ");"
 115 .BI "ISLOWER(int " ch ");"
 116 .BI "ISPRINT(int " ch ");"
 117 .BI "ISPUNCT(int " ch ");"
 118 .BI "ISSPACE(int " ch ");"
 119 .BI "ISUPPER(int " ch ");"
 120 .BI "ISXDIGIT(int " ch ");"
 121 .BI "TOASCII(int " ch ");"
 122 .BI "TOLOWER(int " ch ");"
 123 .BI "TOUPPER(int " ch ");"
 124 .PP
 125 .BI "MEMCMP(const void *" x ", " op ", const void *" y ", size_t " n ");"
 126 .BI "STRCMP(const char *" x ", " op ", const char *" y ");"
 127 .BI "STRNCMP(const char *" x ", " op ", const char *" y ", size_t " n ");"
 128 .PP
 129 .BI "void DISCARD(" scalar ");"
 130 .BI "void IGNORE(" variable ");"
 131 .IB type " LAUNDER(" type " " x ");"
 132 .BI "void ADMIRE(" type " " x ");"
 133 .BI "void ADMIRE_BUF(void *" p ", size_t " sz ");"
 134 .B "void RELAX;"
 135 .PP
 136 .BI "DEPRECATED(" msg ")"
 137 .BI "EXECL_LIKE(" ntrail ")"
 138 .BI "IGNORABLE"
 139 .BI "MUST_CHECK"
 140 .BI "NORETURN"
 141 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
 142 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
 143 .PP
 144 .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
 145 .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
 146 .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
 147 .PP
 148 .BI "GCC_WARNING(" option ")"
 149 .BI "CLANG_WARNING(" option ")"
 150 .fi
 151 .
 152 .\"--------------------------------------------------------------------------
 153 .SH DESCRIPTION
 154 .
 155 .SS Utilities
 156 The
 157 .B N
 158 macro returns the number of elements in the named
 159 .IR array .
 160 .PP
 161 The
 162 .B STR
 163 macro expands to a string literal containing the result of expanding its
 164 argument
 165 .IR tokens .
 166 .PP
 167 The
 168 .B GLUE
 169 macro expands to a single token, which is the result of gluing together
 170 the tokens resulting from expanding its argument token lists.  Each of
 171 the argument token lists must expand to a single preprocessing token,
 172 and the result of gluing these tokens together must be valid
 173 preprocessing token.  The
 174 .B GLUE3
 175 macro does the same, except that it glues together
 176 .I three
 177 argument token lists rather than two.
 178 .PP
 179 The
 180 .B STATIC_ASSERT
 181 macro causes compilation to fail if the integer constant expression
 182 .I cond
 183 evaluates to zero.  This macro uses the C11
 184 .B static_assert
 185 declaration if available, and the
 186 .I msg
 187 will be reported in the compiler's diagnostic messsage; otherwise, the macro
 188 falls back to a somewhat ugly hack which currently ignores the
 189 .IR msg .
 190 .PP
 191 The
 192 .B CHECK_TYPE
 193 macro checks at compile-time that
 194 .I x
 195 has (or, at least, is assignment-compatible with) type
 196 .IR expty .
 197 If so, the result is the integer zero.
 198 The
 199 .B CONVERT_CAREFULLY
 200 macro similarly checks at compile-time that
 201 .I x
 202 has type
 203 .IR expty ,
 204 and if so, the result is
 205 .I x
 206 converted to type
 207 .IR newty .
 208 .PP
 209 The
 210 .B UNCONST
 211 macro checks at compile-time that
 212 .I p
 213 has (or, at least, is assignment-compatible with) type
 214 .BI "const " type "\ *" \fR.
 215 If so, it returns
 216 .I p
 217 converted to type
 218 .IB type "\ *" \fR,
 219 i.e., it removes any
 220 .B const
 221 qualification from the type that
 222 .I p
 223 points to.
 224 The
 225 .B UNVOLATILE
 226 macro is similar, except that it removes any
 227 .B volatile
 228 qualification;
 229 and the
 230 .B UNQUALIFY
 231 macro
 232 removes any
 233 .B const
 234 .I or
 235 .B volatile
 236 qualification.
 237 .PP
 238 The
 239 .B COMMA
 240 macro expands to a comma
 241 .BR ` , ',
 242 which is useful for smuggling commas into macro arguments
 243 if they can't be protected by parentheses.
 244 .PP
 245 The
 246 .BR IS ...\&
 247 and
 248 .BR TO ...\&
 249 macros are wrappers around the corresponding standard
 250 .B <ctype.h>
 251 macros with the corresponding lowercase names.  They take care of
 252 forcing the character argument
 253 .I ch
 254 to
 255 .BR "unsigned char" :
 256 this conversion is necessary on platforms with signed
 257 .B char
 258 to avoid passing negative values into the standard macros.
 259 .PP
 260 The
 261 .BR MEMCMP ,
 262 .BR STRCMP ,
 263 and
 264 .B STRNCMP
 265 macros are wrappers around the standard
 266 .B <string.h>
 267 functions with the corresponding lowercase names.  They take an
 268 additional argument
 269 .I op
 270 which is a equality or ordering operator (e.g.,
 271 .B ==
 272 or
 273 .BR > )
 274 inserted between the two operands.  The standard functions return a
 275 false value if and only if the operands are equal, which is
 276 counterintuitive and leads to mistakes; requiring an explicit relational
 277 operator should reduce the number of such mistakes.
 278 .PP
 279 The
 280 .B DISCARD
 281 macro discards its argument, which must be of some scalar type.  This
 282 can be useful in muffling warnings about ignoring return codes in cases
 283 where you really don't care.
 284 .PP
 285 The
 286 .B IGNORE
 287 macro ignores its argument, which may be an expression of any type.
 288 This can be useful in muffling warnings about unused variables.
 289 .PP
 290 The
 291 .B LAUNDER
 292 macro tries to confuse a compiler so that it `forgets' what it knows
 293 about a particular value.
 294 .PP
 295 The
 296 .B ADMIRE
 297 macro tries to confuse a compiler so that it will faithfully computes
 298 the argument
 299 .I x
 300 even though it's not used for anything.  The
 301 .B ADMIRE_BUF
 302 macro works similarly, but on regions of memory.
 303 .PP
 304 The
 305 .B RELAX
 306 macro tries do nothing, but in a way that a compiler won't optimize
 307 away.
 308 .PP
 309 The
 310 .BR LAUNDER ,
 311 .BR ADMIRE ,
 312 .BR ADMIRE_BUF ,
 313 and
 314 .B RELAX
 315 macros are most useful in benchmarking and similar applications.
 316 .SS Annotations
 317 The following annotations can be attached to function declarations and
 318 definitions, as part of the declaration specifiers.  (Other positions
 319 may also work, depending on your compiler, but don't bet on it.)  They
 320 might not have any effect, depending on your specific compiler.
 321 Currently only GCC is well supported, but exactly which features are
 322 available depend on the compiler version.
 323 .PP
 324 Using a function or variable marked as
 325 .B DEPRECATED
 326 may provoke a compiler warning; this warning may (depending on your
 327 compiler version) include the given
 328 .IR msg .
 329 .PP
 330 A variadic function marked as
 331 .B EXECL_LIKE
 332 must be called with a null pointer (i.e., an integer constant
 333 expression with value 0, cast to
 334 .BR "void *")
 335 in the variadic part of its argument list, followed by
 336 .I ntrail
 337 further arguments.  Typically,
 338 .I ntrail
 339 is zero.  Compilers may warn about misuse of such functions.
 340 .PP
 341 A function or variable marked as
 342 .B IGNORABLE
 343 need not be used.  This may muffle warnings about leaving the marked
 344 definition unused.
 345 .PP
 346 A function marked as
 347 .B MUST_CHECK
 348 returns an important value: a warning may be issued if a caller
 349 ignores the value.  The return type must not be
 350 .BR void .
 351 .PP
 352 A function marked as
 353 .B NORETURN
 354 must not return.  It must have return type
 355 .BR void .
 356 This may be useful in muffling warnings about uninitialized variables,
 357 for example.
 358 .PP
 359 A variadic function marked as
 360 .B PRINTF_LIKE
 361 takes a
 362 .BR printf (3)-style
 363 format argument (in position
 364 .IR fmt-index ,
 365 counting from 1) and a variable-length list of arguments to be formatted
 366 (starting from position
 367 .IR arg-index ).
 368 Compilers may warn about misuse of such functions.
 369 .PP
 370 A variadic function marked as
 371 .B SCANF_LIKE
 372 takes a
 373 .BR scanf (3)-style
 374 format argument (in position
 375 .IR fmt-index ,
 376 counting from 1) and a variable-length list of arguments to be formatted
 377 (starting from position
 378 .IR arg-index ).
 379 Compilers may warn about misuse of such functions.
 380 .
 381 .SS Muffling warnings
 382 Some compilers allow you to muffle warnings in particular pieces of
 383 code.  These macros provide a compiler-neutral interface to such
 384 facilities.  Each macro takes an argument
 385 .IR warns ,
 386 which is a sequence of calls to
 387 .IB compiler _WARNING
 388 macros listing the warnings to be muffled.  The list may contain
 389 warnings for several different compilers.  The other argument is a
 390 .I body
 391 consisting of declarations (in the case of
 392 .BR MUFFLE_WARNINGS_DECL ),
 393 an expression (for
 394 .BR MUFFLE_WARNINGS_EXPR ),
 395 or a statement (for
 396 .BR MUFFLE_WARNINGS_STMT ).
 397 .
 398 .SS GCC-specific features
 399 The
 400 .B GCC_WARNING
 401 macro is intended to be used in
 402 .I warns
 403 lists (see above).  It takes a string-literal argument
 404 .I option
 405 naming a GCC warning option, e.g.,
 406 .BR """\-Wdiv-by-zero""" .
 407 .PP
 408 The
 409 .B CLANG_WARNING
 410 is similar, except that it works with the Clang compiler.
 411 .PP
 412 Note that including
 413 .B <mLib/macros.h>
 414 also defines the compiler-test macros in
 415 .BR <mLib/compiler.h>;
 416 see
 417 .BR compiler (3).
 418 .
 419 .\"--------------------------------------------------------------------------
 420 .SH "SEE ALSO"
 421 .
 422 .BR compiler (3).
 423 .BR mLib (3),
 424 .
 425 .\"--------------------------------------------------------------------------
 426 .SH "AUTHOR"
 427 .
 428 Mark Wooding, <mdw@distorted.org.uk>
 429 .
 430 .\"----- That's all, folks --------------------------------------------------