Linux Standard Base Core Specification, Generic Part | ||
---|---|---|
<<< Previous | Chapter 10. Object Format | Next >>> |
This chapter describes the Symbol Versioning mechanism. All ELF objects may provide or depend on versioned symbols. Symbol Versioning is implemented by 3 section types: SHT_GNU_versym, SHT_GNU_verdef, and SHT_GNU_verneed.
The prefix Elfxx in the following descriptions and code fragments stands for either "Elf32" or "Elf64", depending on the architecture.
Versions are described by strings. The structures that are used for symbol versions also contain a member that holds the ELF hashing values of the strings. This allows for more efficient processing.
The special section .gnu.version which has a section type of SHT_GNU_versym shall contain the Symbol Version Table. This section shall have the same number of entries as the Dynamic Symbol Table in the .dynsym section.
The .gnu.version section shall contain an array of elements of type Elfxx_Half. Each entry specifies the version defined for or required by the corresponding symbol in the Dynamic Symbol Table.
The values in the Symbol Version Table are specific to the object in which they
are located. These values are identifiers that are provided by the the
vna_other
member of the
Elfxx_Vernaux structure or the
vd_ndx
member of the
Elfxx_Verdef structure.
The values 0 and 1 are reserved.
0 | The symbol is local, not available outside the object. | |
1 | The symbol is defined in this object and is globally available. |
All other values are used to identify version strings located in one of the other Symbol Version sections. The value itself is not the version associated with the symbol. The string identified by the value defines the version of the symbol.
The special section .gnu.version_d which has a section type of SHT_GNU_verdef shall contain symbol version definitions. The number of entries in this section shall be contained in the DT_VERDEFNUM entry of the Dynamic Section .dynamic. The sh_link member of the section header (see figure 4-8 in the System V ABI) shall point to the section that contains the strings referenced by this section.
The section shall contain an array of Elfxx_Verdef structures, as described in Figure 10-1, optionally followed by an array of Elfxx_Verdaux structures, as defined in Figure 10-2.
typedef struct { Elfxx_Half vd_version; Elfxx_Half vd_flags; Elfxx_Half vd_ndx; Elfxx_Half vd_cnt; Elfxx_Word vd_hash; Elfxx_Word vd_aux; Elfxx_Word vd_next; } Elfxx_Verdef; |
Figure 10-1. Version Definition Entries
vd_version | Version revision. This field shall be set to 1. | |
vd_flags | Version information flag bitmask. | |
vd_ndx | Version index numeric value referencing the SHT_GNU_versym section. | |
vd_cnt | Number of associated verdaux array entries. | |
vd_hash | Version name hash value (ELF hash function). | |
vd_aux | Offset in bytes to a corresponding entry in an array of Elfxx_Verdaux structures as defined in Figure 10-2 | |
vd_next | Offset to the next verdef entry, in bytes. |
typedef struct { Elfxx_Word vda_name; Elfxx_Word vda_next; } Elfxx_Verdaux; |
Figure 10-2. Version Definition Auxiliary Entries
vda_name | Offset to the version or dependency name string in the section header, in bytes. | |
vda_next | Offset to the next verdaux entry, in bytes. |
The special section .gnu.version_r which has a section type of
SHT_GNU_verneed
shall contain required symbol version definitions. The number of entries in
this section shall be contained in the DT_VERNEEDNUM entry of the Dynamic
Section .dynamic.
The sh_link
member of the section header (see figure 4-8 in
System V ABI)
shall point to the section that contains the strings referenced by this section.
The section shall contain an array of Elfxx_Verneed structures, as described in Figure 10-3, optionally followed by an array of Elfxx_Vernaux structures, as defined in Figure 10-4.
typedef struct { Elfxx_Half vn_version; Elfxx_Half vn_cnt; Elfxx_Word vn_file; Elfxx_Word vn_aux; Elfxx_Word vn_next; } Elfxx_Verneed; |
Figure 10-3. Version Needed Entries
typedef struct { Elfxx_Word vna_hash; Elfxx_Half vna_flags; Elfxx_Half vna_other; Elfxx_Word vna_name; Elfxx_Word vna_next; } Elfxx_Vernaux; |
Figure 10-4. Version Needed Auxiliary Entries
When loading a sharable object the system shall analyze version definition data from the loaded object to assure that it meets the version requirements of the calling object. This step is referred to as definition testing. The dynamic loader shall retrieve the entries in the caller's Elfxx_Verneed array and attempt to find matching definition information in the loaded Elfxx_Verdef table.
Each object and dependency shall be tested in turn. If a symbol definition is missing and the vna_flags bit for VER_FLG_WEAK is not set, the loader shall return an error and exit. If the vna_flags bit for VER_FLG_WEAK is set in the Elfxx_Vernaux entry, and the loader shall issue a warning and continue operation.
When the versions referenced by undefined symbols in the loaded object are found, version availability is certified. The test completes without error and the object shall be made available.
When symbol versioning is used in an object, relocations extend definition testing beyond the simple match of symbol name strings: the version of the reference shall also equal the name of the definition.
The same index that is used in the symbol table can be referenced in the SHT_GNU_versym section, and the value of this index is then used to acquire name data. The corresponding requirement string is retrieved from the Elfxx_Verneed array, and likewise, the corresponding definition string from the Elfxx_Verdef table.
If the high order bit (bit number 15) of the version symbolis set, the object cannot be used and the static linker shall ignore the symbol's presence in the object.
When an object with a reference and an object with the definition are being linked, the following rules shall govern the result:
The object with the reference and the object with the definitions both use
versioning. All described matching is processed in this case. A fatal error
shall be triggered when no matching definition can be found in the object whose
name is the one referenced by the vn_name
element in the
Elfxx_Verneed entry.
The object with the reference does not use versioning, while the object with the definitions does. In this instance, only the definitions with index numbers 1 and 2 will be used in the reference match, the same identified by the static linker as the base definition. In cases where the static linker was not used, such as in calls to dlopen(), a version that does not have the base definition index shall be acceptable if it is the only version for which the symbol is defined.
The object with the reference uses versioning, but the object with the definitions specifies none. A matching symbol shall be accepted in this case. A fatal error shall be triggered if a corruption in the required symbols list obscures an outdated object file and causes a match on the object filename in the Elfxx_Verneed entry.
Neither the object with the reference nor the object with the definitions use versioning. The behavior in this instance shall default to pre-existing symbol rules.
<<< Previous | Home | Next >>> |
Exception Frames | Up | ABI note tag |