[mLib] / utils / macros.h

/* -*-c-*-
 *
 * Handy macros
 *
 * (c) 2003 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.
 */

#ifndef MLIB_MACROS_H
#define MLIB_MACROS_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <assert.h>

#ifndef MLIB_COMPILER_H
#  include "compiler.h"
#endif

/*----- Miscellaneous utility macros --------------------------------------*/

/* --- @N@ --- *
 *
 * Arguments:	@type v[]@ = an actual array, not a pointer
 *
 * Returns:	The number of elements in @v@.
 */

#define N(v) (sizeof(v)/sizeof(*(v)))

/* --- @STR@ --- *
 *
 * Arguments:	@x@ = some tokens
 *
 * Returns:	A string literal containing the macro-expanded text of @x@.
 */

#define MLIB__STR(x) #x
#define STR(x) MLIB__STR(x)

/* --- @GLUE@ --- *
 *
 * Arguments:	@x, y@ = two sequences of tokens
 *
 * Returns:	A single token formed by gluing together the macro-expansions
 *		of @x@ and @y@.
 */

#define MLIB__GLUE(x, y) x##y
#define GLUE(x, y) MLIB__GLUE(x, y)

/* --- @STATIC_ASSERT@ --- *
 *
 * Arguments:	@int cond@ = a condition
 *		@msg@ = a string literal message
 *
 * Returns:	---
 *
 * Use:		Fail at compile time unless @cond@ is nonzero.  The failure
 *		might report @msg@.
 */

#ifdef static_assert
#  define STATIC_ASSERT(cond, msg) static_assert(!!(cond), msg)
#else
#  define STATIC_ASSERT(cond, msg)					\
	IGNORABLE extern char static_assert_failed[2*!!(cond) - 1]
#endif

/* --- @COMMA@ --- *
 *
 * Arguments:	---
 *
 * Returns:	A `%|,|%' token, which can be usefully passed to macros to
 *		avoid argument splitting.
 */

#define COMMA ,

/*----- String and character hacks ----------------------------------------*/

/* --- @IS...@ --- *
 *
 * Arguments:	@int ch@ = a character code, but not @EOF@
 *
 * Returns:	Nonzero if @ch@ is in the relevant @<ctype.h>@ category.
 *
 * Use:		Classifies characters, but safely even if characters are
 *		signed.
 *
 *		There is a macro for each of the @<ctype.h>@ @is...@
 *		functions.
 */

#define CTYPE_HACK(func, ch) (func((unsigned char)(ch)))

#define ISALNUM(ch) CTYPE_HACK(isalnum, ch)
#define ISALPHA(ch) CTYPE_HACK(isalpha, ch)
#define ISASCII(ch) CTYPE_HACK(isascii, ch)
#define ISBLANK(ch) CTYPE_HACK(isblank, ch)
#define ISCNTRL(ch) CTYPE_HACK(iscntrl, ch)
#define ISDIGIT(ch) CTYPE_HACK(isdigit, ch)
#define ISGRAPH(ch) CTYPE_HACK(isgraph, ch)
#define ISLOWER(ch) CTYPE_HACK(islower, ch)
#define ISPRINT(ch) CTYPE_HACK(isprint, ch)
#define ISPUNCT(ch) CTYPE_HACK(ispunct, ch)
#define ISSPACE(ch) CTYPE_HACK(isspace, ch)
#define ISUPPER(ch) CTYPE_HACK(isupper, ch)
#define ISXDIGIT(ch) CTYPE_HACK(isxdigit, ch)

/* --- @TO...@ --- *
 *
 * Arguments:	@int ch@ = a character code, but not @EOF@
 *
 * Returns:	The converted character code.
 *
 * Use:		Converts characters, but safely even if characters are
 *		signed.
 *
 *		There is a macro for each of the @<ctype.h>@ @to...@
 *		functions.
 */

#define TOASCII(ch) CTYPE_HACK(toascii, ch)
#define TOLOWER(ch) CTYPE_HACK(tolower, ch)
#define TOUPPER(ch) CTYPE_HACK(toupper, ch)

/* --- @MEMCMP@, @STRCMP@, @STRNCMP@ --- *
 *
 * Arguments:	@const type *x, *y@ = pointers to strings
 *		@op@ = a relational operator symbol
 *		@size_t n@ = length of the strings
 *
 * Returns:	Nonzero if the relationship between the strings satisfies the
 *		operator @op@, otherwise zero.
 *
 * Use:		These macros mitigate the author's frequent error of failing
 *		to compare the result of the underlying standard functions
 *		against zero, effectively reversing the sense of an intended
 *		test for equality.
 */

