Commit | Line | Data |
---|---|---|
14d7100d | 1 | .\" -*-nroff-*- |
2 | .TH macros 3 "13 December 2003" "Straylight/Edgeware" "mLib utilities library" | |
3 | .SH NAME | |
4 | macros \- useful macros | |
5 | .\" @N | |
3832000d MW |
6 | .\" @STR |
7 | .\" @GLUE | |
f50c1365 | 8 | .\" @STATIC_ASSERT |
36188114 MW |
9 | .\" @ISALNUM |
10 | .\" @ISALPHA | |
11 | .\" @ISASCII | |
12 | .\" @ISBLANK | |
13 | .\" @ISCNTRL | |
14 | .\" @ISDIGIT | |
15 | .\" @ISGRAPH | |
16 | .\" @ISLOWER | |
17 | .\" @ISPRINT | |
18 | .\" @ISPUNCT | |
19 | .\" @ISSPACE | |
20 | .\" @ISUPPER | |
21 | .\" @ISXDIGIT | |
22 | .\" @TOASCII | |
23 | .\" @TOLOWER | |
24 | .\" @TOUPPER | |
25 | .\" @MEMCMP | |
26 | .\" @STRCMP | |
27 | .\" @STRNCMP | |
3832000d MW |
28 | .\" @DISCARD |
29 | .\" @IGNORE | |
30 | .\" @DEPRECATED | |
31 | .\" @EXECL_LIKE | |
32 | .\" @IGNORABLE | |
8c470f2a | 33 | .\" @MUST_CHECK |
3832000d MW |
34 | .\" @NORETURN |
35 | .\" @PRINTF_LIKE | |
36 | .\" @SCANF_LIKE | |
37 | .\" @MUFFLE_WARNINGS_DECL | |
38 | .\" @MUFFLE_WARNINGS_EXPR | |
39 | .\" @MUFFLE_WARNINGS_STMT | |
3832000d | 40 | .\" @GCC_WARNING |
2f2cb664 | 41 | .\" @CLANG_WARNING |
14d7100d | 42 | .SH SYNOPSIS |
43 | .nf | |
44 | .B "#include <mLib/macros.h>" | |
45 | ||
46 | .BI "size_t N(" array ");" | |
3832000d MW |
47 | .BI "STR(" tokens\fR... ")" |
48 | .BI "GLUE(" tokens\fR... ", " tokens\fR... ")" | |
f50c1365 | 49 | .BI "STATIC_ASSERT(" cond ", " msg ");" |
3832000d | 50 | |
36188114 MW |
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 ");" | |
67 | ||
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 ");" | |
71 | ||
3832000d MW |
72 | .BI "void DISCARD(" scalar ");" |
73 | .BI "void IGNORE(" variable ");" | |
74 | ||
75 | .BI "DEPRECATED(" msg ")" | |
76 | .BI "EXECL_LIKE(" ntrail ")" | |
77 | .BI "IGNORABLE" | |
8c470f2a | 78 | .BI "MUST_CHECK" |
3832000d MW |
79 | .BI "NORETURN" |
80 | .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")" | |
81 | .BI "SCANF_LIKE(" fmt-index ", " arg-index ")" | |
82 | ||
83 | .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")" | |
84 | .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")" | |
85 | .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")" | |
86 | ||
3832000d | 87 | .BI "GCC_WARNING(" option ")" |
c418910f | 88 | .BI "CLANG_WARNING(" option ")" |
14d7100d | 89 | .fi |
90 | .SH DESCRIPTION | |
3832000d | 91 | .SS Utilities |
14d7100d | 92 | The |
93 | .B N | |
94 | macro returns the number of elements in the named | |
95 | .IR array . | |
3832000d MW |
96 | .PP |
97 | The | |
98 | .B STR | |
99 | macro expands to a string literal containing the result of expanding its | |
100 | argument | |
101 | .IR tokens . | |
102 | .PP | |
103 | The | |
104 | .B GLUE | |
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 | |
109 | preprocessing token. | |
110 | .PP | |
111 | The | |
f50c1365 MW |
112 | .B STATIC_ASSERT |
113 | causes compilation to fail if the integer constant expression | |
114 | .I cond | |
115 | evaluates to zero. This macro uses the C11 | |
116 | .B static_assert | |
117 | declaration if available, and the | |
118 | .I msg | |
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 | |
121 | .IR msg . | |
122 | .PP | |
123 | The | |
36188114 MW |
124 | .BR IS ...\& |
125 | and | |
126 | .BR TO ...\& | |
127 | macros are wrappers around the corresponding standard | |
128 | .B <ctype.h> | |
129 | macros with the corresponding lowercase names. They take care of | |
130 | forcing the character argument | |
131 | .I ch | |
132 | to | |
133 | .BR "unsigned char" : | |
134 | this conversion is necessary on platforms with signed | |
135 | .B char | |
136 | to avoid passing negative values into the standard macros. | |
137 | .PP | |
138 | The | |
139 | .BR MEMCMP , | |
140 | .BR STRCMP , | |
141 | and | |
142 | .B STRNCMP | |
143 | macros are wrappers around the standard | |
144 | .B <string.h> | |
145 | functions with the corresponding lowercase names. They take an | |
146 | additional argument | |
147 | .I op | |
148 | which is a equality or ordering operator (e.g., | |
149 | .B == | |
150 | or | |
151 | .BR > ) | |
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. | |
156 | .PP | |
157 | The | |
3832000d MW |
158 | .B DISCARD |
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. | |
162 | .PP | |
163 | The | |
164 | .B IGNORE | |
165 | macro ignores its argument, which may be an expression of any type. | |
166 | This can be useful in muffling warnings about unused variables. | |
167 | .SS Annotations | |
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. | |
174 | .PP | |
175 | Using a function or variable marked as | |
176 | .B DEPRECATED | |
177 | may provoke a compiler warning; this warning may (depending on your | |
178 | compiler version) include the given | |
179 | .IR msg . | |
180 | .PP | |
181 | A variadic function marked as | |
182 | .B EXECL_LIKE | |
183 | must be called with a null pointer (i.e., an integer constant | |
184 | expression with value 0, cast to | |
185 | .BR "void *") | |
186 | in the variadic part of its argument list, followed by | |
187 | .I ntrail | |
188 | further arguments. Typically, | |
189 | .I ntrail | |
190 | is zero. Compilers may warn about misuse of such functions. | |
191 | .PP | |
192 | A function or variable marked as | |
193 | .B IGNORABLE | |
194 | need not be used. This may muffle warnings about leaving the marked | |
195 | definition unused. | |
196 | .PP | |
197 | A function marked as | |
8c470f2a MW |
198 | .B MUST_CHECK |
199 | returns an important value: a warning may be issued if a caller | |
200 | ignores the value. The return type must not be | |
201 | .BR void . | |
202 | .PP | |
203 | A function marked as | |
3832000d MW |
204 | .B NORETURN |
205 | must not return. It must have return type | |
206 | .BR void . | |
207 | This may be useful in muffling warnings about uninitialized variables, | |
208 | for example. | |
209 | .PP | |
210 | A variadic function marked as | |
211 | .B PRINTF_LIKE | |
212 | takes a | |
213 | .BR printf (3)-style | |
214 | format argument (in position | |
215 | .IR fmt-index , | |
216 | counting from 1) and a variable-length list of arguments to be formatted | |
217 | (starting from position | |
218 | .IR arg-index ). | |
219 | Compilers may warn about misuse of such functions. | |
220 | .PP | |
221 | A variadic function marked as | |
222 | .B SCANF_LIKE | |
223 | takes a | |
224 | .BR scanf (3)-style | |
225 | format argument (in position | |
226 | .IR fmt-index , | |
227 | counting from 1) and a variable-length list of arguments to be formatted | |
228 | (starting from position | |
229 | .IR arg-index ). | |
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 | |
235 | .IR warns , | |
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 | |
240 | .I body | |
241 | consisting of declarations (in the case of | |
242 | .BR MUFFLE_WARNINGS_DECL ), | |
243 | an expression (for | |
244 | .BR MUFFLE_WARNINGS_EXPR ), | |
245 | or a statement (for | |
246 | .BR MUFFLE_WARNINGS_STMT ). | |
247 | .SS GCC-specific features | |
248 | The | |
249 | .B GCC_VERSION_P | |
250 | macro returns a nonzero value if the compiler is at least version | |
251 | .IB maj . min | |
252 | of GCC, and zero otherwise. It's useful in preprocessor conditions. | |
253 | .PP | |
254 | The | |
255 | .B GCC_WARNING | |
256 | macro is intended to be used in | |
257 | .I warns | |
258 | lists (see above). It takes a string-literal argument | |
259 | .I option | |
260 | naming a GCC warning option, e.g., | |
261 | .BR """\-Wdiv-by-zero""" . | |
c418910f MW |
262 | .PP |
263 | The | |
264 | .B CLANG_WARNING | |
265 | is similar, except that it works with the Clang compiler. | |
33e3ac90 MW |
266 | .PP |
267 | Note that including | |
268 | .B <mLib/macros.h> | |
269 | also defines the compiler-test macros in | |
270 | .BR <mLib/compiler.h>; | |
271 | see | |
272 | .BR compiler (3). | |
14d7100d | 273 | .SH "SEE ALSO" |
33e3ac90 MW |
274 | .BR mLib (3), |
275 | .BR compiler (3). | |
14d7100d | 276 | .SH "AUTHOR" |
9b5ac6ff | 277 | Mark Wooding, <mdw@distorted.org.uk> |