utils/macros.h: Add `MUST_CHECK', so return codes aren't ignored.

[mLib] / utils / macros.3

.\" -*-nroff-*-
.TH macros 3 "13 December 2003" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
macros \- useful macros
.\" @N
.\" @STR
.\" @GLUE
.\" @STATIC_ASSERT
.\" @ISALNUM
.\" @ISALPHA
.\" @ISASCII
.\" @ISBLANK
.\" @ISCNTRL
.\" @ISDIGIT
.\" @ISGRAPH
.\" @ISLOWER
.\" @ISPRINT
.\" @ISPUNCT
.\" @ISSPACE
.\" @ISUPPER
.\" @ISXDIGIT
.\" @TOASCII
.\" @TOLOWER
.\" @TOUPPER
.\" @MEMCMP
.\" @STRCMP
.\" @STRNCMP
.\" @DISCARD
.\" @IGNORE
.\" @DEPRECATED
.\" @EXECL_LIKE
.\" @IGNORABLE
.\" @MUST_CHECK
.\" @NORETURN
.\" @PRINTF_LIKE
.\" @SCANF_LIKE
.\" @MUFFLE_WARNINGS_DECL
.\" @MUFFLE_WARNINGS_EXPR
.\" @MUFFLE_WARNINGS_STMT
.\" @GCC_WARNING
.\" @CLANG_WARNING
.SH SYNOPSIS
.nf
.B "#include <mLib/macros.h>"

.BI "size_t N(" array ");"
.BI "STR(" tokens\fR... ")"
.BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
.BI "STATIC_ASSERT(" cond ", " msg ");"

.BI "ISALNUM(int " ch ");"
.BI "ISALPHA(int " ch ");"
.BI "ISASCII(int " ch ");"
.BI "ISBLANK(int " ch ");"
.BI "ISCNTRL(int " ch ");"
.BI "ISDIGIT(int " ch ");"
.BI "ISGRAPH(int " ch ");"
.BI "ISLOWER(int " ch ");"
.BI "ISPRINT(int " ch ");"
.BI "ISPUNCT(int " ch ");"
.BI "ISSPACE(int " ch ");"
.BI "ISUPPER(int " ch ");"
.BI "ISXDIGIT(int " ch ");"
.BI "TOASCII(int " ch ");"
.BI "TOLOWER(int " ch ");"
.BI "TOUPPER(int " ch ");"

.BI "MEMCMP(const void *" x ", " op ", const void *" y ", size_t " n ");"
.BI "STRCMP(const char *" x ", " op ", const char *" y ");"
.BI "STRNCMP(const char *" x ", " op ", const char *" y ", size_t " n ");"

.BI "void DISCARD(" scalar ");"
.BI "void IGNORE(" variable ");"

.BI "DEPRECATED(" msg ")"
.BI "EXECL_LIKE(" ntrail ")"
.BI "IGNORABLE"
.BI "MUST_CHECK"
.BI "NORETURN"
.BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
.BI "SCANF_LIKE(" fmt-index ", " arg-index ")"

.BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
.BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
.BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"

.BI "GCC_WARNING(" option ")"
.BI "CLANG_WARNING(" option ")"
.fi
.SH DESCRIPTION
.SS Utilities
The
.B N
macro returns the number of elements in the named
.IR array .
.PP
The
.B STR
macro expands to a string literal containing the result of expanding its
argument
.IR tokens .
.PP
The
.B GLUE
macro expands to a single token, which is the result of gluing together
the tokens resulting from expanding its argument token lists.  Each of
the argument token lists must expand to a single preprocessing token,
and the result of gluing these tokens together must be valid
preprocessing token.
.PP
The
.B STATIC_ASSERT
causes compilation to fail if the integer constant expression
.I cond
evaluates to zero.  This macro uses the C11
.B static_assert
declaration if available, and the
.I msg
will be reported in the compiler's diagnostic messsage; otherwise, the macro
falls back to a somewhat ugly hack which currently ignores the
.IR msg .
.PP
The
.BR IS ...\&
and
.BR TO ...\&
macros are wrappers around the corresponding standard
.B <ctype.h>
macros with the corresponding lowercase names.  They take care of
forcing the character argument
.I ch
to
.BR "unsigned char" :
this conversion is necessary on platforms with signed
.B char
to avoid passing negative values into the standard macros.
.PP
The
.BR MEMCMP ,
.BR STRCMP ,
and
.B STRNCMP
macros are wrappers around the standard
.B <string.h>
functions with the corresponding lowercase names.  They take an
additional argument
.I op
which is a equality or ordering operator (e.g.,
.B ==
or
.BR > )
inserted between the two operands.  The standard functions return a
false value if and only if the operands are equal, which is
counterintuitive and leads to mistakes; requiring an explicit relational
operator should reduce the number of such mistakes.
.PP
The
.B DISCARD
macro discards its argument, which must be of some scalar type.  This
can be useful in muffling warnings about ignoring return codes in cases
where you really don't care.
.PP
The
.B IGNORE
macro ignores its argument, which may be an expression of any type.
This can be useful in muffling warnings about unused variables.
.SS Annotations
The following annotations can be attached to function declarations and
definitions, as part of the declaration specifiers.  (Other positions
may also work, depending on your compiler, but don't bet on it.)  They
might not have any effect, depending on your specific compiler.
Currently only GCC is well supported, but exactly which features are
available depend on the compiler version.
.PP
Using a function or variable marked as
.B DEPRECATED
may provoke a compiler warning; this warning may (depending on your
compiler version) include the given
.IR msg .
.PP
A variadic function marked as
.B EXECL_LIKE
must be called with a null pointer (i.e., an integer constant
expression with value 0, cast to
.BR "void *")
in the variadic part of its argument list, followed by
.I ntrail
further arguments.  Typically,
.I ntrail
is zero.  Compilers may warn about misuse of such functions.
.PP
A function or variable marked as
.B IGNORABLE
need not be used.  This may muffle warnings about leaving the marked
definition unused.
.PP
A function marked as
.B MUST_CHECK
returns an important value: a warning may be issued if a caller
ignores the value.  The return type must not be
.BR void .
.PP
A function marked as
.B NORETURN
must not return.  It must have return type
.BR void .
This may be useful in muffling warnings about uninitialized variables,
for example.
.PP
A variadic function marked as
.B PRINTF_LIKE
takes a
.BR printf (3)-style
format argument (in position
.IR fmt-index ,
counting from 1) and a variable-length list of arguments to be formatted
(starting from position
.IR arg-index ).
Compilers may warn about misuse of such functions.
.PP
A variadic function marked as
.B SCANF_LIKE
takes a
.BR scanf (3)-style
format argument (in position
.IR fmt-index ,
counting from 1) and a variable-length list of arguments to be formatted
(starting from position
.IR arg-index ).
Compilers may warn about misuse of such functions.
.SS Muffling warnings
Some compilers allow you to muffle warnings in particular pieces of
code.  These macros provide a compiler-neutral interface to such
facilities.  Each macro takes an argument
.IR warns ,
which is a sequence of calls to
.IB compiler _WARNING
macros listing the warnings to be muffled.  The list may contain
warnings for several different compilers.  The other argument is a
.I body
consisting of declarations (in the case of
.BR MUFFLE_WARNINGS_DECL ),
an expression (for
.BR MUFFLE_WARNINGS_EXPR ),
or a statement (for
.BR MUFFLE_WARNINGS_STMT ).
.SS GCC-specific features
The
.B GCC_VERSION_P
macro returns a nonzero value if the compiler is at least version
.IB maj . min
of GCC, and zero otherwise.  It's useful in preprocessor conditions.
.PP
The
.B GCC_WARNING
macro is intended to be used in
.I warns
lists (see above).  It takes a string-literal argument
.I option
naming a GCC warning option, e.g.,
.BR """\-Wdiv-by-zero""" .
.PP
The
.B CLANG_WARNING
is similar, except that it works with the Clang compiler.
.PP
Note that including
.B <mLib/macros.h>
also defines the compiler-test macros in
.BR <mLib/compiler.h>;
see
.BR compiler (3).
.SH "SEE ALSO"
.BR mLib (3),
.BR compiler (3).
.SH "AUTHOR"
Mark Wooding, <mdw@distorted.org.uk>