chiark - git - mdw - mLib/blob - utils/macros.h

   1 /* -*-c-*-
   2  *
   3  * Handy macros
   4  *
   5  * (c) 2003 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
  13  * it under the terms of the GNU Library General Public License as
  14  * published by the Free Software Foundation; either version 2 of the
  15  * License, or (at your option) any later version.
  16  *
  17  * mLib is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU Library General Public 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
  24  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  25  * MA 02111-1307, USA.
  26  */
  27
  28 #ifndef MLIB_MACROS_H
  29 #define MLIB_MACROS_H
  30
  31 #ifdef __cplusplus
  32   extern "C" {
  33 #endif
  34
  35 /*----- Header files ------------------------------------------------------*/
  36
  37 #include <assert.h>
  38
  39 #ifndef MLIB_COMPILER_H
  40 #  include "compiler.h"
  41 #endif
  42
  43 /*----- Miscellaneous utility macros --------------------------------------*/
  44
  45 /* --- @N@ --- *
  46  *
  47  * Arguments:   @type v[]@ = an actual array, not a pointer
  48  *
  49  * Returns:     The number of elements in @v@.
  50  */
  51
  52 #define N(v) (sizeof(v)/sizeof(*(v)))
  53
  54 /* --- @STR@ --- *
  55  *
  56  * Arguments:   @x@ = some tokens
  57  *
  58  * Returns:     A string literal containing the macro-expanded text of @x@.
  59  */
  60
  61 #define MLIB__STR(x) #x
  62 #define STR(x) MLIB__STR(x)
  63
  64 /* --- @GLUE@, @GLUE3@ --- *
  65  *
  66  * Arguments:   @x, y@ = two sequences of tokens
  67  *              @z@ = a third sequence of tokens
  68  *
  69  * Returns:     A single token formed by gluing together the macro-expansions
  70  *              of @x@ and @y@, and @z@ for @GLUE3@.
  71  */
  72
  73 #define MLIB__GLUE(x, y) x##y
  74 #define GLUE(x, y) MLIB__GLUE(x, y)
  75 #define GLUE3(x, y, z) GLUE(x, MLIB__GLUE(y, z))
  76
  77 /* --- @STATIC_ASSERT@ --- *
  78  *
  79  * Arguments:   @int cond@ = a condition
  80  *              @msg@ = a string literal message
  81  *
  82  * Returns:     ---
  83  *
  84  * Use:         Fail at compile time unless @cond@ is nonzero.  The failure
  85  *              might report @msg@.
  86  */
  87
  88 #ifdef static_assert
  89 #  define STATIC_ASSERT(cond, msg) static_assert(!!(cond), msg)
  90 #else
  91 #  define STATIC_ASSERT(cond, msg)                                      \
  92         IGNORABLE extern char static_assert_failed[1 - 2*!(cond)]
  93 #endif
  94
  95 /* --- @CHECK_TYPE@ --- *
  96  *
  97  * Arguments:   @expty@ = expected type of @x@
  98  *              @expty x@ = some object
  99  *
 100  * Returns:     Integer zero.
 101  *
 102  * Use:         Cause a compile-time failure unless the type of @x@ is
 103  *              assignment-compatible with @expty@.
 104  */
 105
 106 #define CHECK_TYPE(expty, x) (!sizeof(*(expty *)0 = (x)))
 107
 108 /* --- @CONVERT_CAREFULLY@ --- *
 109  *
 110  * Arguments:   @newty@ = new type for the result
 111  *              @expty@ = expected type of @x@
 112  *              @expty x@ = some object
 113  *
 114  * Returns:     @x@, but coerced to type @newty@.
 115  *
 116  * Use:         Like @(newty)x@, except that it checks at compile-time that
 117  *              @x@ is at least assignment-compatible with type @expty@
 118  *              before trying.
 119  */
 120
 121 #define CONVERT_CAREFULLY(newty, expty, x)                              \
 122         (CHECK_TYPE(expty, x) + (/*unconst unvolatile*/ newty)(x))
 123
 124 /* --- @CONTAINER@ --- *
 125  *
 126  * Arguments:   @type@ = the parent type, a structure or union
 127  *              @mem@ = the name of the member we have a pointer to
 128  *              @memty *p@ = pointer to @member@ within @type@
 129  *
 130  * Returns:     The address of the containing @ty@ object.
 131  */
 132
 133 #define CONTAINER(type, mem, p)                                         \
 134         (!sizeof((p) = &((type *)0)->mem) +                             \
 135          (type *)((unsigned char *)(p) - offsetof(type, mem)))
 136
 137 /* --- @UNCONST@, @UNVOLATILE@, @UNQUALIFY@ --- *
 138  *
 139  * Arguments:   @type@ = a type name
 140  *              @type *p@ = a pointer
 141  *
 142  * Returns:     @p@, but without @const@, @volatile@ or both qualifiers.
 143  *
 144  * Use:         Strips qualifiers from pointer types.
 145  *
 146  *              The @UNCONST@ macro strips @const@.  It checks that @p@
 147  *              has type `pointer to @type@ or @const type@'; if not, a
 148  *              compile-time error results.  Otherwise, it returns the value
 149  *              of @p@, converted to `pointer to (non-constant) @type@'.  It
 150  *              will not silently strip a @volatile@ qualifier.
 151  *
 152  *              The @UNVOLATILE@ macro is similar, except that it strips
 153  *              @volatile@ instead of @const@.  The @UNQUALIFY@ macro strips
 154  *              both qualifiers.
 155  */
 156
 157 #define UNCONST(type, p) CONVERT_CAREFULLY(type *, const type *, p)
 158 #define UNVOLATILE(type, p) CONVERT_CAREFULLY(type *, volatile type *, p)
 159 #define UNQUALIFY(type, p)                                              \
 160         CONVERT_CAREFULLY(type *, const volatile type *, p)
 161
 162 /* --- @EMPTY@ --- *
 163  *
 164  * Arguments:   ---
 165  *
 166  * Returns:     The empty token sequence.
 167  */
 168
 169 #define EMPTY
 170
 171 /* --- @COMMA@ --- *
 172  *
 173  * Arguments:   ---
 174  *
 175  * Returns:     A `%|,|%' token, which can be usefully passed to macros to
 176  *              avoid argument splitting.
 177  */
 178
 179 #define COMMA ,
 180
 181 /*----- String and character hacks ----------------------------------------*/
 182
 183 /* --- @IS...@ --- *
 184  *
 185  * Arguments:   @int ch@ = a character code, but not @EOF@
 186  *
 187  * Returns:     Nonzero if @ch@ is in the relevant @<ctype.h>@ category.
 188  *
 189  * Use:         Classifies characters, but safely even if characters are
 190  *              signed.
 191  *
 192  *              There is a macro for each of the @<ctype.h>@ @is...@
 193  *              functions.
 194  */
 195
 196 #define CTYPE_HACK(func, ch) (func((unsigned char)(ch)))
 197
 198 #define ISALNUM(ch) CTYPE_HACK(isalnum, ch)
 199 #define ISALPHA(ch) CTYPE_HACK(isalpha, ch)
 200 #define ISASCII(ch) CTYPE_HACK(isascii, ch)
 201 #define ISBLANK(ch) CTYPE_HACK(isblank, ch)
 202 #define ISCNTRL(ch) CTYPE_HACK(iscntrl, ch)
 203 #define ISDIGIT(ch) CTYPE_HACK(isdigit, ch)
 204 #define ISGRAPH(ch) CTYPE_HACK(isgraph, ch)
 205 #define ISLOWER(ch) CTYPE_HACK(islower, ch)
 206 #define ISPRINT(ch) CTYPE_HACK(isprint, ch)
 207 #define ISPUNCT(ch) CTYPE_HACK(ispunct, ch)
 208 #define ISSPACE(ch) CTYPE_HACK(isspace, ch)
 209 #define ISUPPER(ch) CTYPE_HACK(isupper, ch)
 210 #define ISXDIGIT(ch) CTYPE_HACK(isxdigit, ch)
 211
 212 /* --- @TO...@ --- *
 213  *
 214  * Arguments:   @int ch@ = a character code, but not @EOF@
 215  *
 216  * Returns:     The converted character code.
 217  *
 218  * Use:         Converts characters, but safely even if characters are
 219  *              signed.
 220  *
 221  *              There is a macro for each of the @<ctype.h>@ @to...@
 222  *              functions.
 223  */
 224
 225 #define TOASCII(ch) CTYPE_HACK(toascii, ch)
 226 #define TOLOWER(ch) CTYPE_HACK(tolower, ch)
 227 #define TOUPPER(ch) CTYPE_HACK(toupper, ch)
 228
 229 /* --- @MEMCMP@, @STRCMP@, @STRNCMP@ --- *
 230  *
 231  * Arguments:   @const type *x, *y@ = pointers to strings
 232  *              @op@ = a relational operator symbol
 233  *              @size_t n@ = length of the strings
 234  *
 235  * Returns:     Nonzero if the relationship between the strings satisfies the
 236  *              operator @op@, otherwise zero.
 237  *
 238  * Use:         These macros mitigate the author's frequent error of failing
 239  *              to compare the result of the underlying standard functions
 240  *              against zero, effectively reversing the sense of an intended
 241  *              test for equality.
 242  */
 243
 244 #define MEMCMP(x, op, y, n) (memcmp((x), (y), (n)) op 0)
 245 #define STRCMP(x, op, y) (strcmp((x), (y)) op 0)
 246 #define STRNCMP(x, op, y, n) (strncmp((x), (y), (n)) op 0)
 247
 248 /*----- Compiler-specific definitions -------------------------------------*/
 249
 250 /* The descriptions of these are given below, with the fallback
 251  * definitions.
 252  */
 253
 254 #if GCC_VERSION_P(2, 5) || CLANG_VERSION_P(3, 3)
 255 #  define NORETURN __attribute__((__noreturn__))
 256 #  define PRINTF_LIKE(fix, aix) __attribute__((__format__(printf, fix, aix)))
 257 #  define SCANF_LIKE(fix, aix) __attribute__((__format__(scanf, fix, aix)))
 258 #  define IGNORABLE __attribute__((__unused__))
 259 #endif
 260
 261 #if GCC_VERSION_P(3, 4) || CLANG_VERSION_P(3, 3)
 262 #  define MUST_CHECK __attribute__((__warn_unused_result__))
 263 #endif
 264
 265 #if GCC_VERSION_P(4, 5) || CLANG_VERSION_P(3, 3)
 266 #  define DEPRECATED(msg) __attribute__((__deprecated__(msg)))
 267 #elif GCC_VERSION_P(3, 1)
 268 #  define DEPRECATED(msg) __attribute__((__deprecated__))
 269 #endif
 270
 271 #if GCC_VERSION_P(4, 0) || CLANG_VERSION_P(3, 3)
 272 #  define EXECL_LIKE(ntrail) __attribute__((__sentinel__(ntrail)))
 273 #endif
 274
 275 #if GCC_VERSION_P(2, 7) || CLANG_VERSION_P(0, 0)
 276 #  define LAUNDER(x)                                                    \
 277         ({ __typeof__(x) _y; __asm__("" : "=g"(_y) : "0"(x)); _y; })
 278 #  define ADMIRE(x)                                                     \
 279         ({ __asm__("" :: "g"(x)); })
 280 #  define ADMIRE_BUF(p, sz)                                             \
 281         ({ __asm__("" :: "m"(*(unsigned char *)p), "g"(sz) : "memory"); })
 282 #  define RELAX do __asm__(""); while (0)
 283 #endif
 284
 285 #if CLANG_VERSION_P(3, 3)
 286
 287 #  define MLIB__PRAGMA_HACK(x) _Pragma(#x)
 288 #  define MLIB__MUFFLE_WARNINGS(warns, body)                            \
 289         _Pragma("clang diagnostic push")                                \
 290         warns                                                           \
 291         body                                                            \
 292         _Pragma("clang diagnostic pop")
 293 #  define CLANG_WARNING(warn)                                           \
 294         MLIB__PRAGMA_HACK(clang diagnostic ignored warn)
 295 #  define MUFFLE_WARNINGS_DECL(warns, body)                             \
 296         MLIB__MUFFLE_WARNINGS(warns, body)
 297 #  define MUFFLE_WARNINGS_EXPR(warns, body)                             \
 298         __extension__ ({ MLIB__MUFFLE_WARNINGS(warns, (body);) })
 299 #  define MUFFLE_WARNINGS_STMT(warns, body)                             \
 300         do { MLIB__MUFFLE_WARNINGS(warns, body) } while (0)
 301
 302 #endif
 303
 304 #if GCC_VERSION_P(4, 6)
 305
 306    /* --- Diagnostic suppression in GCC: a tale of woe --- *
 307     *
 308     * This is extremely unpleasant, largely as a result of bugs in the GCC
 309     * preprocessor's handling of @_Pragma@.  The fundamental problem is
 310     * that it's the preprocessor, and not the compiler proper, which
 311     * detects @_Pragma@, emitting @#pragma@ lines into its output; and it
 312     * does it during macro expansion, even if the macro is being expanded
 313     * during argument collection.  Since arguments are expanded before
 314     * replacing the macro's invocation with its body, a pragma in an
 315     * argument will be emitted %%\emph{before}%% any pragmata in the body,
 316     * even if they appear before the argument in the body -- and even if
 317     * the argument doesn't actually appear anywhere at all in the body.
 318     *
 319     * Another, rather less significant, problem is that @_Pragma@'s
 320     * argument is a single string literal, recognized in translation phase
 321     * 4, before string-literal concatenation in phase 6, so we must build
 322     * pragma bodies as token lists and then stringify them.
 323     *
 324     * As a result, we need some subterfuge here.  The @MLIB__PRAGMA_HACK@
 325     * macro issues a @_Pragma@ on its argument token list, which it
 326     * stringifies; this deals with the second problem.  The first is
 327     * trickier: we must delay expansion of @MLIB__PRAGMA_HACK@ from the
 328     * argument collection phase to the body rescanning phase, and we do
 329     * this by splitting the invocations between @GCC_WARNING@ macro calls:
 330     * the name is left hanging from the previous call (or from
 331     * @MLIB__MUFFLE_WARNINGS@, in the first case) and the body is supplied
 332     * by @GCC_WARNING@, which also supplies the next @MLIB__PRAGMA_HACK@.
 333     * The remaining problem is to make sure we can dispose of the final
 334     * trailing @MLIB__PRAGMA_HACK@ harmlessly, which we do by introducing
 335     * an extra argument @emitp@, which may be either @t@ or @nil@; this
 336     * dispatches to an appropriate helper macro by means of token-pasting.
 337     *
 338     * I'm so sorry.
 339     */
 340
 341 #  define MLIB__PRAGMA_HACK_t(x) _Pragma(#x)
 342 #  define MLIB__PRAGMA_HACK_nil(x)
 343 #  define MLIB__PRAGMA_HACK(emitp, x) MLIB__PRAGMA_HACK_##emitp(x)
 344 #  define MLIB__MUFFLE_WARNINGS(warns, body)                            \
 345         _Pragma("GCC diagnostic push") MLIB__PRAGMA_HACK                \
 346         warns                                                           \
 347         (nil, nil)                                                      \
 348         body                                                            \
 349         _Pragma("GCC diagnostic pop")
 350 #  define GCC_WARNING(warn)                                             \
 351         (t, GCC diagnostic ignored warn) MLIB__PRAGMA_HACK
 352 #  define MUFFLE_WARNINGS_DECL(warns, body)                             \
 353         MLIB__MUFFLE_WARNINGS(warns, body)
 354 #  define MUFFLE_WARNINGS_EXPR(warns, body)                             \
 355         __extension__ ({ MLIB__MUFFLE_WARNINGS(warns, (body);) })
 356 #  define MUFFLE_WARNINGS_STMT(warns, body)                             \
 357         do { MLIB__MUFFLE_WARNINGS(warns, body) } while (0)
 358 #endif
 359
 360 /* --- Fallback definitions, mostly trivial --- */
 361
 362 /* --- @DISCARD@ --- *
 363  *
 364  * Arguments:   @x@ = a function call
 365  *
 366  * Returns:     ---
 367  *
 368  * Use:         Explicitly discard the result of @x@.  This counteracts a
 369  *              @MUST_CHECK@ attribute on the called function.
 370  */
 371
 372 #ifndef DISCARD
 373 #  define DISCARD(x) do if (x); while (0)
 374 #endif
 375
 376 /* --- @IGNORE@ --- *
 377  *
 378  * Arguments:   @x@ = any expression
 379  *
 380  * Returns:     ---
 381  *
 382  * Use:         Ignore the value of @x@, overriding compiler warnings.
 383  */
 384
 385 #ifndef IGNORE
 386 #  define IGNORE(x) ((void)(x))
 387 #endif
 388
 389 /* --- @LAUNDER@ --- *
 390  *
 391  * Arguments:   @x@ = some integer expression
 392  *
 393  * Returns:     @x@.
 394  *
 395  * Use:         Causes a compiler to know nothing about the value of @x@,
 396  *              even if it looks obvious, e.g., it's a constant.
 397  */
 398
 399 #ifndef LAUNDER
 400 #  define LAUNDER(x) (x)
 401 #endif
 402
 403 /* --- @ADMIRE@, @ADMIRE_BUF@ --- *
 404  *
 405  * Arguments:   @x@ = some scalar expression
 406  *              @const void *p@, @size_t sz@ = a pointer and length
 407  *
 408  * Returns:     ---
 409  *
 410  * Use:         Ensures that the compiler generates code to compute @x@ or
 411  *              the contents of the buffer at @p@.
 412  */
 413
 414 #ifndef ADMIRE
 415 #  define ADMIRE(x) ((void)(x))
 416 #endif
 417 #ifndef ADMIRE_BUF
 418 #  define ADMIRE_BUF(p, sz) ((void)(p), (void)(sz))
 419 #endif
 420
 421 /* --- @RELAX@ --- *
 422  *
 423  * Arguments:   ---
 424  *
 425  * Returns:     ---
 426  *
 427  * Use:         Does nothing, but the compiler doesn't know that.
 428  */
 429
 430 #ifndef RELAX
 431 #  define RELAX
 432 #endif
 433
 434 /* --- @DEPRECATED@, @NORETURN@, @IGNORABLE@, @MUST_CHECK@ --- *
 435  *
 436  * Use:         These are (mostly) function attributes; write them among the
 437  *              declaration specifiers for a function definition or
 438  *              declaration.  These may not do anything, but the intended
 439  *              behaviour is as follows.
 440  *
 441  *                * @DEPRECATED(msg)@ -- report a warning, quoting the string
 442  *                  literal @msg@, if the function is called.
 443  *
 444  *                * @NORETURN@ -- promise that the function doesn't return to
 445  *                  its caller: either it kills the process, or it performs
 446  *                  some nonlocal transfer.
 447  *
 448  *                * @IGNORABLE@ -- the item (which might be data rather than
 449  *                  a function) might not be referred to, but that's OK:
 450  *                  don't warn about it.
 451  *
 452  *                @ @MUST_CHECK@ -- warn if the return value of a function is
 453  *                  ignored.  Use @DISCARD@ if you really don't care.
 454  */
 455
 456 #ifndef DEPRECATED
 457 #  define DEPRECATED(msg)
 458 #endif
 459
 460 #ifndef NORETURN
 461 #  define NORETURN
 462 #endif
 463
 464 #ifndef IGNORABLE
 465 #  define IGNORABLE
 466 #endif
 467
 468 #ifndef MUST_CHECK
 469 #  define MUST_CHECK
 470 #endif
 471
 472 /* --- @PRINTF_LIKE@, @SCANF_LIKE@, @EXECL_LIKE@ --- *
 473  *
 474  * Arguments:   @int fmtix@ = format string argument index (starting from 1)
 475  *              @int argix@ = variable format argument tail index (starting
 476  *                      from 1)
 477  *              @int ntrail@ = number of arguments following terminator
 478  *
 479  * Use:         These are function attributes.  Again, they might not do
 480  *              anything at all.  By intention, they give the compiler
 481  *              information about a variadic function's arguments, so that it
 482  *              can warn about misuse.
 483  *
 484  *                * @PRINTF_LIKE@ -- the function takes a @printf@-style
 485  *                  format string as argument @fmtix@ and an argument tail
 486  *                  (which may be empty) beginning with argument @argix@.
 487  *
 488  *                * @SCANF_LIKE@ -- the function takes a @scanf@-style
 489  *                  format string as argument @fmtix@ and an argument tail
 490  *                  (which may be empty) beginning with argument @argix@.
 491  *
 492  *                * @EXECL_LIKE@ -- the function takes a sequence of pointer
 493  *                  arguments terminated by a null pointer, followed by
 494  *                  @ntrail@ further arguments.
 495  */
 496
 497 #ifndef PRINTF_LIKE
 498 #  define PRINF_LIKE(fmtix, argix)
 499 #endif
 500
 501 #ifndef SCANF_LIKE
 502 #  define SCANF_LIKE(fmtix, argix)
 503 #endif
 504
 505 #ifndef EXECL_LIKE
 506 #  define EXECL_LIKE(ntrail)
 507 #endif
 508
 509 /* --- @MUFFLE_WARNINGS_...@ --- *
 510  *
 511  * Arguments:   @warns@ = a sequence of @..._WARNING@ calls (see below)
 512  *              @body@ = some program text
 513  *
 514  * Use:         Muffle specific warnings within the program text.
 515  *
 516  *              For @MUFFLE_WARNINGS_DECL@, the program text is a
 517  *              declaration; for @MUFFLE_WARNINGS_EXPR@, it is an expression,
 518  *              and for @MUFFLE_WARNINGS_STMT@, it is a statement.
 519  *
 520  *              The warnings to be muffled are given as a list of
 521  *              @..._WARNING@ macros, with no separators.  The list can
 522  *              list warnings from multiple different compilers: entries for
 523  *              irrelevant compilers will be ignored.
 524  */
 525
 526 #ifndef MUFFLE_WARNINGS_DECL
 527 #  define MUFFLE_WARNINGS_DECL(warns, body) body
 528 #endif
 529
 530 #ifndef MUFFLE_WARNINGS_EXPR
 531 #  define MUFFLE_WARNINGS_EXPR(warns, body) (body)
 532 #endif
 533
 534 #ifndef MUFFLE_WARNINGS_STMT
 535 #  define MUFFLE_WARNINGS_STMT(warns, body) do { body } while (0)
 536 #endif
 537
 538 /* --- @GCC_WARNING@ --- *
 539  *
 540  * Arguments:   @warn@ = a string literal naming a warning, with `%|-W...|%'
 541  *                      prefix
 542  *
 543  * Use:         Names a GCC warning: use within @MUFFLE_WARNINGS_...@.
 544  *
 545  *              Note that GCC's warning suppression is very buggy.
 546  */
 547
 548 #ifndef GCC_WARNING
 549 #  define GCC_WARNING(warn)
 550 #endif
 551
 552 /* --- @CLANG_WARNING@ --- *
 553  *
 554  * Arguments:   @warn@ = a string literal naming a warning, with `%|-W...|%'
 555  *                      prefix
 556  *
 557  * Use:         Names a Clang warning: use within @MUFFLE_WARNINGS_...@.
 558  */
 559
 560 #ifndef CLANG_WARNING
 561 #  define CLANG_WARNING(warn)
 562 #endif
 563
 564 /*----- That's all, folks -------------------------------------------------*/
 565
 566 #ifdef __cplusplus
 567   }
 568 #endif
 569
 570 #endif