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 | |
8 | .\" @DISCARD | |
9 | .\" @IGNORE | |
10 | .\" @DEPRECATED | |
11 | .\" @EXECL_LIKE | |
12 | .\" @IGNORABLE | |
13 | .\" @NORETURN | |
14 | .\" @PRINTF_LIKE | |
15 | .\" @SCANF_LIKE | |
16 | .\" @MUFFLE_WARNINGS_DECL | |
17 | .\" @MUFFLE_WARNINGS_EXPR | |
18 | .\" @MUFFLE_WARNINGS_STMT | |
19 | .\" @GCC_VERSION_P | |
20 | .\" @GCC_WARNING | |
14d7100d | 21 | .SH SYNOPSIS |
22 | .nf | |
23 | .B "#include <mLib/macros.h>" | |
24 | ||
25 | .BI "size_t N(" array ");" | |
3832000d MW |
26 | .BI "STR(" tokens\fR... ")" |
27 | .BI "GLUE(" tokens\fR... ", " tokens\fR... ")" | |
28 | ||
29 | .BI "void DISCARD(" scalar ");" | |
30 | .BI "void IGNORE(" variable ");" | |
31 | ||
32 | .BI "DEPRECATED(" msg ")" | |
33 | .BI "EXECL_LIKE(" ntrail ")" | |
34 | .BI "IGNORABLE" | |
35 | .BI "NORETURN" | |
36 | .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")" | |
37 | .BI "SCANF_LIKE(" fmt-index ", " arg-index ")" | |
38 | ||
39 | .BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")" | |
40 | .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")" | |
41 | .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")" | |
42 | ||
43 | .BI "int GCC_VERSION_P(" maj ", " min ");" | |
44 | .BI "GCC_WARNING(" option ")" | |
14d7100d | 45 | .fi |
46 | .SH DESCRIPTION | |
3832000d | 47 | .SS Utilities |
14d7100d | 48 | The |
49 | .B N | |
50 | macro returns the number of elements in the named | |
51 | .IR array . | |
3832000d MW |
52 | .PP |
53 | The | |
54 | .B STR | |
55 | macro expands to a string literal containing the result of expanding its | |
56 | argument | |
57 | .IR tokens . | |
58 | .PP | |
59 | The | |
60 | .B GLUE | |
61 | macro expands to a single token, which is the result of gluing together | |
62 | the tokens resulting from expanding its argument token lists. Each of | |
63 | the argument token lists must expand to a single preprocessing token, | |
64 | and the result of gluing these tokens together must be valid | |
65 | preprocessing token. | |
66 | .PP | |
67 | The | |
68 | .B DISCARD | |
69 | macro discards its argument, which must be of some scalar type. This | |
70 | can be useful in muffling warnings about ignoring return codes in cases | |
71 | where you really don't care. | |
72 | .PP | |
73 | The | |
74 | .B IGNORE | |
75 | macro ignores its argument, which may be an expression of any type. | |
76 | This can be useful in muffling warnings about unused variables. | |
77 | .SS Annotations | |
78 | The following annotations can be attached to function declarations and | |
79 | definitions, as part of the declaration specifiers. (Other positions | |
80 | may also work, depending on your compiler, but don't bet on it.) They | |
81 | might not have any effect, depending on your specific compiler. | |
82 | Currently only GCC is well supported, but exactly which features are | |
83 | available depend on the compiler version. | |
84 | .PP | |
85 | Using a function or variable marked as | |
86 | .B DEPRECATED | |
87 | may provoke a compiler warning; this warning may (depending on your | |
88 | compiler version) include the given | |
89 | .IR msg . | |
90 | .PP | |
91 | A variadic function marked as | |
92 | .B EXECL_LIKE | |
93 | must be called with a null pointer (i.e., an integer constant | |
94 | expression with value 0, cast to | |
95 | .BR "void *") | |
96 | in the variadic part of its argument list, followed by | |
97 | .I ntrail | |
98 | further arguments. Typically, | |
99 | .I ntrail | |
100 | is zero. Compilers may warn about misuse of such functions. | |
101 | .PP | |
102 | A function or variable marked as | |
103 | .B IGNORABLE | |
104 | need not be used. This may muffle warnings about leaving the marked | |
105 | definition unused. | |
106 | .PP | |
107 | A function marked as | |
108 | .B NORETURN | |
109 | must not return. It must have return type | |
110 | .BR void . | |
111 | This may be useful in muffling warnings about uninitialized variables, | |
112 | for example. | |
113 | .PP | |
114 | A variadic function marked as | |
115 | .B PRINTF_LIKE | |
116 | takes a | |
117 | .BR printf (3)-style | |
118 | format argument (in position | |
119 | .IR fmt-index , | |
120 | counting from 1) and a variable-length list of arguments to be formatted | |
121 | (starting from position | |
122 | .IR arg-index ). | |
123 | Compilers may warn about misuse of such functions. | |
124 | .PP | |
125 | A variadic function marked as | |
126 | .B SCANF_LIKE | |
127 | takes a | |
128 | .BR scanf (3)-style | |
129 | format argument (in position | |
130 | .IR fmt-index , | |
131 | counting from 1) and a variable-length list of arguments to be formatted | |
132 | (starting from position | |
133 | .IR arg-index ). | |
134 | Compilers may warn about misuse of such functions. | |
135 | .SS Muffling warnings | |
136 | Some compilers allow you to muffle warnings in particular pieces of | |
137 | code. These macros provide a compiler-neutral interface to such | |
138 | facilities. Each macro takes an argument | |
139 | .IR warns , | |
140 | which is a sequence of calls to | |
141 | .IB compiler _WARNING | |
142 | macros listing the warnings to be muffled. The list may contain | |
143 | warnings for several different compilers. The other argument is a | |
144 | .I body | |
145 | consisting of declarations (in the case of | |
146 | .BR MUFFLE_WARNINGS_DECL ), | |
147 | an expression (for | |
148 | .BR MUFFLE_WARNINGS_EXPR ), | |
149 | or a statement (for | |
150 | .BR MUFFLE_WARNINGS_STMT ). | |
151 | .SS GCC-specific features | |
152 | The | |
153 | .B GCC_VERSION_P | |
154 | macro returns a nonzero value if the compiler is at least version | |
155 | .IB maj . min | |
156 | of GCC, and zero otherwise. It's useful in preprocessor conditions. | |
157 | .PP | |
158 | The | |
159 | .B GCC_WARNING | |
160 | macro is intended to be used in | |
161 | .I warns | |
162 | lists (see above). It takes a string-literal argument | |
163 | .I option | |
164 | naming a GCC warning option, e.g., | |
165 | .BR """\-Wdiv-by-zero""" . | |
14d7100d | 166 | .SH "SEE ALSO" |
167 | .BR mLib (3). | |
168 | .SH "AUTHOR" | |
9b5ac6ff | 169 | Mark Wooding, <mdw@distorted.org.uk> |