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