#define MEMCMP(x, op, y, n) (memcmp((x), (y), (n)) op 0)
#define STRCMP(x, op, y) (strcmp((x), (y)) op 0)
#define STRNCMP(x, op, y, n) (strncmp((x), (y), (n)) op 0)

/*----- Compiler-specific definitions -------------------------------------*/

/* The descriptions of these are given below, with the fallback
 * definitions.
 */

#if GCC_VERSION_P(2, 5) || CLANG_VERSION_P(3, 3)
#  define NORETURN __attribute__((__noreturn__))
#  define PRINTF_LIKE(fix, aix) __attribute__((__format__(printf, fix, aix)))
#  define SCANF_LIKE(fix, aix) __attribute__((__format__(scanf, fix, aix)))
#  define IGNORABLE __attribute__((__unused__))
#endif

#if GCC_VERSION_P(3, 4) || CLANG_VERSION_P(3, 3)
#  define MUST_CHECK __attribute__((__warn_unused_result__))
#endif

#if GCC_VERSION_P(4, 5) || CLANG_VERSION_P(3, 3)
#  define DEPRECATED(msg) __attribute__((__deprecated__(msg)))
#elif GCC_VERSION_P(3, 1)
#  define DEPRECATED(msg) __attribute__((__deprecated__))
#endif

#if GCC_VERSION_P(4, 0) || CLANG_VERSION_P(3, 3)
#  define EXECL_LIKE(ntrail) __attribute__((__sentinel__(ntrail)))
#endif

#if GCC_VERSION_P(2, 7) || CLANG_VERSION_P(0, 0)
#  define LAUNDER(x)							\
	({ __typeof__(x) _y; __asm__("" : "=g"(_y) : "0"(x)); _y; })
#  define RELAX do __asm__ __volatile__("" ::: "memory"); while (0)
#endif

#if CLANG_VERSION_P(3, 3)

#  define MLIB__PRAGMA_HACK(x) _Pragma(#x)
#  define MLIB__MUFFLE_WARNINGS(warns, body)				\
	_Pragma("clang diagnostic push")				\
	warns								\
	body								\
	_Pragma("clang diagnostic pop")
#  define CLANG_WARNING(warn)						\
	MLIB__PRAGMA_HACK(clang diagnostic ignored warn)
#  define MUFFLE_WARNINGS_DECL(warns, body)				\
	MLIB__MUFFLE_WARNINGS(warns, body)
#  define MUFFLE_WARNINGS_EXPR(warns, body)				\
	__extension__ ({ MLIB__MUFFLE_WARNINGS(warns, (body);) })
#  define MUFFLE_WARNINGS_STMT(warns, body)				\
	do { MLIB__MUFFLE_WARNINGS(warns, body) } while (0)

#endif

#if GCC_VERSION_P(4, 6)

   /* --- Diagnostic suppression in GCC: a tale of woe --- *
    *
    * This is extremely unpleasant, largely as a result of bugs in the GCC
    * preprocessor's handling of @_Pragma@.  The fundamental problem is
    * that it's the preprocessor, and not the compiler proper, which
    * detects @_Pragma@, emitting @#pragma@ lines into its output; and it
    * does it during macro expansion, even if the macro is being expanded
    * during argument collection.  Since arguments are expanded before
    * replacing the macro's invocation with its body, a pragma in an
    * argument will be emitted %%\emph{before}%% any pragmata in the body,
    * even if they appear before the argument in the body -- and even if
    * the argument doesn't actually appear anywhere at all in the body.
    *
    * Another, rather less significant, problem is that @_Pragma@'s
    * argument is a single string literal, recognized in translation phase
    * 4, before string-literal concatenation in phase 6, so we must build
    * pragma bodies as token lists and then stringify them.
    *
    * As a result, we need some subterfuge here.  The @MLIB__PRAGMA_HACK@
    * macro issues a @_Pragma@ on its argument token list, which it
    * stringifies; this deals with the second problem.  The first is
    * trickier: we must delay expansion of @MLIB__PRAGMA_HACK@ from the
    * argument collection phase to the body rescanning phase, and we do
    * this by splitting the invocations between @GCC_WARNING@ macro calls:
    * the name is left hanging from the previous call (or from
    * @MLIB__MUFFLE_WARNINGS@, in the first case) and the body is supplied
    * by @GCC_WARNING@, which also supplies the next @MLIB__PRAGMA_HACK@.
    * The remaining problem is to make sure we can dispose of the final
    * trailing @MLIB__PRAGMA_HACK@ harmlessly, which we do by introducing
    * an extra argument @emitp@, which may be either @t@ or @nil@; this
    * dispatches to an appropriate helper macro by means of token-pasting.
    *
    * I'm so sorry.
    */

