@@@ fltfmt mess

[mLib] / utils / macros.3.in

.\" -*-nroff-*-
.\"
.\" Manual for miscellaneous macros
.\"
.\" (c) 2003, 2005, 2009, 2013, 2018, 2019, 2022, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH macros 3mLib "13 December 2003" "Straylight/Edgeware" "mLib utilities library"
.\" @N
.\" @STR
.\" @GLUE
.\" @STATIC_ASSERT
.\" @CHECK_TYPE
.\" @CONVERT_CAREFULLY
.\" @UNCONST
.\" @UNVOLATILE
.\" @UNQUALIFY
.\" @COMMA
.
.\" @ISALNUM
.\" @ISALPHA
.\" @ISASCII
.\" @ISBLANK
.\" @ISCNTRL
.\" @ISDIGIT
.\" @ISGRAPH
.\" @ISLOWER
.\" @ISPRINT
.\" @ISPUNCT
.\" @ISSPACE
.\" @ISUPPER
.\" @ISXDIGIT
.\" @TOASCII
.\" @TOLOWER
.\" @TOUPPER
.
.\" @MEMCMP
.\" @STRCMP
.\" @STRNCMP
.
.\" @DISCARD
.\" @IGNORE
.\" @LAUNDER
.\" @RELAX
.
.\" @DEPRECATED
.\" @IGNORABLE
.\" @MUST_CHECK
.\" @NORETURN
.\" @PRINTF_LIKE
.\" @SCANF_LIKE
.\" @EXECL_LIKE
.
.\" @MUFFLE_WARNINGS_DECL
.\" @MUFFLE_WARNINGS_EXPR
.\" @MUFFLE_WARNINGS_STMT
.\" @GCC_WARNING
.\" @CLANG_WARNING
.
.\"--------------------------------------------------------------------------
.SH NAME
macros \- useful macros
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/macros.h>"
.PP
.BI "size_t N(" type " " array "[]);"
.BI "STR(" tokens\fR... ")"
.BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
.BI "STATIC_ASSERT(" cond ", " msg ");"
.BI "int CHECK_TYPE(" expty ", " expty " " x );
.IB newty " CONVERT_CAREFULLY(" newty ", " expty ", " expty " " x );
.IB type " *UNCONST(" type ", const " type " *" p );
.IB type " *UNVOLATILE(" type ", volatile " type " *" p );
.IB type " *UNQUALIFY(" type ", const volatile " type " *" p );
.B "#define COMMA ,"
.PP
.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 ");"
.PP
.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 ");"
.PP
.BI "void DISCARD(" scalar ");"
.BI "void IGNORE(" variable ");"
.PP
.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 ")"
.PP
.BI "MUFFLE_WARNINGS_DECL(" warns ", " decls ")"
.BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
.BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
.PP
.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
macro 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
.B CHECK_TYPE
macro checks at compile-time that
.I x
has (or, at least, is assignment-compatible with) type
.IR expty .
If so, the result is the integer zero.
The
.B CONVERT_CAREFULLY
macro similarly checks at compile-time that
.I x
has type
.IR expty ,
and if so, the result is
.I x
converted to type
.IR newty .
.PP
The
.B UNCONST
macro checks at compile-time that
.I p
has (or, at least, is assignment-compatible with) type
.BI "const " type "\ *" \fR.
If so, it returns
.I p
converted to type
.IB type "\ *" \fR,
i.e., it removes any
.B const
qualification from the type that
.I p
points to.
The
.B UNVOLATILE
macro is similar, except that it removes any
.B volatile
qualification;
and the
.B UNQUALIFY
macro
removes any
.B const
.I or
.B volatile
qualification.
.PP
The
.B COMMA
macro expands to a comma
.BR ` , ',
which is useful for smuggling commas into macro arguments
if they can't be protected by parentheses.
.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.
.PP
The
.B LAUNDER
macro tries to confuse a compiler so that it `forgets' what it knows
about a particular value.  This is most useful in benchmarking or
similar applications.
.PP
The
.B RELAX
macro tries do nothing, but in a way that a compiler won't optimize
away.
.
.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_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 compiler (3).
.BR mLib (3),
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------