SYMBOL_SCOPE / SYMBOL_VERSION Directives (Linker and Libraries Guide)

Linker and Libraries Guide

SYMBOL_SCOPE / 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 {
                        AUXILIARY = soname;
                        FILTER = soname;
                        FLAGS = symbol_flags...;
                        SIZE = value;
                        TYPE = symbol_type;
                        VALUE = value;
                };
        } [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 Chapter 5, Application Binary 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 9–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 Table 7–20.
`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 Table 7–20.
`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 Table 7–20.
`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 Table 7–20.
`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 Table 7–20.
`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 Table 7–20. Note that local symbols can also be eliminated by using the link-editor `-z redlocsym` option.

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.

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 an executable or shared 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 an executable or shared 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 Chapter 5, Application Binary 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.

AUXILIARY Attribute

Indicates that this symbol is an auxiliary filter on the shared object name (soname). See Generating Auxiliary Filters.

FILTER Attribute

Indicates that this symbol is a filter on the shared object name. See Generating Standard Filters. Filter symbols do not require any backing implementation to be provided from an input relocatable object. Therefore, use this directive together with defining the symbol's type, to create an absolute symbol table entry.

FLAGS Attribute

symbol_flags specify symbol attributes as a space separated list of one or more of the following values.

Table 9–9 Symbol FLAG Values


Flag	Meaning
`DIRECT`	Indicates that this symbol should be directly bound to. When used with a symbol definition, this keyword results in any reference from within the object being built to be directly bound to the definition. When used with a symbol reference, this flag results in a direct binding to the dependency that provides the definition. See Appendix D, Direct Bindings. This flag can also be used with the `PARENT` flag to establish a direct binding to any parent at runtime.
`DYNSORT`	Indicates that this symbol should be included in a sort section. See Symbol Sort Sections. The symbol type must be `STT_FUNC`, `STT_OBJECT`, `STT_COMMON`, or `STT_TLS`.
`EXTERN`	Indicates the symbol is defined externally to the object being created. This keyword is typically defined to label callback routines. Undefined symbols that would be flagged with the `-z defs` option are suppressed with this flag. This flag is only meaningful when generating a symbol reference. Should a definition for this symbol occur within the objects combined at link-edit, then the keyword is silently ignored.
`INTERPOSE`	Indicates that this symbol acts an interposer. This flag can only be used when generating a dynamic executable. This flag provides for finer control of defining interposing symbols than is possible by using the `-z interpose` option.
`NODIRECT`	Indicates that this symbol should not be directly bound to. This state applies to references from within the object being created and from external references. See Appendix D, Direct Bindings. This flag can also be used with the `PARENT` flag to prevent a direct binding to any parent at runtime.
`NODYNSORT`	Indicates that this symbol should not be included in a sort section. See Symbol Sort Sections.
`PARENT`	Indicates the symbol is defined in the parent of the object being created. A parent is an object that references this object at runtime as an explicit dependency. A parent can also reference this object at runtime using dlopen(3C). This flag is typically defined to label callback routines. This flag can be used with the `DIRECT` or `NODIRECT` flags to establish individual direct, or no-direct references to the parent. Undefined symbols that would be flagged with the `-z defs` option are suppressed with this flag. This flag is only meaningful when generating a symbol reference. Should a definition for this symbol occur within the objects combined at link-edit, then the keyword is silently ignored.

SIZE Attribute

Sets the size attribute. This attribute results in the creation of a symbol definition.

TYPE Attribute

The symbol type attribute. This attribute can be either COMMON, DATA, or FUNCTION. COMMON results in a tentative symbol definition. DATA and FUNCTION result in a section symbol definition or an absolute symbol definition. See Symbol Table Section.

A data attribute results in the creation of an OBJT symbol. A data attribute that is accompanied with a size, but no value creates a section symbol by associating the symbol with an ELF section. This section is filled with zeros. A function attribute results in the creation of an FUNC symbol.

A function attribute that is accompanied with a size, but no value creates a section symbol by associating the symbol with an ELF section. This section is assigned a void function, generated by the link-editor, with the following signature.

        void (*)(void)

A data or function attribute that is accompanied with a value results in the appropriate symbol type together with an absolute, ABS, section index.

The creation of a section data symbol is useful for the creation of filters. External references to a section data symbol of a filter from an executable result in the appropriate copy relocation being generated. See Copy Relocations.

VALUE Attribute

Indicates the value attribute. This attribute results in the creation of a symbol definition.