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;
SIZE = size_value;
SIZE = size_value[count];
VALUE = value;
};
AUXILIARY = soname;
FILTER = soname;
FLAGS = symbol_flags....;
SIZE = size_value;
SIZE = size_value[count];
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 9, 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.
|
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 9, Interfaces and Versioning.
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.
The ASSERT attribute is used to specify the expected characteristics of the symbol. The link-editor compares the symbol characteristics that result from the link-edit to those given by ASSERT attributes. If the real and asserted attributes do not agree, a fatal error is issued and the output object is not created.
The interpretation of the ASSERT attribute is dependent on whether the STUB_OBJECT directive or –z stub command line option are used. The three possible cases are as follows.
ASSERT attributes are not required when the STUB_OBJECT directive is not used. However, if ASSERT attributes exist, their attributes are verified against the real values collected with the link-edit. Should any ASSERT attributes not match their associated real values, the link-edit terminates unsuccessfully.
When the STUB_OBJECT directive is used, and the –z stub command line option is specified, the link-editor uses the ASSERT directives to define the attributes of the global symbols provided by the object. See Stub Objects.
When the STUB_OBJECT directive is used, and –z stub command line option is not specified, the link-editor requires that all global data in the resulting object have an associated ASSERT directive that declares it as data and supplies a size. In this mode, if the TYPE ASSERT attribute is not specified, GLOBAL is assumed. Similarly, if SH_ATTR is not specified, a default value of BITS is assumed. These defaults ensure that the data attributes of the stub and real objects are compatible. The resulting ASSERT statements are evaluated in the same manner as in the first case above. See STUB_OBJECT Directive.
ASSERT accepts the following attributes.
Defines an alias for a previously defined symbol. An alias symbol has the same type, value, and size as the main symbol. The ALIAS attribute cannot be used with the TYPE, SIZE, and SH_ATTR attributes. When ALIAS is specified, the type, size, and section attributes are obtained from the alias symbol.
Specifies an ELF symbol_binding, which can be any of the STB_ values defined in <sys/elf.h>, with the STB_ prefix removed. For example, GLOBAL, or WEAK.
Specifies an ELF symbol_type, which can be any of the STT_ constants defined in <sys/elf.h>, with the STT_ prefix removed. For example, OBJECT, COMMON, or FUNC. In addition, for compatibility with other mapfile usage, FUNCTION and DATA can be specified for STT_FUNC and STT_OBJECT, respectively. TYPE cannot be used with ALIAS.
Specifies attributes of the section associated with the symbol. The section_attributes that can be specified are given in Table 8–9. SH_ATTR cannot be used with ALIAS.
Specifies the expected symbol size. SIZE cannot be used with ALIAS. The syntax for the size_value argument is as described in the discussion of the SIZE attribute. See SIZE Attribute.
Specifies the expected symbol value.
|
Indicates that this symbol is an auxiliary filter on the shared object name (soname). See Generating Auxiliary Filters.
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.
symbol_flags specify symbol attributes as a space separated list of one or more of the following values.
|
Sets the size attribute. This attribute results in the creation of a symbol definition.
The size_value argument can be a numeric value, or it can be the symbolic name addrsize. addrsize represents the size of a machine word capable of holding a memory address. The link-editor substitutes the value 4 for addrsize when building 32-bit objects, and the value 8 when building 64-bit objects. addrsize is useful for representing the size of pointer variables and C variables of type long, as it automatically adjusts for 32 and 64-bit objects without requiring the use of conditional input.
The size_value argument can be optionally suffixed with a count value, enclosed in square brackets. If count is present, size_value and count are multiplied together to obtain the final size value.
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.
Indicates the value attribute. This attribute results in the creation of a symbol definition.