2 .TH macros 3 "13 December 2003" "Straylight/Edgeware" "mLib utilities library"
4 macros \- useful macros
16 .\" @MUFFLE_WARNINGS_DECL
17 .\" @MUFFLE_WARNINGS_EXPR
18 .\" @MUFFLE_WARNINGS_STMT
23 .B "#include <mLib/macros.h>"
25 .BI "size_t N(" array ");"
26 .BI "STR(" tokens\fR... ")"
27 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
29 .BI "void DISCARD(" scalar ");"
30 .BI "void IGNORE(" variable ");"
32 .BI "DEPRECATED(" msg ")"
33 .BI "EXECL_LIKE(" ntrail ")"
36 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
37 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
39 .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
40 .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
41 .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
43 .BI "int GCC_VERSION_P(" maj ", " min ");"
44 .BI "GCC_WARNING(" option ")"
50 macro returns the number of elements in the named
55 macro expands to a string literal containing the result of expanding its
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
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.
75 macro ignores its argument, which may be an expression of any type.
76 This can be useful in muffling warnings about unused variables.
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.
85 Using a function or variable marked as
87 may provoke a compiler warning; this warning may (depending on your
88 compiler version) include the given
91 A variadic function marked as
93 must be called with a null pointer (i.e., an integer constant
94 expression with value 0, cast to
96 in the variadic part of its argument list, followed by
98 further arguments. Typically,
100 is zero. Compilers may warn about misuse of such functions.
102 A function or variable marked as
104 need not be used. This may muffle warnings about leaving the marked
109 must not return. It must have return type
111 This may be useful in muffling warnings about uninitialized variables,
114 A variadic function marked as
118 format argument (in position
120 counting from 1) and a variable-length list of arguments to be formatted
121 (starting from position
123 Compilers may warn about misuse of such functions.
125 A variadic function marked as
129 format argument (in position
131 counting from 1) and a variable-length list of arguments to be formatted
132 (starting from position
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
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
145 consisting of declarations (in the case of
146 .BR MUFFLE_WARNINGS_DECL ),
148 .BR MUFFLE_WARNINGS_EXPR ),
150 .BR MUFFLE_WARNINGS_STMT ).
151 .SS GCC-specific features
154 macro returns a nonzero value if the compiler is at least version
156 of GCC, and zero otherwise. It's useful in preprocessor conditions.
160 macro is intended to be used in
162 lists (see above). It takes a string-literal argument
164 naming a GCC warning option, e.g.,
165 .BR """\-Wdiv-by-zero""" .
169 Mark Wooding, <mdw@distorted.org.uk>