ABI tags — Clang 8 documentation

# Clang 8 documentation

## ABI tags

## Introduction

This text tries to describe gcc semantic for mangling “abi_tag” attributes described in https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html

There is no guarantee the following rules are correct, complete or make sense in any way as they were determined empirically by experiments with gcc5.

## Declaration

ABI tags are declared in an abi_tag attribute and can be applied to a function, variable, class or inline namespace declaration. The attribute takes one or more strings (called tags); the order does not matter.

See https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html for details.

Tags on an inline namespace are called “implicit tags”, all other tags are “explicit tags”.

## Mangling

All tags that are “active” on an <unqualified-name> are emitted after the <unqualified-name>, before <template-args> or <discriminator>, and are part of the same <substitution> the <unqualified-name> is.

They are mangled as:

    <abi-tags> ::= <abi-tag>*   # sort by name
    <abi-tag> ::= B <tag source-name>

Example:

    __attribute__((abi_tag("test")))
    void Func();
    // gets mangled as: _Z4FuncB4testv (prettified as `Func[abi:test]()`)

## Active tags

A namespace does not have any active tags. For types (class / struct / union / enum), the explicit tags are the active tags.

For variables and functions, the active tags are the explicit tags plus any “required tags” which are not in the “available tags” set:

    derived-tags := (required-tags - available-tags)
    active-tags := explicit-tags + derived-tags

## Required tags for a function

If a function is used as a local scope for another name, and is part of another function as local scope, it doesn’t have any required tags.

If a function is used as a local scope for a guard variable name, it doesn’t have any required tags.

Otherwise the function requires any implicit or explicit tag used in the name for the return type.

Example:

    namespace A {
      inline namespace B __attribute__((abi_tag)) {
        struct C { int x; };
      }
    }

    A::C foo(); // gets mangled as: _Z3fooB1Bv (prettified as `foo[abi:B]()`)

## Required tags for a variable

A variable requires any implicit or explicit tag used in its type.

## Available tags

All tags used in the prefix and in the template arguments for a name are available. Also, for functions, all tags from the <bare-function-type> (which might include the return type for template functions) are available.

For <local-name>s all active tags used in the local part (<function- encoding>) are available, but not implicit tags which were not active.

Implicit and explicit tags used in the <unqualified-name> for a function (as in the type of a cast operator) are NOT available.

Example: a cast operator to std::string (which is std::__cxx11::basic_string<…>) will use ‘cxx11’ as an active tag, as it is required from the return type std::string but not available.