2 .TH macros 3 "13 December 2003" "Straylight/Edgeware" "mLib utilities library"
4 macros \- useful macros
36 .\" @MUFFLE_WARNINGS_DECL
37 .\" @MUFFLE_WARNINGS_EXPR
38 .\" @MUFFLE_WARNINGS_STMT
43 .B "#include <mLib/macros.h>"
45 .BI "size_t N(" array ");"
46 .BI "STR(" tokens\fR... ")"
47 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
48 .BI "STATIC_ASSERT(" cond ", " msg ");"
50 .BI "ISALNUM(int " ch ");"
51 .BI "ISALPHA(int " ch ");"
52 .BI "ISASCII(int " ch ");"
53 .BI "ISBLANK(int " ch ");"
54 .BI "ISCNTRL(int " ch ");"
55 .BI "ISDIGIT(int " ch ");"
56 .BI "ISGRAPH(int " ch ");"
57 .BI "ISLOWER(int " ch ");"
58 .BI "ISPRINT(int " ch ");"
59 .BI "ISPUNCT(int " ch ");"
60 .BI "ISSPACE(int " ch ");"
61 .BI "ISUPPER(int " ch ");"
62 .BI "ISXDIGIT(int " ch ");"
63 .BI "TOASCII(int " ch ");"
64 .BI "TOLOWER(int " ch ");"
65 .BI "TOUPPER(int " ch ");"
67 .BI "MEMCMP(const void *" x ", " op ", const void *" y ", size_t " n ");"
68 .BI "STRCMP(const char *" x ", " op ", const char *" y ");"
69 .BI "STRNCMP(const char *" x ", " op ", const char *" y ", size_t " n ");"
71 .BI "void DISCARD(" scalar ");"
72 .BI "void IGNORE(" variable ");"
74 .BI "DEPRECATED(" msg ")"
75 .BI "EXECL_LIKE(" ntrail ")"
78 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
79 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
81 .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
82 .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
83 .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
85 .BI "GCC_WARNING(" option ")"
86 .BI "CLANG_WARNING(" option ")"
92 macro returns the number of elements in the named
97 macro expands to a string literal containing the result of expanding its
103 macro expands to a single token, which is the result of gluing together
104 the tokens resulting from expanding its argument token lists. Each of
105 the argument token lists must expand to a single preprocessing token,
106 and the result of gluing these tokens together must be valid
111 causes compilation to fail if the integer constant expression
113 evaluates to zero. This macro uses the C11
115 declaration if available, and the
117 will be reported in the compiler's diagnostic messsage; otherwise, the macro
118 falls back to a somewhat ugly hack which currently ignores the
125 macros are wrappers around the corresponding standard
127 macros with the corresponding lowercase names. They take care of
128 forcing the character argument
131 .BR "unsigned char" :
132 this conversion is necessary on platforms with signed
134 to avoid passing negative values into the standard macros.
141 macros are wrappers around the standard
143 functions with the corresponding lowercase names. They take an
146 which is a equality or ordering operator (e.g.,
150 inserted between the two operands. The standard functions return a
151 false value if and only if the operands are equal, which is
152 counterintuitive and leads to mistakes; requiring an explicit relational
153 operator should reduce the number of such mistakes.
157 macro discards its argument, which must be of some scalar type. This
158 can be useful in muffling warnings about ignoring return codes in cases
159 where you really don't care.
163 macro ignores its argument, which may be an expression of any type.
164 This can be useful in muffling warnings about unused variables.
166 The following annotations can be attached to function declarations and
167 definitions, as part of the declaration specifiers. (Other positions
168 may also work, depending on your compiler, but don't bet on it.) They
169 might not have any effect, depending on your specific compiler.
170 Currently only GCC is well supported, but exactly which features are
171 available depend on the compiler version.
173 Using a function or variable marked as
175 may provoke a compiler warning; this warning may (depending on your
176 compiler version) include the given
179 A variadic function marked as
181 must be called with a null pointer (i.e., an integer constant
182 expression with value 0, cast to
184 in the variadic part of its argument list, followed by
186 further arguments. Typically,
188 is zero. Compilers may warn about misuse of such functions.
190 A function or variable marked as
192 need not be used. This may muffle warnings about leaving the marked
197 must not return. It must have return type
199 This may be useful in muffling warnings about uninitialized variables,
202 A variadic function marked as
206 format argument (in position
208 counting from 1) and a variable-length list of arguments to be formatted
209 (starting from position
211 Compilers may warn about misuse of such functions.
213 A variadic function marked as
217 format argument (in position
219 counting from 1) and a variable-length list of arguments to be formatted
220 (starting from position
222 Compilers may warn about misuse of such functions.
223 .SS Muffling warnings
224 Some compilers allow you to muffle warnings in particular pieces of
225 code. These macros provide a compiler-neutral interface to such
226 facilities. Each macro takes an argument
228 which is a sequence of calls to
229 .IB compiler _WARNING
230 macros listing the warnings to be muffled. The list may contain
231 warnings for several different compilers. The other argument is a
233 consisting of declarations (in the case of
234 .BR MUFFLE_WARNINGS_DECL ),
236 .BR MUFFLE_WARNINGS_EXPR ),
238 .BR MUFFLE_WARNINGS_STMT ).
239 .SS GCC-specific features
242 macro returns a nonzero value if the compiler is at least version
244 of GCC, and zero otherwise. It's useful in preprocessor conditions.
248 macro is intended to be used in
250 lists (see above). It takes a string-literal argument
252 naming a GCC warning option, e.g.,
253 .BR """\-Wdiv-by-zero""" .
257 is similar, except that it works with the Clang compiler.
261 also defines the compiler-test macros in
262 .BR <mLib/compiler.h>;
269 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob