clang/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.