3 .\" Manual for miscellaneous macros
5 .\" (c) 2003, 2005, 2009, 2013, 2018, 2019, 2022, 2024 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of the mLib utilities library.
12 .\" mLib is free software: you can redistribute it and/or modify it under
13 .\" the terms of the GNU Library General Public License as published by
14 .\" the Free Software Foundation; either version 2 of the License, or (at
15 .\" your option) any later version.
17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
20 .\" License for more details.
22 .\" You should have received a copy of the GNU Library General Public
23 .\" License along with mLib. If not, write to the Free Software
24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
27 .\"--------------------------------------------------------------------------
28 .so ../defs.man \" @@@PRE@@@
30 .\"--------------------------------------------------------------------------
31 .TH macros 3mLib "13 December 2003" "Straylight/Edgeware" "mLib utilities library"
72 .\" @MUFFLE_WARNINGS_DECL
73 .\" @MUFFLE_WARNINGS_EXPR
74 .\" @MUFFLE_WARNINGS_STMT
78 .\"--------------------------------------------------------------------------
80 macros \- useful macros
82 .\"--------------------------------------------------------------------------
86 .B "#include <mLib/macros.h>"
88 .BI "size_t N(" array ");"
89 .BI "STR(" tokens\fR... ")"
90 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
91 .BI "STATIC_ASSERT(" cond ", " msg ");"
93 .BI "ISALNUM(int " ch ");"
94 .BI "ISALPHA(int " ch ");"
95 .BI "ISASCII(int " ch ");"
96 .BI "ISBLANK(int " ch ");"
97 .BI "ISCNTRL(int " ch ");"
98 .BI "ISDIGIT(int " ch ");"
99 .BI "ISGRAPH(int " ch ");"
100 .BI "ISLOWER(int " ch ");"
101 .BI "ISPRINT(int " ch ");"
102 .BI "ISPUNCT(int " ch ");"
103 .BI "ISSPACE(int " ch ");"
104 .BI "ISUPPER(int " ch ");"
105 .BI "ISXDIGIT(int " ch ");"
106 .BI "TOASCII(int " ch ");"
107 .BI "TOLOWER(int " ch ");"
108 .BI "TOUPPER(int " ch ");"
110 .BI "MEMCMP(const void *" x ", " op ", const void *" y ", size_t " n ");"
111 .BI "STRCMP(const char *" x ", " op ", const char *" y ");"
112 .BI "STRNCMP(const char *" x ", " op ", const char *" y ", size_t " n ");"
114 .BI "void DISCARD(" scalar ");"
115 .BI "void IGNORE(" variable ");"
117 .BI "DEPRECATED(" msg ")"
118 .BI "EXECL_LIKE(" ntrail ")"
122 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
123 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
125 .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
126 .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
127 .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
129 .BI "GCC_WARNING(" option ")"
130 .BI "CLANG_WARNING(" option ")"
133 .\"--------------------------------------------------------------------------
139 macro returns the number of elements in the named
144 macro expands to a string literal containing the result of expanding its
150 macro expands to a single token, which is the result of gluing together
151 the tokens resulting from expanding its argument token lists. Each of
152 the argument token lists must expand to a single preprocessing token,
153 and the result of gluing these tokens together must be valid
158 macro causes compilation to fail if the integer constant expression
160 evaluates to zero. This macro uses the C11
162 declaration if available, and the
164 will be reported in the compiler's diagnostic messsage; otherwise, the macro
165 falls back to a somewhat ugly hack which currently ignores the
170 macro expands to a comma
172 which is useful for smuggling commas into macro arguments
173 if they can't be protected by parentheses.
179 macros are wrappers around the corresponding standard
181 macros with the corresponding lowercase names. They take care of
182 forcing the character argument
185 .BR "unsigned char" :
186 this conversion is necessary on platforms with signed
188 to avoid passing negative values into the standard macros.
195 macros are wrappers around the standard
197 functions with the corresponding lowercase names. They take an
200 which is a equality or ordering operator (e.g.,
204 inserted between the two operands. The standard functions return a
205 false value if and only if the operands are equal, which is
206 counterintuitive and leads to mistakes; requiring an explicit relational
207 operator should reduce the number of such mistakes.
211 macro discards its argument, which must be of some scalar type. This
212 can be useful in muffling warnings about ignoring return codes in cases
213 where you really don't care.
217 macro ignores its argument, which may be an expression of any type.
218 This can be useful in muffling warnings about unused variables.
222 macro tries to confuse a compiler so that it `forgets' what it knows
223 about a particular value. This is most useful in benchmarking or
224 similar applications.
228 macro tries do nothing, but in a way that a compiler won't optimize
232 The following annotations can be attached to function declarations and
233 definitions, as part of the declaration specifiers. (Other positions
234 may also work, depending on your compiler, but don't bet on it.) They
235 might not have any effect, depending on your specific compiler.
236 Currently only GCC is well supported, but exactly which features are
237 available depend on the compiler version.
239 Using a function or variable marked as
241 may provoke a compiler warning; this warning may (depending on your
242 compiler version) include the given
245 A variadic function marked as
247 must be called with a null pointer (i.e., an integer constant
248 expression with value 0, cast to
250 in the variadic part of its argument list, followed by
252 further arguments. Typically,
254 is zero. Compilers may warn about misuse of such functions.
256 A function or variable marked as
258 need not be used. This may muffle warnings about leaving the marked
263 returns an important value: a warning may be issued if a caller
264 ignores the value. The return type must not be
269 must not return. It must have return type
271 This may be useful in muffling warnings about uninitialized variables,
274 A variadic function marked as
278 format argument (in position
280 counting from 1) and a variable-length list of arguments to be formatted
281 (starting from position
283 Compilers may warn about misuse of such functions.
285 A variadic function marked as
289 format argument (in position
291 counting from 1) and a variable-length list of arguments to be formatted
292 (starting from position
294 Compilers may warn about misuse of such functions.
296 .SS Muffling warnings
297 Some compilers allow you to muffle warnings in particular pieces of
298 code. These macros provide a compiler-neutral interface to such
299 facilities. Each macro takes an argument
301 which is a sequence of calls to
302 .IB compiler _WARNING
303 macros listing the warnings to be muffled. The list may contain
304 warnings for several different compilers. The other argument is a
306 consisting of declarations (in the case of
307 .BR MUFFLE_WARNINGS_DECL ),
309 .BR MUFFLE_WARNINGS_EXPR ),
311 .BR MUFFLE_WARNINGS_STMT ).
313 .SS GCC-specific features
316 macro is intended to be used in
318 lists (see above). It takes a string-literal argument
320 naming a GCC warning option, e.g.,
321 .BR """\-Wdiv-by-zero""" .
325 is similar, except that it works with the Clang compiler.
329 also defines the compiler-test macros in
330 .BR <mLib/compiler.h>;
334 .\"--------------------------------------------------------------------------
340 .\"--------------------------------------------------------------------------
343 Mark Wooding, <mdw@distorted.org.uk>
345 .\"----- That's all, folks --------------------------------------------------