SYMBOL_SCOPE and SYMBOL_VERSION Directives

The SYMBOL_SCOPE and SYMBOL_VERSION directives are used to specify the scope and attributes of global symbols. SYMBOL_SCOPE operates within the context of the unnamed base symbol version, while SYMBOL_VERSION is used to gather symbols into explicitly named global versions. The SYMBOL_VERSION directive allows the creation of stable interfaces that support object evolution in a backward compatible manner.

SYMBOL_VERSION has the following syntax.

        SYMBOL_VERSION version_name {
symbol_scope:
                        *;

symbol_name;
symbol_name {
                        ASSERT = {
                                ALIAS = symbol_name;
                                BINDING = symbol_binding;
                                TYPE = symbol_type;
                                SH_ATTR = section_attributes;

                                SIZE = size_value;
                                SIZE = size_value[count];

                                VALUE = value;
                        };

                        DEFERRED = soname;
                
                        AUXILIARY = soname;
                        FILTER = soname;
                        FILTER {
                                FILTEE = soname;
                                TYPE = filter_type;
                        };

                        FLAGS = symbol_flags....;
                
                        RENAME = symbol_name;
                        RENAME = MATCHREF(...);

                        SIZE = size_value;
                        SIZE = size_value[count];

                        TYPE = symbol_type;
                        VALUE = value;
                };

                MATCH(...);
                MATCH(...) {
See symbol_name
                };
        } [inherited_version_name....];

SYMBOL_SCOPE does not accept version names, but is otherwise identical.

        SYMBOL_SCOPE {
                ....
        };

In a SYMBOL_VERSION directive, version_name provides a label for this set of symbol definitions. This label identifies a version definition within the output object. One or more inherited versions (inherited_version_name) can be specified, separated by white space, in which case the newly defined version inherits from the versions named. See Interfaces and Versioning.

symbol_scope defines the scope of symbols in a SYMBOL_SCOPE or SYMBOL_VERSION directive. By default, symbols are assumed to have global scope. This can be modified by specifying a symbol_scope followed by a colon (:). These lines determine the symbol scope for all symbols that follow, until changed by a subsequent scope declaration. The possible scope values and their meanings are given in the following table.

Table 10-8 Symbol Scope Types

Scope	Meaning
default / global	Global symbols of this scope are visible to all external objects. References to such symbols from within the object are bound at runtime, thus allowing interposition to take place. This visibility scope provides a default, that can be demoted, or eliminated by other symbol visibility techniques. This scope definition has the same affect as a symbol with STV_DEFAULT visibility. See ELF Symbol Visibility.
hidden / local	Global symbols of this scope are reduced to symbols with a local binding. Symbols of this scope are not visible to other external objects. This scope definition has the same affect as a symbol with STV_HIDDEN visibility. See ELF Symbol Visibility.
protected / symbolic	Global symbols of this scope are visible to all external objects. References to these symbols from within the object are bound at link-edit, thus preventing runtime interposition. This visibility scope can be demoted, or eliminated by other symbol visibility techniques. This scope definition has the same affect as a symbol with STV_PROTECTED visibility. See ELF Symbol Visibility.
exported	Global symbols of this scope are visible to all external objects. References to such symbols from within the object are bound at runtime, thus allowing interposition to take place. This symbol visibility can not be demoted, or eliminated by any other symbol visibility technique. This scope definition has the same affect as a symbol with STV_EXPORTED visibility. See ELF Symbol Visibility.
singleton	Global symbols of this scope are visible to all external objects. References to such symbols from within the object are bound at runtime, and ensure that only one instance of the symbol is bound to from all references within a process. This symbol visibility can not be demoted, or eliminated by any other symbol visibility technique. This scope definition has the same affect as a symbol with STV_SINGLETON visibility. See ELF Symbol Visibility.
eliminate	Global symbols of this scope are hidden. Their symbol table entries are eliminated. This scope definition has the same affect as a symbol with STV_ELIMINATE visibility. See ELF Symbol Visibility.

A symbol_name is the name of a symbol. This name can result in a symbol definition, or a symbol reference, depending on any qualifying attributes. In the simplest form, without any qualifying attributes, a symbol reference is created. This reference is exactly the same as would be generated using the -u option discussed in Defining Additional Symbols with the -u option. Typically, if the symbol name is followed by any qualifying attributes, then a symbol definition is generated using the associated attributes.

The symbol can also be specified as a MATCH expression. See MATCH and MATCHREF Expressions.

When a local scope is defined, the symbol name can be defined as the special "*" auto-reduction directive. Symbols that have no explicitly defined visibility are demoted to a local binding within the dynamic object being generated. Explicit visibility definitions originate from mapfile definitions, or visibility definitions that are encapsulated within relocatable objects. Similarly, when an eliminate scope is defined, the symbol name can be defined as the special "*" auto-elimination directive. Symbols that have no explicitly defined visibility are eliminated from the dynamic object being generated.

If a SYMBOL_VERSION directive is specified, or if auto-reduction is specified with either SYMBOL_VERSION or SYMBOL_SCOPE, then versioning information is recorded in the image created. If this image is a dynamic object, then any symbol reduction is also applied.

If the image being created is a relocatable object, then by default, no symbol reduction is applied. In this case, any symbol reductions are recorded as part of the versioning information. These reductions are applied when the relocatable object is finally used to generate a dynamic object. The link-editor's -B reduce option can be used to force symbol reduction when generating a relocatable object.

A more detailed description of the versioning information is provided in Interfaces and Versioning.

Note:

To ensure interface definition stability, no wildcard expansion is provided for defining symbol names.

A symbol_name can be listed by itself in order to simply assign the symbol to a version and/or specify its scope. Optional symbol attributes can be specified within {} brackets. Valid attributes are described below.