ItaniumMangleAbiTags.rst source code [clang_source_code/docs/ItaniumMangleAbiTags.rst]

1	========
2	ABI tags
3	========
4
5	Introduction
6	============
7
8	This text tries to describe gcc semantic for mangling "abi_tag" attributes
9	described in https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html
10
11	There is no guarantee the following rules are correct, complete or make sense
12	in any way as they were determined empirically by experiments with gcc5.
13
14	Declaration
15	===========
16
17	ABI tags are declared in an abi_tag attribute and can be applied to a
18	function, variable, class or inline namespace declaration. The attribute takes
19	one or more strings (called tags); the order does not matter.
20
21	See https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html for
22	details.
23
24	Tags on an inline namespace are called "implicit tags", all other tags are
25	"explicit tags".
26
27	Mangling
28	========
29
30	All tags that are "active" on an <unqualified-name> are emitted after the
31	<unqualified-name>, before <template-args> or <discriminator>, and are part of
32	the same <substitution> the <unqualified-name> is.
33
34	They are mangled as:
35
36	.. code-block:: none
37
38	<abi-tags> ::= <abi-tag>* # sort by name
39	<abi-tag> ::= B <tag source-name>
40
41	Example:
42
43	.. code-block:: c++
44
45	__attribute__((abi_tag("test")))
46	void Func();
47	// gets mangled as: _Z4FuncB4testv (prettified as `Func[abi:test]()`)
48
49	Active tags
50	===========
51
52	A namespace does not have any active tags. For types (class / struct / union /
53	enum), the explicit tags are the active tags.
54
55	For variables and functions, the active tags are the explicit tags plus any
56	"required tags" which are not in the "available tags" set:
57
58	.. code-block:: none
59
60	derived-tags := (required-tags - available-tags)
61	active-tags := explicit-tags + derived-tags
62
63	Required tags for a function
64	============================
65
66	If a function is used as a local scope for another name, and is part of
67	another function as local scope, it doesn't have any required tags.
68
69	If a function is used as a local scope for a guard variable name, it doesn't
70	have any required tags.
71
72	Otherwise the function requires any implicit or explicit tag used in the name
73	for the return type.
74
75	Example:
76
77	.. code-block:: c++
78
79	namespace A {
80	inline namespace B __attribute__((abi_tag)) {
81	struct C { int x; };
82	}
83	}
84
85	A::C foo(); // gets mangled as: _Z3fooB1Bv (prettified as `foo[abi:B]()`)
86
87	Required tags for a variable
88	============================
89
90	A variable requires any implicit or explicit tag used in its type.
91
92	Available tags
93	==============
94
95	All tags used in the prefix and in the template arguments for a name are
96	available. Also, for functions, all tags from the <bare-function-type>
97	(which might include the return type for template functions) are available.
98
99	For <local-name>s all active tags used in the local part (<function-
100	encoding>) are available, but not implicit tags which were not active.
101
102	Implicit and explicit tags used in the <unqualified-name> for a function (as
103	in the type of a cast operator) are NOT available.
104
105	Example: a cast operator to std::string (which is
106	std::__cxx11::basic_string<...>) will use 'cxx11' as an active tag, as it is
107	required from the return type `std::string` but not available.
108

Clang Project