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