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
42 .B "#include <mLib/macros.h>"
44 .BI "size_t N(" array ");"
45 .BI "STR(" tokens\fR... ")"
46 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
47 .BI "STATIC_ASSERT(" cond ", " msg ");"
49 .BI "ISALNUM(int " ch ");"
50 .BI "ISALPHA(int " ch ");"
51 .BI "ISASCII(int " ch ");"
52 .BI "ISBLANK(int " ch ");"
53 .BI "ISCNTRL(int " ch ");"
54 .BI "ISDIGIT(int " ch ");"
55 .BI "ISGRAPH(int " ch ");"
56 .BI "ISLOWER(int " ch ");"
57 .BI "ISPRINT(int " ch ");"
58 .BI "ISPUNCT(int " ch ");"
59 .BI "ISSPACE(int " ch ");"
60 .BI "ISUPPER(int " ch ");"
61 .BI "ISXDIGIT(int " ch ");"
62 .BI "TOASCII(int " ch ");"
63 .BI "TOLOWER(int " ch ");"
64 .BI "TOUPPER(int " ch ");"
66 .BI "MEMCMP(const void *" x ", " op ", const void *" y ", size_t " n ");"
67 .BI "STRCMP(const char *" x ", " op ", const char *" y ");"
68 .BI "STRNCMP(const char *" x ", " op ", const char *" y ", size_t " n ");"
70 .BI "void DISCARD(" scalar ");"
71 .BI "void IGNORE(" variable ");"
73 .BI "DEPRECATED(" msg ")"
74 .BI "EXECL_LIKE(" ntrail ")"
77 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
78 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
80 .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
81 .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
82 .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
84 .BI "GCC_WARNING(" option ")"
85 .BI "CLANG_WARNING(" option ")"
91 macro returns the number of elements in the named
96 macro expands to a string literal containing the result of expanding its
102 macro expands to a single token, which is the result of gluing together
103 the tokens resulting from expanding its argument token lists. Each of
104 the argument token lists must expand to a single preprocessing token,
105 and the result of gluing these tokens together must be valid
110 causes compilation to fail if the integer constant expression
112 evaluates to zero. This macro uses the C11
114 declaration if available, and the
116 will be reported in the compiler's diagnostic messsage; otherwise, the macro
117 falls back to a somewhat ugly hack which currently ignores the
124 macros are wrappers around the corresponding standard
126 macros with the corresponding lowercase names. They take care of
127 forcing the character argument
130 .BR "unsigned char" :
131 this conversion is necessary on platforms with signed
133 to avoid passing negative values into the standard macros.
140 macros are wrappers around the standard
142 functions with the corresponding lowercase names. They take an
145 which is a equality or ordering operator (e.g.,
149 inserted between the two operands. The standard functions return a
150 false value if and only if the operands are equal, which is
151 counterintuitive and leads to mistakes; requiring an explicit relational
152 operator should reduce the number of such mistakes.
156 macro discards its argument, which must be of some scalar type. This
157 can be useful in muffling warnings about ignoring return codes in cases
158 where you really don't care.
162 macro ignores its argument, which may be an expression of any type.
163 This can be useful in muffling warnings about unused variables.
165 The following annotations can be attached to function declarations and
166 definitions, as part of the declaration specifiers. (Other positions
167 may also work, depending on your compiler, but don't bet on it.) They
168 might not have any effect, depending on your specific compiler.
169 Currently only GCC is well supported, but exactly which features are
170 available depend on the compiler version.
172 Using a function or variable marked as
174 may provoke a compiler warning; this warning may (depending on your
175 compiler version) include the given
178 A variadic function marked as
180 must be called with a null pointer (i.e., an integer constant
181 expression with value 0, cast to
183 in the variadic part of its argument list, followed by
185 further arguments. Typically,
187 is zero. Compilers may warn about misuse of such functions.
189 A function or variable marked as
191 need not be used. This may muffle warnings about leaving the marked
196 must not return. It must have return type
198 This may be useful in muffling warnings about uninitialized variables,
201 A variadic function marked as
205 format argument (in position
207 counting from 1) and a variable-length list of arguments to be formatted
208 (starting from position
210 Compilers may warn about misuse of such functions.
212 A variadic function marked as
216 format argument (in position
218 counting from 1) and a variable-length list of arguments to be formatted
219 (starting from position
221 Compilers may warn about misuse of such functions.
222 .SS Muffling warnings
223 Some compilers allow you to muffle warnings in particular pieces of
224 code. These macros provide a compiler-neutral interface to such
225 facilities. Each macro takes an argument
227 which is a sequence of calls to
228 .IB compiler _WARNING
229 macros listing the warnings to be muffled. The list may contain
230 warnings for several different compilers. The other argument is a
232 consisting of declarations (in the case of
233 .BR MUFFLE_WARNINGS_DECL ),
235 .BR MUFFLE_WARNINGS_EXPR ),
237 .BR MUFFLE_WARNINGS_STMT ).
238 .SS GCC-specific features
241 macro returns a nonzero value if the compiler is at least version
243 of GCC, and zero otherwise. It's useful in preprocessor conditions.
247 macro is intended to be used in
249 lists (see above). It takes a string-literal argument
251 naming a GCC warning option, e.g.,
252 .BR """\-Wdiv-by-zero""" .
256 is similar, except that it works with the Clang compiler.
260 also defines the compiler-test macros in
261 .BR <mLib/compiler.h>;
268 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob