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