[deliverable/binutils-gdb.git] / gnulib / import / attribute.h

/* ATTRIBUTE_* macros for using attributes in GCC and similar compilers

   Copyright 2020-2021 Free Software Foundation, Inc.

   This program is free software: you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published
   by the Free Software Foundation; either version 3 of the License, or
   (at your option) any later version.

   This program 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
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <https://www.gnu.org/licenses/>.  */

/* Written by Paul Eggert.  */

/* Provide public ATTRIBUTE_* names for the private _GL_ATTRIBUTE_*
   macros used within Gnulib.  */

/* These attributes can be placed in two ways:
     - At the start of a declaration (i.e. even before storage-class
       specifiers!); then they apply to all entities that are declared
       by the declaration.
     - Immediately after the name of an entity being declared by the
       declaration; then they apply to that entity only.  */

#ifndef _GL_ATTRIBUTE_H
#define _GL_ATTRIBUTE_H


/* This file defines two types of attributes:
   * C2X standard attributes.  These have macro names that do not begin with
     'ATTRIBUTE_'.
   * Selected GCC attributes; see:
     https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
     https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
     https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html
     These names begin with 'ATTRIBUTE_' to avoid name clashes.  */


/* =============== Attributes for specific kinds of functions =============== */

/* Attributes for functions that should not be used.  */

/* Warn if the entity is used.  */
/* Applies to:
     - function, variable,
     - struct, union, struct/union member,
     - enumeration, enumeration item,
     - typedef,
   in C++ also: namespace, class, template specialization.  */
#define DEPRECATED _GL_ATTRIBUTE_DEPRECATED

/* If a function call is not optimized way, warn with MSG.  */
/* Applies to: functions.  */
#define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg)

/* If a function call is not optimized way, report an error with MSG.  */
/* Applies to: functions.  */
#define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg)


/* Attributes for memory-allocating functions.  */

/* The function returns a pointer to freshly allocated memory.  */
/* Applies to: functions.  */
#define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC

/* ATTRIBUTE_ALLOC_SIZE ((N)) - The Nth argument of the function
   is the size of the returned memory block.
   ATTRIBUTE_ALLOC_SIZE ((M, N)) - Multiply the Mth and Nth arguments
   to determine the size of the returned memory block.  */
/* Applies to: function, pointer to function, function types.  */
#define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args)


/* Attributes for variadic functions.  */

/* The variadic function expects a trailing NULL argument.
   ATTRIBUTE_SENTINEL () - The last argument is NULL (requires C99).
   ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL.  */
/* Applies to: functions.  */
#define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos)


/* ================== Attributes for compiler diagnostics ================== */

/* Attributes that help the compiler diagnose programmer mistakes.
   Some of them may also help for some compiler optimizations.  */

/* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) -
   The STRING-INDEXth function argument is a format string of style
   ARCHETYPE, which is one of:
     printf, gnu_printf
     scanf, gnu_scanf,
     strftime, gnu_strftime,
     strfmon,
   or the same thing prefixed and suffixed with '__'.
   If FIRST-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK
   are suitable for the format string.  */
/* Applies to: functions.  */
#define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec)

/* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL.
   ATTRIBUTE_NONNULL () - All pointer arguments must not be null.  */
/* Applies to: functions.  */
#define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args)

/* The function's return value is a non-NULL pointer.  */
/* Applies to: functions.  */
#define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL

/* Warn if the caller does not use the return value,
   unless the caller uses something like ignore_value.  */
/* Applies to: function, enumeration, class.  */
#define NODISCARD _GL_ATTRIBUTE_NODISCARD


/* Attributes that disable false alarms when the compiler diagnoses
   programmer "mistakes".  */

/* Do not warn if the entity is not used.  */
/* Applies to:
     - function, variable,
     - struct, union, struct/union member,
     - enumeration, enumeration item,
     - typedef,
   in C++ also: class.  */
#define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED

/* The contents of a character array is not meant to be NUL-terminated.  */
/* Applies to: struct/union members and variables that are arrays of element
   type '[[un]signed] char'.  */
#define ATTRIBUTE_NONSTRING _GL_ATTRIBUTE_NONSTRING

/* Do not warn if control flow falls through to the immediately
   following 'case' or 'default' label.  */
/* Applies to: Empty statement (;), inside a 'switch' statement.  */
#define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH


/* ================== Attributes for debugging information ================== */

/* Attributes regarding debugging information emitted by the compiler.  */

/* Omit the function from stack traces when debugging.  */
/* Applies to: function.  */
#define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL

/* Make the entity visible to debuggers etc., even with '-fwhole-program'.  */
/* Applies to: functions, variables.  */
#define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE


/* ========== Attributes that mainly direct compiler optimizations ========== */

/* The function does not throw exceptions.  */
/* Applies to: functions.  */
#define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW

/* Do not inline the function.  */
/* Applies to: functions.  */
#define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE

