JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris 11.1 Linkers and Libraries Guide     Oracle Solaris 11.1 Information Library
search filter icon
search icon

Document Information

Preface

Part I Using the Link-Editor and Runtime Linker

1.  Introduction to the Oracle Solaris Link Editors

2.  Link-Editor

3.  Runtime Linker

4.  Shared Objects

Part II Quick Reference

5.  Link-Editor Quick Reference

Part III Advanced Topics

6.  Direct Bindings

7.  Building Objects to Optimize System Performance

8.  Mapfiles

Mapfile Structure and Syntax

Mapfile Version

Conditional Input

Directive Syntax

Mapfile Directives

CAPABILITY Directive

HW Attribute

HW_1 / HW_2 Attributes

MACHINE Attribute

PLATFORM Attribute

SF Attribute

SF_1 Attribute

DEPEND_VERSIONS Directive

ALLOW Attribute

REQUIRE Attribute

HDR_NOALLOC Directive

PHDR_ADD_NULL Directive

LOAD_SEGMENT / NOTE_SEGMENT / NULL_SEGMENT Directives

ALIGN Attribute (LOAD_SEGMENT only)

ASSIGN_SECTION Attribute

DISABLE Attribute

FLAGS Attribute (LOAD_SEGMENT only)

IS_ORDER Attribute

MAX_SIZE Attribute (LOAD_SEGMENT only)

NOHDR Attribute (LOAD_SEGMENT only)

OS_ORDER Attribute

PADDR Attribute (LOAD_SEGMENT only)

ROUND Attribute (LOAD_SEGMENT only)

SIZE_SYMBOL Attribute (LOAD_SEGMENT only)

VADDR (LOAD_SEGMENT only)

SEGMENT_ORDER Directive

STACK Directive

STUB_OBJECT Directive

SYMBOL_SCOPE / SYMBOL_VERSION Directives

ASSERT Attribute

AUXILIARY Attribute

FILTER Attribute

FLAGS Attribute

SIZE Attribute

TYPE Attribute

VALUE Attribute

Predefined Segments

Mapping Examples

Example: Section to Segment Assignment

Example: Predefined Section Modification

Link-Editor Internals: Section and Segment Processing

Section To Segment Assignment

Mapfile Directives for Predefined Segments and Entrance Criteria

9.  Interfaces and Versioning

10.  Establishing Dependencies with Dynamic String Tokens

11.  Extensibility Mechanisms

Part IV ELF Application Binary Interface

12.  Object File Format

13.  Program Loading and Dynamic Linking

14.  Thread-Local Storage

Part V Appendices

A.  Linker and Libraries Updates and New Features

B.  System V Release 4 (Version 1) Mapfiles

Index

Mapfile Structure and Syntax

Mapfile directives can span more than one line, and can have any amount of white space, including new lines.

For all syntax discussions, the following notations apply.

Table 8-1 Double Quoted Text Escape Sequences

Escape Sequence
Meaning
\a
alert (bell)
\b
backspace
\f
formfeed
\n
newline
\r
return
\t
horizontal tab
\v
vertical tab
\\
backslash
\'
single quote
\”
double quote
\ooo
An octal constant, where ooo is one to three octal digits (0...7)

Table 8-2 Names And Other Widely Used Strings Found In Mapfiles

Name
Purpose
segment_name
Name of ELF segment
section_name
Name of ELF section
symbol_name
Name of ELF symbol
file_path
A Unix file path of slash (/) delimited names used to reference an ELF object, or an archive that contains ELF objects
file_basename
Final component (basename(1)) of a file_path
objname
Either a file_basename or the name of an object contained within an archive
soname
Sharable object name, as used for the SONAME of a sharable object (e.g. libc.so.1)
version_name
Name of a symbol version, as used within an ELF versioning section
inherited_version_name
Name of a symbol version inherited by another symbol version

Table 8-3 Segment Flags

Flag Value
Meaning
READ
Segment is readable
WRITE
Segment is writable
EXECUTE
Segment is executable
0
All permission flags are cleared
DATA
The combination of READ, WRITE, and EXECUTE flags appropriate for a data segment on the target platform
STACK
The combination of READ, WRITE, and EXECUTE flags appropriate for the target platform, as defined by the platform ABI

Mapfile Version

The first non-comment, non-empty, line in a mapfile is expected to be a mapfile version declaration. This declaration establishes the version of the mapfile language used by the remainder of the file. The mapfile language documented in this manual is version 2.

        $mapfile_version 2

A mapfile that does not begin with a version declaration is assumed to be written in the original mapfile language defined for System V Release 4 Unix (SVR4) by AT&T. The link-editor retains the ability to process such mapfiles. Their syntax is documented in Appendix B, System V Release 4 (Version 1) Mapfiles.

Conditional Input

Lines within a mapfile can be conditionalized to only apply to a specific ELFCLASS (32 or 64-bit) or machine type.

        $if expr
        ...
        [$elif expr]
        ...
        [$else]
        ...
        $endif

