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