#  define MLIB__PRAGMA_HACK_t(x) _Pragma(#x)
#  define MLIB__PRAGMA_HACK_nil(x)
#  define MLIB__PRAGMA_HACK(emitp, x) MLIB__PRAGMA_HACK_##emitp(x)
#  define MLIB__MUFFLE_WARNINGS(warns, body)				\
	_Pragma("GCC diagnostic push") MLIB__PRAGMA_HACK		\
	warns								\
	(nil, nil)							\
	body								\
	_Pragma("GCC diagnostic pop")
#  define GCC_WARNING(warn)						\
	(t, GCC diagnostic ignored warn) MLIB__PRAGMA_HACK
#  define MUFFLE_WARNINGS_DECL(warns, body)				\
	MLIB__MUFFLE_WARNINGS(warns, body)
#  define MUFFLE_WARNINGS_EXPR(warns, body)				\
	__extension__ ({ MLIB__MUFFLE_WARNINGS(warns, (body);) })
#  define MUFFLE_WARNINGS_STMT(warns, body)				\
	do { MLIB__MUFFLE_WARNINGS(warns, body) } while (0)
#endif

/* --- Fallback definitions, mostly trivial --- */

/* --- @DISCARD@ --- *
 *
 * Arguments:	@x@ = a function call
 *
 * Returns:	---
 *
 * Use:		Explicitly discard the result of @x@.  This counteracts a
 *		@MUST_CHECK@ attribute on the called function.
 */

#ifndef DISCARD
#  define DISCARD(x) do if (x); while (0)
#endif

/* --- @IGNORE@ --- *
 *
 * Arguments:	@x@ = any expression
 *
 * Returns:	---
 *
 * Use:		Ignore the value of @x@, overriding compiler warnings.
 */

#ifndef IGNORE
#  define IGNORE(x) ((void)(x))
#endif

/* --- @LAUNDER@ --- *
 *
 * Arguments:	@x@ = some integer expression
 *
 * Returns:	@x@.
 *
 * Use:		Causes a compiler to know nothing about the value of @x@,
 *		even if it looks obvious, e.g., it's a constant.
 */

#ifndef LAUNDER
#  define LAUNDER(x) (x)
#endif

/* --- @RELAX@ --- *
 *
 * Arguments:	---
 *
 * Returns:	---
 *
 * Use:		Does nothing, but the compiler doesn't know that.
 */

#ifndef RELAX
#  define RELAX
#endif

/* --- @DEPRECATED@, @NORETURN@, @IGNORABLE@, @MUST_CHECK@ --- *
 *
 * Use:		These are (mostly) function attributes; write them among the
 *		declaration specifiers for a function definition or
 *		declaration.  These may not do anything, but the intended
 *		behaviour is as follows.
 *
 *		  * @DEPRECATED(msg)@ -- report a warning, quoting the string
 *		    literal @msg@, if the function is called.
 *
 *		  * @NORETURN@ -- promise that the function doesn't return to
 *		    its caller: either it kills the process, or it performs
 *		    some nonlocal transfer.
 *
 *		  * @IGNORABLE@ -- the item (which might be data rather than
 *		    a function) might not be referred to, but that's OK:
 *		    don't warn about it.
 *
 *		  @ @MUST_CHECK@ -- warn if the return value of a function is
 *		    ignored.  Use @DISCARD@ if you really don't care.
 */

#ifndef DEPRECATED
#  define DEPRECATED(msg)
#endif

#ifndef NORETURN
#  define NORETURN
#endif

#ifndef IGNORABLE
#  define IGNORABLE
#endif

#ifndef MUST_CHECK
#  define MUST_CHECK
#endif

/* --- @PRINTF_LIKE@, @SCANF_LIKE@, @EXECL_LIKE@ --- *
 *
 * Arguments:	@int fmtix@ = format string argument index (starting from 1)
 *		@int argix@ = variable format argument tail index (starting
 *			from 1)
 *		@int ntrail@ = number of arguments following terminator
 *
 * Use:		These are function attributes.  Again, they might not do
 *		anything at all.  By intention, they give the compiler
 *		information about a variadic function's arguments, so that it
 *		can warn about misuse.
 *
 *		  * @PRINTF_LIKE@ -- the function takes a @printf@-style
 *		    format string as argument @fmtix@ and an argument tail
 *		    (which may be empty) beginning with argument @argix@.
 *
 *		  * @SCANF_LIKE@ -- the function takes a @scanf@-style
 *		    format string as argument @fmtix@ and an argument tail
 *		    (which may be empty) beginning with argument @argix@.
 *
 *		  * @EXECL_LIKE@ -- the function takes a sequence of pointer
 *		    arguments terminated by a null pointer, followed by
 *		    @ntrail@ further arguments.
 */

#ifndef PRINTF_LIKE
#  define PRINF_LIKE(fmtix, argix)
#endif

