Linker and Libraries Guide

Defining Additional Symbols with a mapfile

An extensive set of global symbol definitions can be provided by using the link-editor's -M option and an associated mapfile. Symbol definition mapfile entries have the following syntax.


[ name ] {
      scope:
            symbol [ = [ type ] [ value ] [ size ] [ information ] ];
} [ dependency ];
name

A label for this set of symbol definitions, if present, identifies a version definition within the image. See Chapter 5, Application Binary Interfaces and Versioning.

scope

Indicates the visibility of the symbols' binding within the output file being generated. All symbols defined with a mapfile are treated as global in scope during the link-edit process. These symbols are resolved against any other global symbols of the same name that are obtained from any of the input files. The following definitions, and aliases, define a symbols' visibility in the object being created.

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.

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.

If an object is created with a single symbolic scope, all relocations within the object are bound to the object at link-edit. With this single scope, even reserved symbols are reduced to symbolic scope. See Generating the Output File for a list of reserved symbol names.

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.

eliminate

Global symbols of this scope are hidden. Their symbol table entries are eliminated. Note that local symbols can also be eliminated by using the link-editor -z redlocsym option.


Note –

The STV_ symbol visibility attributes, originate from symbol declarations that are embedded in source code that are processed by the compilers.


symbol

A symbol name. 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.

type

Indicates the symbol type attribute. This attribute can be either COMMON, data, or function. The COMMON attribute results in a tentative symbol definition. The data and function attributes 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 return, 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

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

size

Indicates the size attribute. This attribute takes the form of Snumber. This attribute results in the creation of a symbol definition.

information

This keyword provides additional information for the symbol.

AUXILIARY name

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

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 keyword results in a direct binding to the dependency that provides the definition. See Direct Bindings. This keyword can also be used with the PARENT keyword to establish a direct binding to any parent at runtime.

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 keyword.

This keyword 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.

FILTER name

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.

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 Direct Bindings. This keyword can also be used with the PARENT keyword to prevent a direct binding to any parent at runtime.

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 keyword is typically defined to label callback routines. This keyword can be used with the DIRECT or NODIRECT keywords 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 keyword.

This keyword 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.

dependency

Represents a version definition that is inherited by this definition. See Chapter 5, Application Binary Interfaces and Versioning.

If either a version definition or the auto-reduction directive is specified, 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.


The following sections presents several examples of using the mapfile syntax.