2 .TH macros 3 "13 December 2003" "Straylight/Edgeware" "mLib utilities library"
4 macros \- useful macros
37 .\" @MUFFLE_WARNINGS_DECL
38 .\" @MUFFLE_WARNINGS_EXPR
39 .\" @MUFFLE_WARNINGS_STMT
44 .B "#include <mLib/macros.h>"
46 .BI "size_t N(" array ");"
47 .BI "STR(" tokens\fR... ")"
48 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
49 .BI "STATIC_ASSERT(" cond ", " msg ");"
51 .BI "ISALNUM(int " ch ");"
52 .BI "ISALPHA(int " ch ");"
53 .BI "ISASCII(int " ch ");"
54 .BI "ISBLANK(int " ch ");"
55 .BI "ISCNTRL(int " ch ");"
56 .BI "ISDIGIT(int " ch ");"
57 .BI "ISGRAPH(int " ch ");"
58 .BI "ISLOWER(int " ch ");"
59 .BI "ISPRINT(int " ch ");"
60 .BI "ISPUNCT(int " ch ");"
61 .BI "ISSPACE(int " ch ");"
62 .BI "ISUPPER(int " ch ");"
63 .BI "ISXDIGIT(int " ch ");"
64 .BI "TOASCII(int " ch ");"
65 .BI "TOLOWER(int " ch ");"
66 .BI "TOUPPER(int " ch ");"
68 .BI "MEMCMP(const void *" x ", " op ", const void *" y ", size_t " n ");"
69 .BI "STRCMP(const char *" x ", " op ", const char *" y ");"
70 .BI "STRNCMP(const char *" x ", " op ", const char *" y ", size_t " n ");"
72 .BI "void DISCARD(" scalar ");"
73 .BI "void IGNORE(" variable ");"
75 .BI "DEPRECATED(" msg ")"
76 .BI "EXECL_LIKE(" ntrail ")"
80 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
81 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
83 .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
84 .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
85 .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
87 .BI "GCC_WARNING(" option ")"
88 .BI "CLANG_WARNING(" option ")"
94 macro returns the number of elements in the named
99 macro expands to a string literal containing the result of expanding its
105 macro expands to a single token, which is the result of gluing together
106 the tokens resulting from expanding its argument token lists. Each of
107 the argument token lists must expand to a single preprocessing token,
108 and the result of gluing these tokens together must be valid
113 causes compilation to fail if the integer constant expression
115 evaluates to zero. This macro uses the C11
117 declaration if available, and the
119 will be reported in the compiler's diagnostic messsage; otherwise, the macro
120 falls back to a somewhat ugly hack which currently ignores the
127 macros are wrappers around the corresponding standard
129 macros with the corresponding lowercase names. They take care of
130 forcing the character argument
133 .BR "unsigned char" :
134 this conversion is necessary on platforms with signed
136 to avoid passing negative values into the standard macros.
143 macros are wrappers around the standard
145 functions with the corresponding lowercase names. They take an
148 which is a equality or ordering operator (e.g.,
152 inserted between the two operands. The standard functions return a
153 false value if and only if the operands are equal, which is
154 counterintuitive and leads to mistakes; requiring an explicit relational
155 operator should reduce the number of such mistakes.
159 macro discards its argument, which must be of some scalar type. This
160 can be useful in muffling warnings about ignoring return codes in cases
161 where you really don't care.
165 macro ignores its argument, which may be an expression of any type.
166 This can be useful in muffling warnings about unused variables.
168 The following annotations can be attached to function declarations and
169 definitions, as part of the declaration specifiers. (Other positions
170 may also work, depending on your compiler, but don't bet on it.) They
171 might not have any effect, depending on your specific compiler.
172 Currently only GCC is well supported, but exactly which features are
173 available depend on the compiler version.
175 Using a function or variable marked as
177 may provoke a compiler warning; this warning may (depending on your
178 compiler version) include the given
181 A variadic function marked as
183 must be called with a null pointer (i.e., an integer constant
184 expression with value 0, cast to
186 in the variadic part of its argument list, followed by
188 further arguments. Typically,
190 is zero. Compilers may warn about misuse of such functions.
192 A function or variable marked as
194 need not be used. This may muffle warnings about leaving the marked
199 returns an important value: a warning may be issued if a caller
200 ignores the value. The return type must not be
205 must not return. It must have return type
207 This may be useful in muffling warnings about uninitialized variables,
210 A variadic function marked as
214 format argument (in position
216 counting from 1) and a variable-length list of arguments to be formatted
217 (starting from position
219 Compilers may warn about misuse of such functions.
221 A variadic function marked as
225 format argument (in position
227 counting from 1) and a variable-length list of arguments to be formatted
228 (starting from position
230 Compilers may warn about misuse of such functions.
231 .SS Muffling warnings
232 Some compilers allow you to muffle warnings in particular pieces of
233 code. These macros provide a compiler-neutral interface to such
234 facilities. Each macro takes an argument
236 which is a sequence of calls to
237 .IB compiler _WARNING
238 macros listing the warnings to be muffled. The list may contain
239 warnings for several different compilers. The other argument is a
241 consisting of declarations (in the case of
242 .BR MUFFLE_WARNINGS_DECL ),
244 .BR MUFFLE_WARNINGS_EXPR ),
246 .BR MUFFLE_WARNINGS_STMT ).
247 .SS GCC-specific features
250 macro returns a nonzero value if the compiler is at least version
252 of GCC, and zero otherwise. It's useful in preprocessor conditions.
256 macro is intended to be used in
258 lists (see above). It takes a string-literal argument
260 naming a GCC warning option, e.g.,
261 .BR """\-Wdiv-by-zero""" .
265 is similar, except that it works with the Clang compiler.
269 also defines the compiler-test macros in
270 .BR <mLib/compiler.h>;
277 Mark Wooding, <mdw@distorted.org.uk>