mdw@git.distorted.org.uk Git - mLib/blob - utils/macros.3

   1 .\" -*-nroff-*-
   2 .TH macros 3 "13 December 2003" "Straylight/Edgeware" "mLib utilities library"
   3 .SH NAME
   4 macros \- useful macros
   5 .\" @N
   6 .\" @STR
   7 .\" @GLUE
   8 .\" @DISCARD
   9 .\" @IGNORE
  10 .\" @DEPRECATED
  11 .\" @EXECL_LIKE
  12 .\" @IGNORABLE
  13 .\" @NORETURN
  14 .\" @PRINTF_LIKE
  15 .\" @SCANF_LIKE
  16 .\" @MUFFLE_WARNINGS_DECL
  17 .\" @MUFFLE_WARNINGS_EXPR
  18 .\" @MUFFLE_WARNINGS_STMT
  19 .\" @GCC_WARNING
  20 .SH SYNOPSIS
  21 .nf
  22 .B "#include <mLib/macros.h>"
  23
  24 .BI "size_t N(" array ");"
  25 .BI "STR(" tokens\fR... ")"
  26 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
  27
  28 .BI "void DISCARD(" scalar ");"
  29 .BI "void IGNORE(" variable ");"
  30
  31 .BI "DEPRECATED(" msg ")"
  32 .BI "EXECL_LIKE(" ntrail ")"
  33 .BI "IGNORABLE"
  34 .BI "NORETURN"
  35 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
  36 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
  37
  38 .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
  39 .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
  40 .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
  41
  42 .BI "GCC_WARNING(" option ")"
  43 .BI "CLANG_WARNING(" option ")"
  44 .fi
  45 .SH DESCRIPTION
  46 .SS Utilities
  47 The
  48 .B N
  49 macro returns the number of elements in the named
  50 .IR array .
  51 .PP
  52 The
  53 .B STR
  54 macro expands to a string literal containing the result of expanding its
  55 argument
  56 .IR tokens .
  57 .PP
  58 The
  59 .B GLUE
  60 macro expands to a single token, which is the result of gluing together
  61 the tokens resulting from expanding its argument token lists.  Each of
  62 the argument token lists must expand to a single preprocessing token,
  63 and the result of gluing these tokens together must be valid
  64 preprocessing token.
  65 .PP
  66 The
  67 .B DISCARD
  68 macro discards its argument, which must be of some scalar type.  This
  69 can be useful in muffling warnings about ignoring return codes in cases
  70 where you really don't care.
  71 .PP
  72 The
  73 .B IGNORE
  74 macro ignores its argument, which may be an expression of any type.
  75 This can be useful in muffling warnings about unused variables.
  76 .SS Annotations
  77 The following annotations can be attached to function declarations and
  78 definitions, as part of the declaration specifiers.  (Other positions
  79 may also work, depending on your compiler, but don't bet on it.)  They
  80 might not have any effect, depending on your specific compiler.
  81 Currently only GCC is well supported, but exactly which features are
  82 available depend on the compiler version.
  83 .PP
  84 Using a function or variable marked as
  85 .B DEPRECATED
  86 may provoke a compiler warning; this warning may (depending on your
  87 compiler version) include the given
  88 .IR msg .
  89 .PP
  90 A variadic function marked as
  91 .B EXECL_LIKE
  92 must be called with a null pointer (i.e., an integer constant
  93 expression with value 0, cast to
  94 .BR "void *")
  95 in the variadic part of its argument list, followed by
  96 .I ntrail
  97 further arguments.  Typically,
  98 .I ntrail
  99 is zero.  Compilers may warn about misuse of such functions.
 100 .PP
 101 A function or variable marked as
 102 .B IGNORABLE
 103 need not be used.  This may muffle warnings about leaving the marked
 104 definition unused.
 105 .PP
 106 A function marked as
 107 .B NORETURN
 108 must not return.  It must have return type
 109 .BR void .
 110 This may be useful in muffling warnings about uninitialized variables,
 111 for example.
 112 .PP
 113 A variadic function marked as
 114 .B PRINTF_LIKE
 115 takes a
 116 .BR printf (3)-style
 117 format argument (in position
 118 .IR fmt-index ,
 119 counting from 1) and a variable-length list of arguments to be formatted
 120 (starting from position
 121 .IR arg-index ).
 122 Compilers may warn about misuse of such functions.
 123 .PP
 124 A variadic function marked as
 125 .B SCANF_LIKE
 126 takes a
 127 .BR scanf (3)-style
 128 format argument (in position
 129 .IR fmt-index ,
 130 counting from 1) and a variable-length list of arguments to be formatted
 131 (starting from position
 132 .IR arg-index ).
 133 Compilers may warn about misuse of such functions.
 134 .SS Muffling warnings
 135 Some compilers allow you to muffle warnings in particular pieces of
 136 code.  These macros provide a compiler-neutral interface to such
 137 facilities.  Each macro takes an argument
 138 .IR warns ,
 139 which is a sequence of calls to
 140 .IB compiler _WARNING
 141 macros listing the warnings to be muffled.  The list may contain
 142 warnings for several different compilers.  The other argument is a
 143 .I body
 144 consisting of declarations (in the case of
 145 .BR MUFFLE_WARNINGS_DECL ),
 146 an expression (for
 147 .BR MUFFLE_WARNINGS_EXPR ),
 148 or a statement (for
 149 .BR MUFFLE_WARNINGS_STMT ).
 150 .SS GCC-specific features
 151 The
 152 .B GCC_VERSION_P
 153 macro returns a nonzero value if the compiler is at least version
 154 .IB maj . min
 155 of GCC, and zero otherwise.  It's useful in preprocessor conditions.
 156 .PP
 157 The
 158 .B GCC_WARNING
 159 macro is intended to be used in
 160 .I warns
 161 lists (see above).  It takes a string-literal argument
 162 .I option
 163 naming a GCC warning option, e.g.,
 164 .BR """\-Wdiv-by-zero""" .
 165 .PP
 166 The
 167 .B CLANG_WARNING
 168 is similar, except that it works with the Clang compiler.
 169 .PP
 170 Note that including
 171 .B <mLib/macros.h>
 172 also defines the compiler-test macros in
 173 .BR <mLib/compiler.h>;
 174 see
 175 .BR compiler (3).
 176 .SH "SEE ALSO"
 177 .BR mLib (3),
 178 .BR compiler (3).
 179 .SH "AUTHOR"
 180 Mark Wooding, <mdw@distorted.org.uk>