2 .TH macros 3 "13 December 2003" "Straylight/Edgeware" "mLib utilities library"
4 macros \- useful macros
17 .\" @MUFFLE_WARNINGS_DECL
18 .\" @MUFFLE_WARNINGS_EXPR
19 .\" @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... ")"
28 .BI "STATIC_ASSERT(" cond ", " msg ");"
30 .BI "void DISCARD(" scalar ");"
31 .BI "void IGNORE(" variable ");"
33 .BI "DEPRECATED(" msg ")"
34 .BI "EXECL_LIKE(" ntrail ")"
37 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
38 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
40 .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
41 .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
42 .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
44 .BI "GCC_WARNING(" option ")"
45 .BI "CLANG_WARNING(" option ")"
51 macro returns the number of elements in the named
56 macro expands to a string literal containing the result of expanding its
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
70 causes compilation to fail if the integer constant expression
72 evaluates to zero. This macro uses the C11
74 declaration if available, and the
76 will be reported in the compiler's diagnostic messsage; otherwise, the macro
77 falls back to a somewhat ugly hack which currently ignores the
82 macro discards its argument, which must be of some scalar type. This
83 can be useful in muffling warnings about ignoring return codes in cases
84 where you really don't care.
88 macro ignores its argument, which may be an expression of any type.
89 This can be useful in muffling warnings about unused variables.
91 The following annotations can be attached to function declarations and
92 definitions, as part of the declaration specifiers. (Other positions
93 may also work, depending on your compiler, but don't bet on it.) They
94 might not have any effect, depending on your specific compiler.
95 Currently only GCC is well supported, but exactly which features are
96 available depend on the compiler version.
98 Using a function or variable marked as
100 may provoke a compiler warning; this warning may (depending on your
101 compiler version) include the given
104 A variadic function marked as
106 must be called with a null pointer (i.e., an integer constant
107 expression with value 0, cast to
109 in the variadic part of its argument list, followed by
111 further arguments. Typically,
113 is zero. Compilers may warn about misuse of such functions.
115 A function or variable marked as
117 need not be used. This may muffle warnings about leaving the marked
122 must not return. It must have return type
124 This may be useful in muffling warnings about uninitialized variables,
127 A variadic function marked as
131 format argument (in position
133 counting from 1) and a variable-length list of arguments to be formatted
134 (starting from position
136 Compilers may warn about misuse of such functions.
138 A variadic function marked as
142 format argument (in position
144 counting from 1) and a variable-length list of arguments to be formatted
145 (starting from position
147 Compilers may warn about misuse of such functions.
148 .SS Muffling warnings
149 Some compilers allow you to muffle warnings in particular pieces of
150 code. These macros provide a compiler-neutral interface to such
151 facilities. Each macro takes an argument
153 which is a sequence of calls to
154 .IB compiler _WARNING
155 macros listing the warnings to be muffled. The list may contain
156 warnings for several different compilers. The other argument is a
158 consisting of declarations (in the case of
159 .BR MUFFLE_WARNINGS_DECL ),
161 .BR MUFFLE_WARNINGS_EXPR ),
163 .BR MUFFLE_WARNINGS_STMT ).
164 .SS GCC-specific features
167 macro returns a nonzero value if the compiler is at least version
169 of GCC, and zero otherwise. It's useful in preprocessor conditions.
173 macro is intended to be used in
175 lists (see above). It takes a string-literal argument
177 naming a GCC warning option, e.g.,
178 .BR """\-Wdiv-by-zero""" .
182 is similar, except that it works with the Clang compiler.
186 also defines the compiler-test macros in
187 .BR <mLib/compiler.h>;
194 Mark Wooding, <mdw@distorted.org.uk>