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
22 .B "#include <mLib/macros.h>"
24 .BI "size_t N(" array ");"
25 .BI "STR(" tokens\fR... ")"
26 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
28 .BI "void DISCARD(" scalar ");"
29 .BI "void IGNORE(" variable ");"
31 .BI "DEPRECATED(" msg ")"
32 .BI "EXECL_LIKE(" ntrail ")"
35 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
36 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
38 .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
39 .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
40 .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
42 .BI "GCC_WARNING(" option ")"
43 .BI "CLANG_WARNING(" option ")"
49 macro returns the number of elements in the named
54 macro expands to a string literal containing the result of expanding its
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
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.
74 macro ignores its argument, which may be an expression of any type.
75 This can be useful in muffling warnings about unused variables.
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.
84 Using a function or variable marked as
86 may provoke a compiler warning; this warning may (depending on your
87 compiler version) include the given
90 A variadic function marked as
92 must be called with a null pointer (i.e., an integer constant
93 expression with value 0, cast to
95 in the variadic part of its argument list, followed by
97 further arguments. Typically,
99 is zero. Compilers may warn about misuse of such functions.
101 A function or variable marked as
103 need not be used. This may muffle warnings about leaving the marked
108 must not return. It must have return type
110 This may be useful in muffling warnings about uninitialized variables,
113 A variadic function marked as
117 format argument (in position
119 counting from 1) and a variable-length list of arguments to be formatted
120 (starting from position
122 Compilers may warn about misuse of such functions.
124 A variadic function marked as
128 format argument (in position
130 counting from 1) and a variable-length list of arguments to be formatted
131 (starting from position
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
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
144 consisting of declarations (in the case of
145 .BR MUFFLE_WARNINGS_DECL ),
147 .BR MUFFLE_WARNINGS_EXPR ),
149 .BR MUFFLE_WARNINGS_STMT ).
150 .SS GCC-specific features
153 macro returns a nonzero value if the compiler is at least version
155 of GCC, and zero otherwise. It's useful in preprocessor conditions.
159 macro is intended to be used in
161 lists (see above). It takes a string-literal argument
163 naming a GCC warning option, e.g.,
164 .BR """\-Wdiv-by-zero""" .
168 is similar, except that it works with the Clang compiler.
172 also defines the compiler-test macros in
173 .BR <mLib/compiler.h>;
180 Mark Wooding, <mdw@distorted.org.uk>