#ifndef SCANF_LIKE
#  define SCANF_LIKE(fmtix, argix)
#endif

#ifndef EXECL_LIKE
#  define EXECL_LIKE(ntrail)
#endif

/* --- @MUFFLE_WARNINGS_...@ --- *
 *
 * Arguments:	@warns@ = a sequence of @..._WARNING@ calls (see below)
 *		@body@ = some program text
 *
 * Use:		Muffle specific warnings within the program text.
 *
 *		For @MUFFLE_WARNINGS_DECL@, the program text is a
 *		declaration; for @MUFFLE_WARNINGS_EXPR@, it is an expression,
 *		and for @MUFFLE_WARNINGS_STMT@, it is a statement.
 *
 *		The warnings to be muffled are given as a list of
 *		@..._WARNING@ macros, with no separators.  The list can
 *		list warnings from multiple different compilers: entries for
 *		irrelevant compilers will be ignored.
 */

#ifndef MUFFLE_WARNINGS_DECL
#  define MUFFLE_WARNINGS_DECL(warns, body) body
#endif

#ifndef MUFFLE_WARNINGS_EXPR
#  define MUFFLE_WARNINGS_EXPR(warns, body) (body)
#endif

#ifndef MUFFLE_WARNINGS_STMT
#  define MUFFLE_WARNINGS_STMT(warns, body) do { body } while (0)
#endif

/* --- @GCC_WARNING@ --- *
 *
 * Arguments:	@warn@ = a string literal naming a warning, with `%|-W...|%'
 *			prefix
 *
 * Use:		Names a GCC warning: use within @MUFFLE_WARNINGS_...@.
 *
 *		Note that GCC's warning suppression is very buggy.
 */

#ifndef GCC_WARNING
#  define GCC_WARNING(warn)
#endif

/* --- @CLANG_WARNING@ --- *
 *
 * Arguments:	@warn@ = a string literal naming a warning, with `%|-W...|%'
 *			prefix
 *
 * Use:		Names a Clang warning: use within @MUFFLE_WARNINGS_...@.
 */

#ifndef CLANG_WARNING
#  define CLANG_WARNING(warn)
#endif

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif
Commit	Line	Data
14d7100d	1	/* --c--
16139d88	2	*
16139d88	3	* Handy macros
14d7100d	4	*
	5	* (c) 2003 Straylight/Edgeware
	6	*/
	7
d4efbcd9	8	/----- Licensing notice --------------------------------------------------
14d7100d	9	*
	10	* This file is part of the mLib utilities library.
	11	*
	12	* mLib is free software; you can redistribute it and/or modify
	13	* it under the terms of the GNU Library General Public License as
	14	* published by the Free Software Foundation; either version 2 of the
	15	* License, or (at your option) any later version.
d4efbcd9	16	*
14d7100d	17	* mLib is distributed in the hope that it will be useful,
	18	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	19	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	20	* GNU Library General Public License for more details.
d4efbcd9	21	*
14d7100d	22	* You should have received a copy of the GNU Library General Public
	23	* License along with mLib; if not, write to the Free
	24	* Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
	25	* MA 02111-1307, USA.
	26	*/
	27