/* Always inline the function, and report an error if the compiler
   cannot inline.  */
/* Applies to: function.  */
#define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE

/* It is OK for a compiler to omit duplicate calls with the same arguments.
   This attribute is safe for a function that neither depends on
   nor affects observable state, and always returns exactly once -
   e.g., does not loop forever, and does not call longjmp.
   (This attribute is stricter than ATTRIBUTE_PURE.)  */
/* Applies to: functions.  */
#define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST

/* It is OK for a compiler to omit duplicate calls with the same
   arguments if observable state is not changed between calls.
   This attribute is safe for a function that does not affect
   observable state, and always returns exactly once.
   (This attribute is looser than ATTRIBUTE_CONST.)  */
/* Applies to: functions.  */
#define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE

/* The function is rarely executed.  */
/* Applies to: functions.  */
#define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD

/* If called from some other compilation unit, the function executes
   code from that unit only by return or by exception handling,
   letting the compiler optimize that unit more aggressively.  */
/* Applies to: functions.  */
#define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF

/* For struct members: The member has the smallest possible alignment.
   For struct, union, class: All members have the smallest possible alignment,
   minimizing the memory required.  */
/* Applies to: struct members, struct, union,
   in C++ also: class.  */
#define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED


/* ================ Attributes that make invalid code valid ================ */

/* Attributes that prevent fatal compiler optimizations for code that is not
   fully ISO C compliant.  */

/* Pointers to the type may point to the same storage as pointers to
   other types, thus disabling strict aliasing optimization.  */
/* Applies to: types.  */
#define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS


#endif /* _GL_ATTRIBUTE_H */
Commit	Line	Data
698be2d8 CB	1	/* ATTRIBUTE_* macros for using attributes in GCC and similar compilers
698be2d8 CB	2
9c9d63b1	3	Copyright 2020-2021 Free Software Foundation, Inc.
698be2d8 CB	4
	5	This program is free software: you can redistribute it and/or modify it
	6	under the terms of the GNU General Public License as published
	7	by the Free Software Foundation; either version 3 of the License, or
	8	(at your option) any later version.
	9
	10	This program is distributed in the hope that it will be useful,
	11	but WITHOUT ANY WARRANTY; without even the implied warranty of
	12	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	13	General Public License for more details.
	14
	15	You should have received a copy of the GNU General Public License
	16	along with this program. If not, see <https://www.gnu.org/licenses/>. */
	17
	18	/* Written by Paul Eggert. */
	19
	20	/* Provide public ATTRIBUTE_* names for the private _GL_ATTRIBUTE_*
	21	macros used within Gnulib. */
	22
	23	/* These attributes can be placed in two ways:
	24	- At the start of a declaration (i.e. even before storage-class
	25	specifiers!); then they apply to all entities that are declared
	26	by the declaration.
	27	- Immediately after the name of an entity being declared by the
	28	declaration; then they apply to that entity only. */
	29
	30	#ifndef _GL_ATTRIBUTE_H
	31	#define _GL_ATTRIBUTE_H
	32
	33
	34	/* This file defines two types of attributes:
	35	* C2X standard attributes. These have macro names that do not begin with
	36	'ATTRIBUTE_'.
	37	* Selected GCC attributes; see:
	38	https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
	39	https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
	40	https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html
	41	These names begin with 'ATTRIBUTE_' to avoid name clashes. */
	42
	43
	44	/* =============== Attributes for specific kinds of functions =============== */
	45
	46	/* Attributes for functions that should not be used. */
	47
	48	/* Warn if the entity is used. */
	49	/* Applies to:
	50	- function, variable,
	51	- struct, union, struct/union member,
	52	- enumeration, enumeration item,
	53	- typedef,
	54	in C++ also: namespace, class, template specialization. */
	55	#define DEPRECATED _GL_ATTRIBUTE_DEPRECATED
	56
	57	/* If a function call is not optimized way, warn with MSG. */
	58	/* Applies to: functions. */
	59	#define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg)
	60
	61	/* If a function call is not optimized way, report an error with MSG. */
	62	/* Applies to: functions. */
	63	#define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg)
	64
	65
	66	/* Attributes for memory-allocating functions. */
	67
