Symbol Sort Sections (Linker and Libraries Guide)

Linker and Libraries Guide

Symbol Sort Sections

The dynamic symbol table formed by the adjacent .SUNW_ldynsym section and .dynsym section can be used to map memory addresses to their corresponding symbol. This mapping can be used to determine which function or variable that a given address represents. However, analyzing the symbol tables to determine a mapping is complicated by the order in which symbols are written to symbol tables. See Symbol Table Layout and Conventions. This layout complicates associating an address to a symbol name in the follows ways.

Symbols are not sorted by address, which forces an expensive linear search of the entire table.
More than one symbol can refer to a given address. Although these symbols are valid and correct, the choice of which of these equivalent names to use by a debugging tool might not be obvious. Different tools might use different alternative names. These issues are likely to lead to user confusion.
Many symbols provide non-address information. These symbols should not be considered as part of such a search.

Symbol sort sections are used to solve these problems. A symbol sort section is an array of Elf32_Word or Elf64_Word objects. Each element of this array is an index into the combined .SUNW_ldynsym – .dynsym symbol table. The elements of the array are sorted so that the symbols that are reference are provided in sorted order. Only symbols representing functions or variables are included. The symbols that are associated with a sort array can be displayed using elfdump(1) with the -S option.

Regular symbols and thread-local storage symbols can not be sorted together. The value of a regular symbol is the address of the function or the address of the variable the symbol references. The value of a thread-local storage symbol is the variable's thread offset. Therefore, regular symbols and thread-local storage symbols use two different sort sections.

.SUNW_dynsymsort: A section of type SHT_SUNW_SYMSORT, containing indexes to regular symbols in the combined .SUNW_ldynsym – .dynsym symbol table, sorted by address. Symbols that do not represent variables or functions are not included.
.SUNW_dyntlssort: A section of type SHT_SUNW_TLSSORT, containing indexes to TLS symbols in the combined .SUNW_ldynsym – .dynsym symbol table, sorted by offset. This section is only produced if the object file contains TLS symbols.

The link-editor uses the following rules, in the order that is shown, to select which symbols are referenced by the sort sections.

The symbol must have a function or variable type: STT_FUNC, STT_OBJECT, STT_COMMON, or STT_TLS.
The following symbols are always included, if present: _DYNAMIC, _end, _fini, _GLOBAL_OFFSET_TABLE_, _init, _PROCEDURE_LINKAGE_TABLE_, and _start.
If a global symbol and a weak symbol are found to reference the same item, the weak symbol is included and the global symbol is excluded.
The symbol must not be undefined.
The symbol must have a non-zero size.

These rules filter out automatically generated compiler and link-editor generated symbols. The symbols that are selected are of interest to the user. However, two cases exist where manual intervention might be necessary to improve the selection process.

The rules did not select a needed special symbol. For example, some special symbols have a zero size.
Unwanted extra symbols are selected. For example, shared objects can define multiple symbols that reference the same address and have the same size. These alias symbols effectively reference the same item. You might prefer to include only one of a multiple symbol family, within the sort section.

The mapfile keywords DYNSORT and NODYNSORT provide for additional control over symbol selection. See SYMBOL_SCOPE / SYMBOL_VERSION Directives.

DYNSORT: Identifies a symbol that should be included in a sort section. The symbol type must be STT_FUNC, STT_OBJECT, STT_COMMON, or STT_TLS.
NODYNSORT: Identifies a symbol that should not be included in a sort section.

For example, an object might provide the following symbol table definitions.

$ elfdump -sN.symtab foo.so.1 | egrep "foo$|bar$"
      [37]  0x000004b0 0x0000001c  FUNC GLOB  D   0 .text      bar
      [38]  0x000004b0 0x0000001c  FUNC WEAK  D   0 .text      foo

The symbols foo and bar represent an aliases pair. By default, when creating a sorted array, only the symbol foo is represented.

$ cc -o foo.so.1 -G foo.c
$ elfdump -S foo.so.1 | egrep "foo$|bar$"
      [13]  0x000004b0 0x0000001c  FUNC WEAK  D   0 .text      foo

In the case where a global and a weak symbol are found by the link-editor to reference the same item, the weak symbol is normally kept. The symbol bar is omitted from the sorted array because of the association to the weak symbol foo.

The following mapfile results in the symbol bar being represented in the sorted array. The symbol foo is omitted.

$ cat mapfile
{
    global:
        bar = DYNSORT;
        foo = NODYNSORT;
};
$ cc -M mapfile -o foo.so.2 -Kpic -G foo.c
$ elfdump -S foo.so.2 | egrep "foo$|bar$"
      [13]  0x000004b0 0x0000001c  FUNC GLOB  D   0 .text      bar

The .SUNW_dynsymsort section and .SUNW_dyntlssort section, require that a .SUNW_ldynsym section be present. Therefore, use of the -z noldynsym option also prevents the creation of any sort section.