14d7100d	28	#ifndef MLIB_MACROS_H
	29	#define MLIB_MACROS_H
	30
	31	#ifdef __cplusplus
	32	extern "C" {
	33	#endif
	34
33e3ac90 MW	35	/----- Header files ------------------------------------------------------/
33e3ac90 MW	36
f50c1365 MW	37	#include <assert.h>
f50c1365 MW	38
33e3ac90 MW	39	#ifndef MLIB_COMPILER_H
	40	# include "compiler.h"
	41	#endif
	42
3832000d	43	/----- Miscellaneous utility macros --------------------------------------/
14d7100d	44
6e683a79 MW	45	/* --- @N@ --- *
	46	*
	47	* Arguments: @type v[]@ = an actual array, not a pointer
	48	*
	49	* Returns: The number of elements in @v@.
	50	*/
	51
c066b1ff	52	#define N(v) (sizeof(v)/sizeof(*(v)))
14d7100d	53
6e683a79 MW	54	/* --- @STR@ --- *
	55	*
	56	* Arguments: @x@ = some tokens
	57	*
	58	* Returns: A string literal containing the macro-expanded text of @x@.
	59	*/
	60
16139d88	61	#define MLIB__STR(x) #x
	62	#define STR(x) MLIB__STR(x)
	63
6e683a79 MW	64	/* --- @GLUE@ --- *
	65	*
	66	* Arguments: @x, y@ = two sequences of tokens
	67	*
	68	* Returns: A single token formed by gluing together the macro-expansions
	69	* of @x@ and @y@.
	70	*/
	71
16139d88	72	#define MLIB__GLUE(x, y) x##y
	73	#define GLUE(x, y) MLIB__GLUE(x, y)
	74
6e683a79 MW	75	/* --- @STATIC_ASSERT@ --- *
	76	*
	77	* Arguments: @int cond@ = a condition
	78	* @msg@ = a string literal message
	79	*
	80	* Returns: ---
	81	*
	82	* Use: Fail at compile time unless @cond@ is nonzero. The failure
	83	* might report @msg@.
	84	*/
	85
f50c1365	86	#ifdef static_assert
dd65cf2d	87	# define STATIC_ASSERT(cond, msg) static_assert(!!(cond), msg)
f50c1365 MW	88	#else
	89	# define STATIC_ASSERT(cond, msg) \
	90	IGNORABLE extern char static_assert_failed[2*!!(cond) - 1]
	91	#endif
	92
6e683a79 MW	93	/* --- @COMMA@ --- *
	94	*
	95	* Arguments: ---
	96	*
	97	* Returns: A `%\|,\|%' token, which can be usefully passed to macros to
	98	* avoid argument splitting.
	99	*/
	100
e6591bec MW	101	#define COMMA ,
e6591bec MW	102
36188114 MW	103	/----- String and character hacks ----------------------------------------/
36188114 MW	104
6e683a79 MW	105	/* --- @IS...@ --- *
	106	*
	107	* Arguments: @int ch@ = a character code, but not @EOF@
	108	*
	109	* Returns: Nonzero if @ch@ is in the relevant @<ctype.h>@ category.
	110	*
	111	* Use: Classifies characters, but safely even if characters are
	112	* signed.
	113	*
	114	* There is a macro for each of the @<ctype.h>@ @is...@
	115	* functions.
	116	*/
	117
36188114 MW	118	#define CTYPE_HACK(func, ch) (func((unsigned char)(ch)))
	119
	120	#define ISALNUM(ch) CTYPE_HACK(isalnum, ch)
	121	#define ISALPHA(ch) CTYPE_HACK(isalpha, ch)
	122	#define ISASCII(ch) CTYPE_HACK(isascii, ch)
	123	#define ISBLANK(ch) CTYPE_HACK(isblank, ch)
	124	#define ISCNTRL(ch) CTYPE_HACK(iscntrl, ch)
	125	#define ISDIGIT(ch) CTYPE_HACK(isdigit, ch)
	126	#define ISGRAPH(ch) CTYPE_HACK(isgraph, ch)
	127	#define ISLOWER(ch) CTYPE_HACK(islower, ch)
	128	#define ISPRINT(ch) CTYPE_HACK(isprint, ch)
	129	#define ISPUNCT(ch) CTYPE_HACK(ispunct, ch)
	130	#define ISSPACE(ch) CTYPE_HACK(isspace, ch)
	131	#define ISUPPER(ch) CTYPE_HACK(isupper, ch)
	132	#define ISXDIGIT(ch) CTYPE_HACK(isxdigit, ch)
	133
6e683a79 MW	134	/* --- @TO...@ --- *
	135	*
	136	* Arguments: @int ch@ = a character code, but not @EOF@
	137	*
	138	* Returns: The converted character code.
	139	*
	140	* Use: Converts characters, but safely even if characters are
	141	* signed.
	142	*
	143	* There is a macro for each of the @<ctype.h>@ @to...@
	144	* functions.
	145	*/
	146
36188114 MW	147	#define TOASCII(ch) CTYPE_HACK(toascii, ch)
	148	#define TOLOWER(ch) CTYPE_HACK(tolower, ch)
	149	#define TOUPPER(ch) CTYPE_HACK(toupper, ch)
	150
6e683a79 MW	151	/* --- @MEMCMP@, @STRCMP@, @STRNCMP@ --- *
	152	*
	153	* Arguments: @const type x, y@ = pointers to strings
	154	* @op@ = a relational operator symbol
	155	* @size_t n@ = length of the strings
	156	*
	157	* Returns: Nonzero if the relationship between the strings satisfies the
	158	* operator @op@, otherwise zero.
	159	*
	160	* Use: These macros mitigate the author's frequent error of failing
	161	* to compare the result of the underlying standard functions
	162	* against zero, effectively reversing the sense of an intended
	163	* test for equality.
	164	*/
	165
36188114 MW	166	#define MEMCMP(x, op, y, n) (memcmp((x), (y), (n)) op 0)
	167	#define STRCMP(x, op, y) (strcmp((x), (y)) op 0)
	168	#define STRNCMP(x, op, y, n) (strncmp((x), (y), (n)) op 0)
	169
6e683a79	170	/----- Compiler-specific definitions -------------------------------------/
3832000d	171
6e683a79 MW	172	/* The descriptions of these are given below, with the fallback
	173	* definitions.
	174	*/
3832000d	175
ff3d3f01	176	#if GCC_VERSION_P(2, 5) \|\| CLANG_VERSION_P(3, 3)
2eea6973 MW	177	# define NORETURN __attribute__((__noreturn__))
	178	# define PRINTF_LIKE(fix, aix) __attribute__((__format__(printf, fix, aix)))
	179	# define SCANF_LIKE(fix, aix) __attribute__((__format__(scanf, fix, aix)))
	180	# define IGNORABLE __attribute__((__unused__))
d94956b5 MW	181	#endif
d94956b5 MW	182
8c470f2a MW	183	#if GCC_VERSION_P(3, 4) \|\| CLANG_VERSION_P(3, 3)
	184	# define MUST_CHECK __attribute__((__warn_unused_result__))
	185	#endif
	186
ff3d3f01	187	#if GCC_VERSION_P(4, 5) \|\| CLANG_VERSION_P(3, 3)
2eea6973	188	# define DEPRECATED(msg) __attribute__((__deprecated__(msg)))
d94956b5	189	#elif GCC_VERSION_P(3, 1)
2eea6973	190	# define DEPRECATED(msg) __attribute__((__deprecated__))
d94956b5 MW	191	#endif
d94956b5 MW	192
ff3d3f01	193	#if GCC_VERSION_P(4, 0) \|\| CLANG_VERSION_P(3, 3)
2eea6973	194	# define EXECL_LIKE(ntrail) __attribute__((__sentinel__(ntrail)))
d94956b5 MW	195	#endif
d94956b5 MW	196
c91413e6	197	#if GCC_VERSION_P(2, 7) \|\| CLANG_VERSION_P(0, 0)
b64eb60f MW	198	# define LAUNDER(x) \
	199	({ __typeof__(x) _y; __asm__("" : "=g"(_y) : "0"(x)); _y; })
	200	# define RELAX do __asm__ __volatile__("" ::: "memory"); while (0)
	201	#endif
	202
ff3d3f01 MW	203	#if CLANG_VERSION_P(3, 3)
	204
	205	# define MLIB__PRAGMA_HACK(x) _Pragma(#x)
	206	# define MLIB__MUFFLE_WARNINGS(warns, body) \
	207	_Pragma("clang diagnostic push") \
	208	warns \
	209	body \
	210	_Pragma("clang diagnostic pop")
	211	# define CLANG_WARNING(warn) \
	212	MLIB__PRAGMA_HACK(clang diagnostic ignored warn)
	213	# define MUFFLE_WARNINGS_DECL(warns, body) \
	214	MLIB__MUFFLE_WARNINGS(warns, body)
	215	# define MUFFLE_WARNINGS_EXPR(warns, body) \
	216	__extension__ ({ MLIB__MUFFLE_WARNINGS(warns, (body);) })
	217	# define MUFFLE_WARNINGS_STMT(warns, body) \
	218	do { MLIB__MUFFLE_WARNINGS(warns, body) } while (0)
	219
c91413e6 MW	220	#endif
	221
	222	#if GCC_VERSION_P(4, 6)
d94956b5 MW	223
	224	/* --- Diagnostic suppression in GCC: a tale of woe --- *
	225	*
	226	* This is extremely unpleasant, largely as a result of bugs in the GCC
	227	* preprocessor's handling of @_Pragma@. The fundamental problem is
	228	* that it's the preprocessor, and not the compiler proper, which
	229	* detects @_Pragma@, emitting @#pragma@ lines into its output; and it
	230	* does it during macro expansion, even if the macro is being expanded
	231	* during argument collection. Since arguments are expanded before
	232	* replacing the macro's invocation with its body, a pragma in an
	233	* argument will be emitted %%\emph{before}%% any pragmata in the body,
	234	* even if they appear before the argument in the body -- and even if
	235	* the argument doesn't actually appear anywhere at all in the body.
	236	*
	237	* Another, rather less significant, problem is that @_Pragma@'s
	238	* argument is a single string literal, recognized in translation phase
	239	* 4, before string-literal concatenation in phase 6, so we must build
	240	* pragma bodies as token lists and then stringify them.
	241	*
	242	* As a result, we need some subterfuge here. The @MLIB__PRAGMA_HACK@
	243	* macro issues a @_Pragma@ on its argument token list, which it
	244	* stringifies; this deals with the second problem. The first is
	245	* trickier: we must delay expansion of @MLIB__PRAGMA_HACK@ from the
	246	* argument collection phase to the body rescanning phase, and we do
	247	* this by splitting the invocations between @GCC_WARNING@ macro calls:
	248	* the name is left hanging from the previous call (or from
	249	* @MLIB__MUFFLE_WARNINGS@, in the first case) and the body is supplied
	250	* by @GCC_WARNING@, which also supplies the next @MLIB__PRAGMA_HACK@.
	251	* The remaining problem is to make sure we can dispose of the final
	252	* trailing @MLIB__PRAGMA_HACK@ harmlessly, which we do by introducing
	253	* an extra argument @emitp@, which may be either @t@ or @nil@; this
	254	* dispatches to an appropriate helper macro by means of token-pasting.
	255	*
	256	* I'm so sorry.
	257	*/
	258
	259	# define MLIB__PRAGMA_HACK_t(x) _Pragma(#x)
	260	# define MLIB__PRAGMA_HACK_nil(x)
	261	# define MLIB__PRAGMA_HACK(emitp, x) MLIB__PRAGMA_HACK_##emitp(x)
	262	# define MLIB__MUFFLE_WARNINGS(warns, body) \
3832000d MW	263	_Pragma("GCC diagnostic push") MLIB__PRAGMA_HACK \
	264	warns \
	265	(nil, nil) \
	266	body \
	267	_Pragma("GCC diagnostic pop")
d94956b5	268	# define GCC_WARNING(warn) \
3832000d	269	(t, GCC diagnostic ignored warn) MLIB__PRAGMA_HACK
d94956b5	270	# define MUFFLE_WARNINGS_DECL(warns, body) \
3832000d	271	MLIB__MUFFLE_WARNINGS(warns, body)
d94956b5	272	# define MUFFLE_WARNINGS_EXPR(warns, body) \
3832000d	273	__extension__ ({ MLIB__MUFFLE_WARNINGS(warns, (body);) })
d94956b5	274	# define MUFFLE_WARNINGS_STMT(warns, body) \
3832000d	275	do { MLIB__MUFFLE_WARNINGS(warns, body) } while (0)
3832000d MW	276	#endif
	277
	278	/* --- Fallback definitions, mostly trivial --- */
	279
6e683a79 MW	280	/* --- @DISCARD@ --- *
	281	*
	282	* Arguments: @x@ = a function call
	283	*
	284	* Returns: ---
	285	*
	286	* Use: Explicitly discard the result of @x@. This counteracts a
	287	* @MUST_CHECK@ attribute on the called function.
	288	*/
3832000d MW	289
	290	#ifndef DISCARD
	291	# define DISCARD(x) do if (x); while (0)
	292	#endif
	293
6e683a79 MW	294	/* --- @IGNORE@ --- *
	295	*
	296	* Arguments: @x@ = any expression
	297	*
	298	* Returns: ---
	299	*
	300	* Use: Ignore the value of @x@, overriding compiler warnings.
	301	*/
	302
3832000d MW	303	#ifndef IGNORE
	304	# define IGNORE(x) ((void)(x))
	305	#endif
	306
6e683a79 MW	307	/* --- @LAUNDER@ --- *
	308	*
	309	* Arguments: @x@ = some integer expression
	310	*
	311	* Returns: @x@.
	312	*
	313	* Use: Causes a compiler to know nothing about the value of @x@,
	314	* even if it looks obvious, e.g., it's a constant.
	315	*/
3832000d	316
6e683a79 MW	317	#ifndef LAUNDER
6e683a79 MW	318	# define LAUNDER(x) (x)
3832000d MW	319	#endif
3832000d MW	320
6e683a79 MW	321	/* --- @RELAX@ --- *
	322	*
	323	* Arguments: ---
	324	*
	325	* Returns: ---
	326	*
	327	* Use: Does nothing, but the compiler doesn't know that.
	328	*/
3832000d	329
6e683a79 MW	330	#ifndef RELAX
6e683a79 MW	331	# define RELAX
3832000d MW	332	#endif
3832000d MW	333
6e683a79 MW	334	/* --- @DEPRECATED@, @NORETURN@, @IGNORABLE@, @MUST_CHECK@ --- *
	335	*
	336	* Use: These are (mostly) function attributes; write them among the
	337	* declaration specifiers for a function definition or
	338	* declaration. These may not do anything, but the intended
	339	* behaviour is as follows.
	340	*
	341	* * @DEPRECATED(msg)@ -- report a warning, quoting the string
	342	* literal @msg@, if the function is called.
	343	*
	344	* * @NORETURN@ -- promise that the function doesn't return to
	345	* its caller: either it kills the process, or it performs
	346	* some nonlocal transfer.
	347	*
	348	* * @IGNORABLE@ -- the item (which might be data rather than
	349	* a function) might not be referred to, but that's OK:
	350	* don't warn about it.
	351	*
	352	* @ @MUST_CHECK@ -- warn if the return value of a function is
	353	* ignored. Use @DISCARD@ if you really don't care.
	354	*/
	355
	356	#ifndef DEPRECATED
	357	# define DEPRECATED(msg)
3832000d MW	358	#endif
3832000d MW	359
59eae7fd MW	360	#ifndef NORETURN
	361	# define NORETURN
	362	#endif
	363
3832000d MW	364	#ifndef IGNORABLE
	365	# define IGNORABLE
	366	#endif
	367
8c470f2a MW	368	#ifndef MUST_CHECK
	369	# define MUST_CHECK
	370	#endif
	371
6e683a79 MW	372	/* --- @PRINTF_LIKE@, @SCANF_LIKE@, @EXECL_LIKE@ --- *
	373	*
	374	* Arguments: @int fmtix@ = format string argument index (starting from 1)
	375	* @int argix@ = variable format argument tail index (starting
	376	* from 1)
	377	* @int ntrail@ = number of arguments following terminator
	378	*
	379	* Use: These are function attributes. Again, they might not do
	380	* anything at all. By intention, they give the compiler
	381	* information about a variadic function's arguments, so that it
	382	* can warn about misuse.
	383	*
	384	* * @PRINTF_LIKE@ -- the function takes a @printf@-style
	385	* format string as argument @fmtix@ and an argument tail
	386	* (which may be empty) beginning with argument @argix@.
	387	*
	388	* * @SCANF_LIKE@ -- the function takes a @scanf@-style
	389	* format string as argument @fmtix@ and an argument tail
	390	* (which may be empty) beginning with argument @argix@.
	391	*
	392	* * @EXECL_LIKE@ -- the function takes a sequence of pointer
	393	* arguments terminated by a null pointer, followed by
	394	* @ntrail@ further arguments.
	395	*/
	396
	397	#ifndef PRINTF_LIKE
	398	# define PRINF_LIKE(fmtix, argix)
b64eb60f MW	399	#endif
b64eb60f MW	400
6e683a79 MW	401	#ifndef SCANF_LIKE
6e683a79 MW	402	# define SCANF_LIKE(fmtix, argix)
b64eb60f MW	403	#endif
b64eb60f MW	404
6e683a79 MW	405	#ifndef EXECL_LIKE
	406	# define EXECL_LIKE(ntrail)
	407	#endif
	408
	409	/* --- @MUFFLE_WARNINGS_...@ --- *
	410	*
	411	* Arguments: @warns@ = a sequence of @..._WARNING@ calls (see below)
	412	* @body@ = some program text
	413	*
	414	* Use: Muffle specific warnings within the program text.
	415	*
	416	* For @MUFFLE_WARNINGS_DECL@, the program text is a
	417	* declaration; for @MUFFLE_WARNINGS_EXPR@, it is an expression,
	418	* and for @MUFFLE_WARNINGS_STMT@, it is a statement.
	419	*
	420	* The warnings to be muffled are given as a list of
	421	* @..._WARNING@ macros, with no separators. The list can
	422	* list warnings from multiple different compilers: entries for
	423	* irrelevant compilers will be ignored.
	424	*/
	425
	426	#ifndef MUFFLE_WARNINGS_DECL
	427	# define MUFFLE_WARNINGS_DECL(warns, body) body
	428	#endif
	429
	430	#ifndef MUFFLE_WARNINGS_EXPR
	431	# define MUFFLE_WARNINGS_EXPR(warns, body) (body)
	432	#endif
	433
	434	#ifndef MUFFLE_WARNINGS_STMT
	435	# define MUFFLE_WARNINGS_STMT(warns, body) do { body } while (0)
	436	#endif
	437
	438	/* --- @GCC_WARNING@ --- *
	439	*
	440	* Arguments: @warn@ = a string literal naming a warning, with `%\|-W...\|%'
	441	* prefix
	442	*
	443	* Use: Names a GCC warning: use within @MUFFLE_WARNINGS_...@.
	444	*
	445	* Note that GCC's warning suppression is very buggy.
	446	*/
	447
3832000d MW	448	#ifndef GCC_WARNING
	449	# define GCC_WARNING(warn)
	450	#endif
	451
6e683a79 MW	452	/* --- @CLANG_WARNING@ --- *
	453	*
	454	* Arguments: @warn@ = a string literal naming a warning, with `%\|-W...\|%'
	455	* prefix
	456	*
	457	* Use: Names a Clang warning: use within @MUFFLE_WARNINGS_...@.
	458	*/
	459
ff3d3f01 MW	460	#ifndef CLANG_WARNING
	461	# define CLANG_WARNING(warn)
	462	#endif
	463
14d7100d	464	/----- That's all, folks -------------------------------------------------/
	465
	466	#ifdef __cplusplus
	467	}
	468	#endif
	469
	470	#endif