68	/* The function returns a pointer to freshly allocated memory. */
69	/* Applies to: functions. */
70	#define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC
71
72	/* ATTRIBUTE_ALLOC_SIZE ((N)) - The Nth argument of the function
73	is the size of the returned memory block.
74	ATTRIBUTE_ALLOC_SIZE ((M, N)) - Multiply the Mth and Nth arguments
75	to determine the size of the returned memory block. */
76	/* Applies to: function, pointer to function, function types. */
77	#define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args)
78
79
80	/* Attributes for variadic functions. */
81
82	/* The variadic function expects a trailing NULL argument.
9c9d63b1	83	ATTRIBUTE_SENTINEL () - The last argument is NULL (requires C99).
698be2d8 CB	84	ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL. */
	85	/* Applies to: functions. */
	86	#define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos)
	87
	88
	89	/* ================== Attributes for compiler diagnostics ================== */
	90
	91	/* Attributes that help the compiler diagnose programmer mistakes.
	92	Some of them may also help for some compiler optimizations. */
	93
	94	/* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) -
	95	The STRING-INDEXth function argument is a format string of style
	96	ARCHETYPE, which is one of:
	97	printf, gnu_printf
	98	scanf, gnu_scanf,
	99	strftime, gnu_strftime,
	100	strfmon,
	101	or the same thing prefixed and suffixed with '__'.
	102	If FIRST-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK
	103	are suitable for the format string. */
	104	/* Applies to: functions. */
	105	#define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec)
	106
	107	/* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL.
	108	ATTRIBUTE_NONNULL () - All pointer arguments must not be null. */
	109	/* Applies to: functions. */
	110	#define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args)
	111
	112	/* The function's return value is a non-NULL pointer. */
	113	/* Applies to: functions. */
	114	#define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL
	115
	116	/* Warn if the caller does not use the return value,
	117	unless the caller uses something like ignore_value. */
	118	/* Applies to: function, enumeration, class. */
	119	#define NODISCARD _GL_ATTRIBUTE_NODISCARD
	120
	121
	122	/* Attributes that disable false alarms when the compiler diagnoses
	123	programmer "mistakes". */
	124
	125	/* Do not warn if the entity is not used. */
	126	/* Applies to:
	127	- function, variable,
	128	- struct, union, struct/union member,
	129	- enumeration, enumeration item,
	130	- typedef,
	131	in C++ also: class. */
	132	#define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED
	133
	134	/* The contents of a character array is not meant to be NUL-terminated. */
	135	/* Applies to: struct/union members and variables that are arrays of element
	136	type '[[un]signed] char'. */
	137	#define ATTRIBUTE_NONSTRING _GL_ATTRIBUTE_NONSTRING
	138
	139	/* Do not warn if control flow falls through to the immediately
	140	following 'case' or 'default' label. */
	141	/* Applies to: Empty statement (;), inside a 'switch' statement. */
	142	#define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH
	143
	144
	145	/* ================== Attributes for debugging information ================== */
	146
	147	/* Attributes regarding debugging information emitted by the compiler. */
148
149	/* Omit the function from stack traces when debugging. */
150	/* Applies to: function. */
151	#define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL
152
153	/* Make the entity visible to debuggers etc., even with '-fwhole-program'. */
154	/* Applies to: functions, variables. */
155	#define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE
156
157
158	/* ========== Attributes that mainly direct compiler optimizations ========== */
159
160	/* The function does not throw exceptions. */
161	/* Applies to: functions. */
162	#define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW
163
164	/* Do not inline the function. */
165	/* Applies to: functions. */
166	#define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE
167
168	/* Always inline the function, and report an error if the compiler
169	cannot inline. */
170	/* Applies to: function. */
171	#define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE
172
9c9d63b1 PM	173	/* It is OK for a compiler to omit duplicate calls with the same arguments.
	174	This attribute is safe for a function that neither depends on
	175	nor affects observable state, and always returns exactly once -
	176	e.g., does not loop forever, and does not call longjmp.
	177	(This attribute is stricter than ATTRIBUTE_PURE.) */
698be2d8	178	/* Applies to: functions. */
9c9d63b1	179	#define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
698be2d8	180
9c9d63b1 PM	181	/* It is OK for a compiler to omit duplicate calls with the same
	182	arguments if observable state is not changed between calls.
	183	This attribute is safe for a function that does not affect
	184	observable state, and always returns exactly once.
	185	(This attribute is looser than ATTRIBUTE_CONST.) */
698be2d8	186	/* Applies to: functions. */
9c9d63b1	187	#define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE
698be2d8 CB	188
	189	/* The function is rarely executed. */
	190	/* Applies to: functions. */
	191	#define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD
	192
	193	/* If called from some other compilation unit, the function executes
	194	code from that unit only by return or by exception handling,
	195	letting the compiler optimize that unit more aggressively. */
	196	/* Applies to: functions. */
	197	#define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF
	198
	199	/* For struct members: The member has the smallest possible alignment.
	200	For struct, union, class: All members have the smallest possible alignment,
	201	minimizing the memory required. */
	202	/* Applies to: struct members, struct, union,
	203	in C++ also: class. */
	204	#define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED
	205
	206
	207	/* ================ Attributes that make invalid code valid ================ */
	208
	209	/* Attributes that prevent fatal compiler optimizations for code that is not
	210	fully ISO C compliant. */
	211
	212	/* Pointers to the type may point to the same storage as pointers to
	213	other types, thus disabling strict aliasing optimization. */
	214	/* Applies to: types. */
	215	#define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS
	216
	217
	218	#endif /* _GL_ATTRIBUTE_H */