A conditional input expression evaluates to a logical true or false value. Each of the directives ($if, $elif, $else, and $endif) appear alone on a line. The expressions in $if and subsequent $elif lines are evaluated in order until an expression that evaluates to true is found. Text following a line with a false value is discarded. The text following a successful directive line is treated normally. Text here refers to any material, that is not part of the conditional structure. Once a successful $if or $elif has been found, and its text processed, succeeding $elif and $else lines, together with their text, are discarded. If all the expressions are zero, and there is a $else, the text following the $else is treated normally.

The scope of an $if directive cannot extend across multiple mapfiles. An $if directive must be terminated by a matching $endif within the mapfile that uses the $if directive, or the link-editor issues an error.

The link-editor maintains an internal table of names that can be used in the logical expressions evaluated by $if and $elif. At startup, this table is initialized with each of the names in the following table that apply to the output object being created.

Table 8-4 Predefined Conditional Expression Names

Name
Meaning
_ELF32
32–bit object
_ELF64
64–bit object
_ET_DYN
shared object
_ET_EXEC
executable object
_ET_REL
relocatable object
_sparc
Sparc machine (32 or 64–bit)
_x86
x86 machine (32 or 64–bit)
true
Always defined

The names are case sensitive, and must be used exactly as shown. For example, true is defined, but TRUE is not. Any of these names can be used by themselves as a logical expression. For example.

        $if _ELF64
        ...
        $endif

This example will evaluate to true, and allow the link-editor to process the enclosed text, when the output object is 64-bit. Although numeric values are not allowed in these logical expressions, a special exception is made for the value 1, which evaluates to true, and 0 for false.

Any undefined name evaluates to false. It is common to use the undefined name false to mark lines of input that should be unconditionally skipped.

        $if false
        ...
        $endif

More complex logical expressions can be written, using the operators shown in the following table

Table 8-5 Conditional Expression Operators

Operator
Meaning
&&
Logical AND
||
Logical OR
( expr )
Sub-expression
!
Negate boolean value of following expression

Expressions are evaluated from left to right. Sub-expressions are evaluated before enclosing expressions.

For example, the lines in the following construct will be evaluated when building 64-bit objects for x86 platforms.

        $if _ELF64 && _x86
        ...
        $endif

The $add directive can be used to add a new name to the link-editor's table of known names. Using the previous example, it might be convenient to define the name amd64 to stand for 64-bit x86 objects, in order to simplify $if directives.

        $if _ELF64 && _x86
        $add amd64
        $endif

This can be used to simplify the previous example.

        $if amd64
        ...
        $endif

New names can also be added to the link-editor's table of known names by using the link-editor's -z mapfile-add option. This option is useful when mapfile input needs to be conditionally enabled based on an attribute of the external environment, such as the compiler being used.

The $clear directive is the reverse of the $add directive. It is used to remove names from the internal table.

        $clear amd64

The effect of the $add directive persists beyond the end of the mapfile that uses $add, and is visible to any subsequent mapfile that is processed by the link-editor in the same link operation. If this is not desired, use $clear at the end of the mapfile containing the $add to remove the definition.

Finally, the $error directive causes the link-editor to print all remaining text on the line as a fatal error, and halt the link operation. The $error directive can be used to ensure that a programmer porting an object to a new machine type will not be able to silently build an incorrect object that is missing a necessary mapfile definition.

        $if _sparc
        ...
        $elif _x86
        ...
        $else
        $error unknown machine type
        $endif

C language programmers will recognize that the syntax used for mapfile conditional input resembles that of the C preprocessor macro language. This similarity is intentional. However, mapfile conditional input directives are by design considerably less powerful than those provided by the C preprocessor. They provide only the most basic facilities required to support linking operations in a cross platform environment.

Among the significant differences between the two languages.

Those requiring more sophisticated macro processing should consider using an external macro processor, such as m4(1).

Directive Syntax

Mapfile directives exist to specify many aspects of the output object. These directives share a common syntax, using name value pairs for attributes, and {...} constructs to represent hierarchy and grouping.

The syntax of mapfile directives is based on the following generic forms.

The simplest form is a directive name without a value.

        directive;

The next form is a directive name with a value, or a white space separated list of values.

        directive = value...;

In addition to the “=” assignment operator shown, the “+=” and “-=” forms of assignment are allowed. The “=” operator sets the given directive to the given value, or value list. The “+=” operator is used to add the value on the right hand side to the current value, and the “-=” operator is used to remove values.

More complex directives manipulate items that take multiple attributes enclosed within {...} brackets to group the attributes together as a unit.

        directive [name] {
                attribute [directive = value];
                ...
        } [name];

There can be a name before the opening brace ({), which is used to name the result of the given statement. Similarly, one or more optional names can follow the closing brace (}), prior to the terminating semicolon (;). These names are used to express that the defined item has a relationship with other named items.

Note that the format for attributes within a grouping use the same syntax described above for simple directives with a value, with an assignment operator (=, +=, -=) followed by a value, or white space separated list of values, terminated with a semicolon (;).

A directive can have attributes that in turn have sub-attributes. In such cases, the sub-attributes are also grouped within nested {...} brackets to reflect this hierarchy.

        directive [name] {
                attribute {
                        subatribute [= value];
                        ...
                };
        } [name...];

The mapfile syntax grammar puts no limit on the depth to which such nesting is allowed. The depth of nesting depends solely on the requirements of the directive.