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