| 1 | .\" -*-nroff-*- |
| 2 | .TH macros 3 "13 December 2003" "Straylight/Edgeware" "mLib utilities library" |
| 3 | .SH NAME |
| 4 | macros \- useful macros |
| 5 | .\" @N |
| 6 | .\" @STR |
| 7 | .\" @GLUE |
| 8 | .\" @STATIC_ASSERT |
| 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 |
| 28 | .\" @DISCARD |
| 29 | .\" @IGNORE |
| 30 | .\" @DEPRECATED |
| 31 | .\" @EXECL_LIKE |
| 32 | .\" @IGNORABLE |
| 33 | .\" @MUST_CHECK |
| 34 | .\" @NORETURN |
| 35 | .\" @PRINTF_LIKE |
| 36 | .\" @SCANF_LIKE |
| 37 | .\" @MUFFLE_WARNINGS_DECL |
| 38 | .\" @MUFFLE_WARNINGS_EXPR |
| 39 | .\" @MUFFLE_WARNINGS_STMT |
| 40 | .\" @GCC_WARNING |
| 41 | .\" @CLANG_WARNING |
| 42 | .SH SYNOPSIS |
| 43 | .nf |
| 44 | .B "#include <mLib/macros.h>" |
| 45 | |
| 46 | .BI "size_t N(" array ");" |
| 47 | .BI "STR(" tokens\fR... ")" |
| 48 | .BI "GLUE(" tokens\fR... ", " tokens\fR... ")" |
| 49 | .BI "STATIC_ASSERT(" cond ", " msg ");" |
| 50 | |
| 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 | |
| 72 | .BI "void DISCARD(" scalar ");" |
| 73 | .BI "void IGNORE(" variable ");" |
| 74 | |
| 75 | .BI "DEPRECATED(" msg ")" |
| 76 | .BI "EXECL_LIKE(" ntrail ")" |
| 77 | .BI "IGNORABLE" |
| 78 | .BI "MUST_CHECK" |
| 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 | |
| 87 | .BI "GCC_WARNING(" option ")" |
| 88 | .BI "CLANG_WARNING(" option ")" |
| 89 | .fi |
| 90 | .SH DESCRIPTION |
| 91 | .SS Utilities |
| 92 | The |
| 93 | .B N |
| 94 | macro returns the number of elements in the named |
| 95 | .IR array . |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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""" . |
| 262 | .PP |
| 263 | The |
| 264 | .B CLANG_WARNING |
| 265 | is similar, except that it works with the Clang compiler. |
| 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). |
| 273 | .SH "SEE ALSO" |
| 274 | .BR mLib (3), |
| 275 | .BR compiler (3). |
| 276 | .SH "AUTHOR" |
| 277 | Mark Wooding, <mdw@distorted.org.uk> |