test

Linker and Libraries Guide

Chapter 9 Mapfiles

Mapfiles provide a large degree of control over the operation of the link-editor, and the resulting output object.

Note –

The link-editor used without a mapfile will always produce a valid ELF output file. The mapfile option provides the user with a great deal of flexibility and control over the output object, some of which has the potential to produce an invalid or unusable object. The user is expected to have knowledge of the rules and conventions that govern the ELF format.

The -M command line option is used to specify the mapfile to be used. Multiple mapfiles can be used in a single link operation. When more than one mapfile is specified, the link-editor processes each one in the order given, as if they represented a single logical mapfile. This occurs before any input objects are processed.

The system provides sample mapfiles for solving common problems in the /usr/lib/ld directory.

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 9–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 9–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 9–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 E, 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 9–4 Predefined Conditional Expression Names

Name 

Meaning 

_ELF32

32–bit object 

_ELF64

64–bit 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 9–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

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.

Mapfile Directives

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 following directives are accepted by the link-editor.

Table 9–6 Mapfile Directives

Directive 

Purpose 

CAPABILITY

Hardware, software, machine, and platform capabilities 

DEPEND_VERSIONS

Specify allowed versions from sharable object dependencies 

HDR_NOALLOC

ELF header and program headers are not allocable 

LOAD_SEGMENT

Create new loadable segment, or modify an existing load segment 

NOTE_SEGMENT

Create note segment, or modify an existing note segment 

NULL_SEGMENT

Create null segment, or modify an existing null segment 

PHDR_ADD_NULL

Add Null Program Header Entries 

SEGMENT_ORDER

Specify the order of segments in the output object and program header array 

STACK

Process Stack Attributes 

SYMBOL_SCOPE

Set symbol attributes and scope within the unnamed global version 

SYMBOL_VERSION

Set symbol attributes and scope within an explicitly named version 

The specific syntax for each supported mapfile directive is shown in the sections that follow.

CAPABILITY Directive

The hardware, software, machine, and platform capabilities of a relocatable object are typically recorded within an object at compile time. The link-editor combines the capabilities of any input relocatable objects to create a final capabilities section for the output file. Capabilities can be defined within a mapfile, to augment, or completely replace, the capabilities that are supplied from input relocatable objects.

        CAPABILITY [capid] {
                HW  = [hwcap_flag...];
                HW += [hwcap_flag...];
                HW -= [hwcap_flag...];
 
                HW_1  = [value...];
                HW_1 += [value...];
                HW_1 -= [value...];
 
                HW_2  = [value...];
                HW_2 += [value...];
                HW_2 -= [value...];
 
                MACHINE  = [machine_name...];
                MACHINE += [machine_name...];
                MACHINE -= [machine_name...];
 
                PLATFORM  = [platform_name...];
                PLATFORM += [platform_name...];
                PLATFORM -= [platform_name...];
 
                SF  = [sfcap_flag...];
                SF += [sfcap_flag...];
                SF -= [sfcap_flag...];
 
                SF_1  = [value...];
                SF_1 += [value...];
                SF_1 -= [value...];
        };

If present, the optional capid name provides a symbolic name for the object capabilities, resulting in a CA_SUNW_ID capability entry in the output object. If multiple CAPABILITY directives are seen, the capid provided by the final directive is used.

An empty CAPABILITY directive can be used to specify a capid for the object capabilities without specifying any capability values.

        CAPABILITY capid;

For each type of capability, the link-editor maintains a current value (value), and a set of values to be excluded (exclude). For hardware and software capabilities, these values are bitmasks. For machine and platform capabilities, they are lists of names. Prior to processing mapfiles, the value and exclude values for all capabilities are cleared. The assignment operators work as follows.

Input objects are processed after mapfiles have been read. Capability values specified by the input objects are merged with those from the mapfiles, unless the “=” operator was used, in which case that capability is ignored when encountered in an input object. Hence, the “=” operator overrides the input objects, whereas the “+=” operator is used to augment them.

Prior to writing the resulting capability value to the output object, the link-editor subtracts any capability values specified with the “-=” operator.

To completely eliminate a given capability from the output object, it suffices to use the “=” operator and an empty value list. For example, the following suppresses any hardware capabilities contributed by the input objects:

        $mapfile_version 2
        CAPABILITY {
                HW = ;
        };

Within an ELF object, hardware and software capabilities are represented as bit assignments within one or more bitmasks found in the capabilities section of the object. The HW and SF mapfile attributes provide a more abstract view of this implementation, accepting a space separated list of symbolic capability names that the link-editor translates to the appropriate mask and bit. The numbered attributes (HW_1, HW_2, SF_1) exist in order to allow direct numeric access to the underlying capability bitmasks. They can be used to specify capability bits that have not been officially defined. Where possible, use of the HW and SF attributes is recommended.

HW Attribute

Hardware capabilities are specified as a space separated list of symbolic capability names. For SPARC platforms, hardware capabilities are defined as AV_ values in <sys/auxv_SPARC.h>. For x86 platforms, hardware capabilities are defined as AV_ values in <sys/auxv_386.h>. Mapfiles use the same names, without the AV_ prefix. For example, the x86 AV_SSE hardware capability is called SSE within a mapfile. This list can contain any of the capability names defined for the CA_SUNW_HW_ capability masks.

HW_1 / HW_2 Attributes

The HW_1 and HW_2 attributes allow the CA_SUNW_HW_1 and CA_SUNW_HW_2 capability masks to be specified directly as numeric values, or as the symbolic hardware capability names that correspond to that mask.

MACHINE Attribute

The MACHINE attribute specifies the machine hardware names for the systems that the object can execute upon. The machine hardware name of a system can be displayed by the utility uname(1) with the -m option. A CAPABILITY directive can specify multiple machine names. Each name results in a CA_SUNW_MACH capability entry in the output object.

PLATFORM Attribute

The PLATFORM attribute specifies the platform names for the systems that the object can execute upon. The platform name of a system can be displayed by the utility uname(1) with the -i option. A CAPABILITY directive can specify multiple platform names. Each name results in a CA_SUNW_PLAT capability entry in the output object.

SF Attribute

Software capabilities are specified as a space separated list of symbolic capability names. Software capabilities are defined as SF1_SUNW_ values in <sys/elf.h>. Mapfiles use the same names, without the SF1_SUNW_ prefix. For example, the SF1_SUNW_ADDR32 software capability is called ADDR32 in a mapfile. This list can contain any of the capability names defined for the CA_SUNW_SF_1.

SF_1 Attribute

The SF_1 attribute allows the CA_SUNW_SF_1 capability mask to be specified directly as a numeric value, or as symbolic software capability names that correspond to that mask.

DEPEND_VERSIONS Directive

When linking against a sharable object, the symbols from all versions exported by the object are normally available for use by the link-editor. The DEPEND_VERSIONS directive is used to limit access to specified versions only. Restricting version access can be used to ensure that a given output object does not use newer features that might not be available on an older version of the system.

A DEPEND_VERSIONS directive has the following syntax.

        DEPEND_VERSIONS objname {
                ALLOW = version_name;
                REQUIRE = version_name;
                ...
        };

objname is the name of the sharable object, as specified on the command line. In the common case where the object is specified using the -l command line option, this will be the specified name with a lib prefix. For instance, libc is commonly referenced as -lc on the command line, and is therefore specified as libc.so in a DEPEND_VERSIONS directive.

ALLOW Attribute

The ALLOW attribute specifies that the specified version, and versions inherited by that version, are available to the link-editor for resolving symbols in the output object. The link-editor will add a requirement for the highest version used in the inheritance chain containing this version to the output object requirements.

REQUIRE Attribute

REQUIRE adds the specified version to the output object requirements, whether or not the version is actually required to satisfy the link operation.

HDR_NOALLOC Directive

Every ELF object has an ELF header at offset 0 in the file. Executable and sharable objects also contain program headers, which are accessed through the ELF header. The link-editor normally arranges for these items to be included as part of the first loadable segment. The information contained in these headers is therefore visible within the mapped image, and is typically used by the runtime linker. The HDR_NOALLOC directive prevents this.

        HDR_NOALLOC;

When HDR_NOALLOC is specified, the ELF header and program header array still appear at the start of the resulting output object file, but are not contained in a loadable segment, and virtual address calculations for the image start at the first section of the first segment rather than at the base of the ELF header.

PHDR_ADD_NULL Directive

The PHDR_ADD_NULL directive causes the link-editor to add a specified number of additional program header entries of type PT_NULL at the end of the program header array. Extra PT_NULL entries can be used by post processing utilities.

        PHDR_ADD_NULL = value;

value must be a positive integer value, and gives the number of extra PT_NULL entries to create. All fields of the resulting program header entries will be set to 0.

LOAD_SEGMENT / NOTE_SEGMENT / NULL_SEGMENT Directives

A segment is a contiguous portion of the output object that contains sections. The mapfile segment directives allow the specification of three different segment types.

Segment directives are used to create new segments in the output file, or to change the attribute values of an existing segment. An existing segment is one that was previous defined, or one of the built-in segments discussed in Predefined Segments. Each new segment is added to the object after the last such segment of the same type. Loadable segments are added first, then note segments, and finally null segments. Any program headers associated with these segments are placed in the program header array in the same relative order as the segments themselves. This default placement can be altered by setting an explicit address in the case of a loadable segment, or using the SEGMENT_ORDER directive.

If segment_name is a preexisting segment, then the attributes specified modify the existing segment. Otherwise, a new segment is created and the specified attributes are applied to the new segment. The link-editor fills in default values for attributes not explicitly supplied.

Note –

When selecting a segment name, bear in mind that a future version of the link-editor might add new predefined segments. If the name used in your segment directive matches this new name, the new predefined segment will alter the meaning of your mapfile, from creating a new segment to modifying an existing one. The best way to prevent this situation is to avoid generic names for segments, and give all of your segment names a unique prefix, such as a company/project identifier, or even the name of the program. For example, a program named hello_world might use the segment name hello_world_data_segment.

All three segment directives share a common set of core attributes. Substituting one of LOAD_SEGMENT, NOTE_SEGMENT, NULL_SEGMENT for directive, a segment declaration is as follows.

        
directive segment_name {
                ASSIGN_SECTION [assign_name];
                ASSIGN_SECTION [assign_name] {
                        FILE_BASENAME = file_basename;
                        FILE_OBJNAME = objname;
                        FILE_PATH = file_path;
                        FLAGS = section_flags;
                        IS_NAME = section_name;
                        TYPE = section_type;
                };

                DISABLE;

                IS_ORDER  = assign_name...;
                IS_ORDER += assign_name...;

                OS_ORDER  = section_name...;
                OS_ORDER += section_name...;
};

The LOAD_SEGMENT directive accepts an additional set of attributes specific to loadable segments. The syntax of these additional attributes is as follows.

        LOAD_SEGMENT segment_name {
                ALIGN = value;

                FLAGS  = segment_flags;
                FLAGS += segment_flags;
                FLAGS -= segment_flags;

                MAX_SIZE = value;

                NOHDR;

                PADDR = value;
                ROUND = value;

                SIZE_SYMBOL  = symbol_name...;
                SIZE_SYMBOL += symbol_name...;

                VADDR = value;
};

Any of the segment directives can be specified as an empty directive. When an empty segment directive creates a new segment, default values are established for all segment attributes. Empty segments are declared as follows.

        LOAD_SEGMENT segment_name;

        NOTE_SEGMENT segment_name;

        NULL_SEGMENT segment_name;

All of the attributes accepted by one or more of the segment directives are described below.

ALIGN Attribute (LOAD_SEGMENT only)

The ALIGN attribute is used to specify the alignment for a loadable segment. The value specified is set in the p_align field of the program header corresponding to the segment. Segment alignment is used in calculating the virtual address of the beginning of the segment.

The alignment specified must be a power of 2. By default, the link-editor sets the alignment of a segment to the built-in default. This default differs from one CPU to another and might even be different between software revisions.

The ALIGN attribute is mutually exclusive to the PADDR and VADDR attributes, and cannot be used with them. When PADDR or VADDR is specified, the p_align field of the corresponding program header will be set to the default value.

ASSIGN_SECTION Attribute

ASSIGN_SECTION specifies a combination of section attributes, such as section name, type, and flags, that collectively qualify a section for assignment to a given segment. Each such set of attributes is called an entrance criterion. A section matches when the section attributes match those of an entrance criterion exactly. An ASSIGN_SECTION that does not specify any attributes matches any section that criterion is compared to.

Multiple ASSIGN_SECTION attributes are allowed for a given segment. Each ASSIGN_SECTION attribute is independent of the others. A section will be assigned to a segment if the section matches any one of the ASSIGN_SECTION definitions associated with that segment. The link-editor will not assign sections to a segment unless the segment has at least one ASSIGN_SECTION attribute.

The link-editor uses an internal list of entrance criteria to assign sections to segments. Each ASSIGN_SECTION declaration encountered in the mapfile is placed on this list, in the order encountered. The entrance criteria for the built-in segments discussed in Predefined Segments are placed on this list immediately following the final mapfile defined entry.

The entrance criterion can be given an optional name (assign_name). This name can be used in conjunction with the IS_ORDER attribute to specify the order in which input sections are placed in the output section.

To place an input section, the link-editor starts at the head of the entrance criteria list, and compares the attributes of the section to each entrance criterion in turn. The section is assigned to the segment associated with the first entrance criterion that matches the section attributes exactly. If there is no match, the section is placed at the end of the file, as is generally the case for all non-allocable sections.

ASSIGN_SECTION accepts the following.

Table 9–7 Section FLAGS Values

Flag Value 

Meaning 

ALLOC

Section is allocable 

WRITE

Section is writable 

EXECUTE

Section is executable 

AMD64_LARGE

Section can be larger than 2GB 

DISABLE Attribute

The DISABLE attribute causes the link-editor to ignore the segment. No sections will be assigned to a disabled segment. The segment is automatically re-enabled when referenced by a following segment directive. Hence, an empty reference suffices to re-enable a disabled section.

segment segment_name;

FLAGS Attribute (LOAD_SEGMENT only)

The FLAGS attribute specifies segment permissions as a space separated list of the permissions in Table 9–3. By default, user defined segments receive READ, WRITE, and EXECUTE permissions. The default flags for the predefined segments described in Predefined Segments are supplied by the link-editor, and in some cases can be platform-dependent.

There are three forms allowed.

        FLAGS  = segment_flags...;
        FLAGS += segment_flags...;
        FLAGS -= segment_flags...;

The simple “=” assignment operator replaces the current flags with the new set, the “+=” form adds the new flags to the existing set, and the “-=” form removes the specified flags from the existing set.

IS_ORDER Attribute

The link-editor normally places output sections into the segment in the order they are encountered. Similarly, the input sections that make up the output section are placed in the order they are encountered. The IS_ORDER attribute can be used to alter this default placement of input sections. IS_ORDER specifies a space separated list of entrance criterion names (assign_name). Sections matched by one of these entrance criteria are placed at the head of the output section, sorted in the order given by IS_ORDER. Sections matched by entrance criteria not found in the IS_ORDER list are placed following the sorted sections, in the order they are encountered.

When the “=” form of assignment is used, the previous value of IS_ORDER for the given segment is discarded, and replaced with the new list. The “+=” form of IS_ORDER concatenates the new list to the end of the existing list.

The IS_ORDER attribute is of particular interest when used in conjunction with the -xF option to the compilers. When a file is compiled with the -xF option, each function in that file is placed in a separate section with the same attributes as the text section. These sections are called .text%function_name.

For example, a file containing three functions, main(), foo() and bar(), when compiled with the -xF option, yields a relocatable object file with text for the three functions being placed in sections called .text%main, .text%foo, and .text%bar. When the link-editor places these sections into the output, the % and anything following the % are removed. Hence, all three of these functions will be placed in the .text output section. The IS_ORDER attribute can be used to force them to be placed in a specific order within the .text output section relative to each other.

Consider the following user-defined mapfile.

        $mapfile_version 2
                LOAD_SEGMENT text {
                ASSIGN_SECTION text_bar  { IS_NAME = .text%bar };
                ASSIGN_SECTION text_main { IS_NAME = .text%main };
                ASSIGN_SECTION text_foo  { IS_NAME = .text%foo };
                IS_ORDER = text_foo text_bar text_main;
        };

No matter the order in which these three functions are found in the source code, or encountered by the link-editor, their order in the output object text segment will be foo(), bar(), and main().

MAX_SIZE Attribute (LOAD_SEGMENT only)

By default, the link-editor will allow a segment to grow to the size required by the contents of the segment. The MAX_SIZE attribute can be used to specify a maximum size for the segment. If MAX_SIZE is set, the link-editor will generate an error if the segment grows beyond the specified size.

NOHDR Attribute (LOAD_SEGMENT only)

If a segment with the NOHDR attribute set becomes the first loadable segment in the output object, the ELF and program headers will not be included within the segment.

The NOHDR attribute differs from the top level HDR_NOALLOC directive in that HDR_NOALLOC is a per-segment value, and only has an effect if the segment becomes the first loadable segment. This feature exists primarily to provide feature parity with the older mapfiles. See Appendix E, System V Release 4 (Version 1) Mapfiles for more details.

The HDR_NOALLOC directive is recommended in preference to the segment NOHDR attribute.

OS_ORDER Attribute

The link-editor normally places output sections into the segment in the order they are encountered. The OS_ORDER attribute can be used to alter this default placement of output sections. OS_ORDER specifies a space separated list of output section names (section_name). The listed sections are placed at the head of the segment, sorted in the order given by OS_ORDER. Sections not listed in OS_ORDER are placed following the sorted sections, in the order they are encountered.

When the “=” form of assignment is used, the previous value of OS_ORDER for the given segment is discarded, and replaced with the new list. The “+=” form of OS_ORDER concatenates the new list to the end of the existing list.

PADDR Attribute (LOAD_SEGMENT only)

The PADDR attribute is used to specify an explicit physical address for the segment. The value specified is set in the p_addr field of the program header corresponding to the segment. By default, the link-editor sets the physical address of segments to 0, as this field has no meaning for user mode objects, and is primarily of interest non-userland objects such as operating system kernels.

ROUND Attribute (LOAD_SEGMENT only)

The ROUND attribute is used to specify that the size of the segment should be rounded up to the given value. The rounding value specified must be a power of 2. By default, the link-editor sets the rounding factor of a segment to 1, meaning that the segment size is not rounded up.

SIZE_SYMBOL Attribute (LOAD_SEGMENT only)

The SIZE_SYMBOL attribute defines a space separated list of section size symbol names to be created by the link-editor. A size symbol is a global-absolute symbol that represents the size, in bytes, of the segment. These symbols can be referenced in your object files. In order to access the symbol within your code, you should ensure that symbol_name is a legal identifier in that language. The symbol naming rules for the C programming language are recommended, as such symbols are likely to be accessible from any other language.

The “=” form of assignment can be used to establish an initial value, and can only be used once per link-editor session. The “+=” form of SIZE_SYMBOL concatenates the new list to the end of the existing list, and can be used as many times as desired.

VADDR (LOAD_SEGMENT only)

The VADDR attribute is used to specify an explicit virtual address for the segment. The value specified is set in the p_vaddr field of the program header corresponding to the segment. By default, the link-editor assigns virtual addresses to segments as the output file is created.

SEGMENT_ORDER Directive

The SEGMENT_ORDER directive is used to specify a non-default ordering for segments in the output object.

SEGMENT_ORDER accepts a space separated list of segment names.

        SEGMENT_ORDER  = segment_name...;
        SEGMENT_ORDER += segment_name...;

When the “=” form of assignment is used, the previous segment order list is discarded, and replaced with the new list. The “+=” form of assignment concatenates the new list to the end of the existing list.

By default, the link-editor orders segments as follows.

  1. Loadable segments with explicit addresses set with the VADDR attribute of the LOAD_SEGMENT directive, sorted by address.

  2. Segments ordered using the SEGMENT_ORDER directive, in the order specified.

  3. Loadable segments without explicit addresses, not found in the SEGMENT_ORDER list.

  4. Note segments without explicit addresses, not found in the SEGMENT_ORDER list.

  5. Null segments without explicit addresses, not found in the SEGMENT_ORDER list.

Note –

ELF has some implicit conventions that must be followed by a well formed object.

Mapfiles can be used to create objects that violate these requirements. This should be avoided, as the result of running such an object is undefined.

Unless the HDR_NOALLOC directive is specified, the link-editor enforces the requirement that the first segment must be a loadable segment, and not a note or null segment. HDR_NOALLOC cannot be used for userland objects, and is therefore of little practical use. This feature is used when building operating system kernels.

STACK Directive

The STACK directive specifies attributes of the process stack. 

        STACK {
                FLAGS  = segment_flags...;
                FLAGS += segment_flags...;
                FLAGS -= segment_flags...;
};

The FLAGS attribute specifies a white space separated list of segment permissions consisting of any of the values described in Table 9–3.

There are three forms allowed. The simple “=” assignment operator replaces the current flags with the new set, the “+=” form adds the new flags to the existing set, and the “-=” form removes the specified flags from the existing set.

The default stack permissions are defined by the platform ABI, and vary between platforms. The value for the target platform is specified using the segment flag name STACK.

On some platforms, the ABI mandated default permissions include EXECUTE. EXECUTE is rarely if ever needed and is generally considered to be a potential security risk. Removing EXECUTE permission from the stack is a recommended practice.

        STACK {
                FLAGS -= EXECUTE;
        };

The STACK directive is reflected in the output ELF object as a PT_SUNWSTACK program header entry.

SYMBOL_SCOPE / SYMBOL_VERSION Directives

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 {
                        AUXILIARY = soname;
                        FILTER = soname;
                        FLAGS = symbol_flags...;
                        SIZE = value;
                        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 5, Application Binary 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.

Table 9–8 Symbol Scope Types

Scope 

Meaning 

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.

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.

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.

exported

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 symbol visibility can not be demoted, or eliminated by any other symbol visibility technique. This scope definition has the same affect as a symbol with STV_EXPORTED visibility. See Table 7–20.

singleton

Global symbols of this scope are visible to all external objects. References to such symbols from within the object are bound at runtime, and ensure that only one instance of the symbol is bound to from all references within a process. This symbol visibility can not be demoted, or eliminated by any other symbol visibility technique. This scope definition has the same affect as a symbol with STV_SINGLETON visibility. See Table 7–20.

eliminate

Global symbols of this scope are hidden. Their symbol table entries are eliminated. This scope definition has the same affect as a symbol with STV_ELIMINATE visibility. See Table 7–20. Note that local symbols can also be eliminated by using the link-editor -z redlocsym option.

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 5, Application Binary Interfaces and Versioning.

Note –

To ensure interface definition stability, no wildcard expansion is provided for defining symbol names.

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.

AUXILIARY Attribute

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

FILTER Attribute

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.

FLAGS Attribute

symbol_flags specify symbol attributes as a space separated list of one or more of the following values.

Table 9–9 Symbol FLAG Values

Flag 

Meaning 

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

DYNSORT

Indicates that this symbol should be included in a sort section. See Symbol Sort Sections. The symbol type must be STT_FUNC, STT_OBJECT, STT_COMMON, or STT_TLS.

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

INTERPOSE

Indicates that this symbol acts an interposer. This flag can only be used when generating a dynamic executable. This flag provides for finer control of defining interposing symbols than is possible by using the -z interpose option.

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

NODYNSORT

Indicates that this symbol should not be included in a sort section. See Symbol Sort Sections.

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

SIZE Attribute

Sets the size attribute. This attribute results in the creation of a symbol definition.

TYPE Attribute

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.

VALUE Attribute

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

Predefined Segments

The link-editor provides a predefined set of output segment descriptors and entrance criteria. These definitions satisfy the needs of most linking scenarios, and comply with the ELF layout rules and conventions expected by the system.

The text, data, and extra segments are of primary interest, while the others serve more specialized purposes, as described below.

Mapping Examples

The following are examples of user-defined mapfiles. The numbers on the left are included in the example for tutorial purposes. Only the information to the right of the numbers actually appears in the mapfile.

Example: Section to Segment Assignment

This example demonstrates how to define segments and assign input sections to them.

Example 9–1 Basic Section to Segment Assignment

        1    $mapfile_version 2
        2    LOAD_SEGMENT elephant {
        3            ASSIGN_SECTION {
        4                    IS_NAME=.data;
        5                    FILE_PATH=peanuts.o;
        6            };
        7            ASSIGN_SECTION {
        8                    IS_NAME=.data;
        9                    FILE_OBJNAME=popcorn.o;
       10           };
       11   };
       12
       13   LOAD_SEGMENT monkey {
       14           VADDR=0x80000000;
       15           MAX_SIZE=0x4000;
       16           ASSIGN_SECTION {
       17                   TYPE=progbits;
       18                   FLAGS=ALLOC EXECUTE;
       19           };
       20           ASSIGN_SECTION {
       21                   IS_NAME=.data
       22           };
       23   };
       24
       25   LOAD_SEGMENT donkey {
       26           FLAGS=READ EXECUTE;
       27           ALIGN=0x1000;
       28           ASSIGN_SECTION {
       29                   IS_NAME=.data;
       30           };
       31   };
       32
       33   LOAD_SEGMENT text {
       34           VADDR=0x80008000
       35   };

Four separate segments are manipulated in this example. Every mapfile starts with a $mapfile_version declaration as shown on line 1. Segment elephant (lines 2-11) receives all of the data sections from the files peanuts.o or popcorn.o. The object popcorn.o can come from an archive, in which case the archive file can have any name. Alternatively, popcorn.o can come from any file with a basename of popcorn.o. In contrast, peanuts.o can only come from a file with exactly that name. For example, the file /var/tmp/peanuts.o supplied to a link-edit does not match peanuts.o.

Segment monkey (lines 13-23) has a virtual address of 0x80000000, and a maximum length of 0x4000. This segment receives all sections that are both PROGBITS and allocable-executable, as well as all sections not already in the segment elephant with the name .data. The .data sections entering the monkey segment need not be PROGBITS or allocable-executable, because they match the entrance criterion on line 20 rather than the one on line 16. This illustrates that and and relationship exists between the sub-attributes within a ASSIGN_SECTION attribute, while an or relationship exists between the different ASSIGN_SECTION attributes for a single segment.

The donkey segment (lines 25-31) is given non-default permission flags and alignment, and will accept all sections named .data. However, this segment will never be assigned any sections, and as a result, segment donkey will never appear in the output object. The reason for this is that the link-editor examines entrance criteria in the order they appear in themapfile. In this mapfile, segment elephant accepts some .data sections, and segment takes any that are left, leaving none for donkey.

Lines 33-35 set the virtual address of the text segment to 0x80008000. The text segment is one of the standard predefined segments, as described in Predefined Segments, so this statement modifies the existing segment rather than creating a new one.

Example: Predefined Section Modification

The following mapfile example manipulates the predefined text and data segments, header options and section within segment ordering.

Example 9–2 Predefined Section Manipulation and Section to Segment Assignment

        1    $mapfile_version 2
        2    HDR_NOALLOC;
        3
        4    LOAD_SEGMENT text {
        5            VADDR=0xf0004000;
        6            FLAGS=READ EXECUTE;
        7            OS_ORDER=.text .rodata;
        9            ASSIGN_SECTION {
       10                   TYPE=PROGBITS;
       11                   FLAGS=ALLOC !WRITE;
       12           };
       13   };
       14
       15   LOAD_SEGMENT data {
       16           FLAGS=READ WRITE EXECUTE;
       17           ALIGN=0x1000;
       18           ROUND=0x1000;
       19   };

As always, the first line declares the mapfile language version to be used. The HDR_NOALLOC directive (line 2) specifies that the resulting object should not include the ELF header or program header array within the first allocable segment in the object, which is the predefined text segment.

The segment directive on lines 4-13 set a virtual address and permission flags for the text segment. This directive also specifies that sections named .text sections should be placed at the head of the segment, followed by any sections named .rodata, and that all other sections will follow these. Finally, allocable, non-writable PROGBITS sections are assigned to the segment.

The segment directive on lines 15-19 specifies that the data segment must be aligned on a boundary of 0x1000. This has the effect of aligning the first section within the segment at the same alignment. The length of the segment is to be rounded up to a multiple of the same value as the alignment. The segment permissions are set to read, write, and execute.

Link-Editor Internals: Section and Segment Processing

The internal process used by the link-editor to assign sections to output segments is described here. This information is not necessary in order to use mapfiles. This information is primarily of interest to those interested in link-editor internals, and for those who want a deep understanding of how segment mapfile directives are interpreted and executed by the link-editor.

Section To Segment Assignment

The process of assigning input sections to output segments involves the following data structures.

For each section written to the output object, the link-editor performs the following steps to place the section in an output segment.

  1. The attributes of the section are compared to each record in the internal entrance criteria list, starting at the head of the list and considering each entrance criterion in turn. A match occurs when every attribute in the entrance criterion matches exactly, and the segment associated with the entrance criterion is not disabled. The search stops with the first entrance criterion that matches, and the section is directed to the associated segment.

    If no Entrance Criterion match is found, the section is placed at the end of the output file after all other segments. No program header entry is created for this information. Most non-allocable sections (e.g. debug sections) end up in this area.

  2. When the section falls into a segment, the link-editor checks the list of existing output sections in that segment as follows.

    If the section attribute values match those of an existing output section exactly, the section is placed at the end of the list of sections associated with that output section.

    If no matching output section is found, a new output section is created with the attributes of the section being placed, and the input section is placed within the new output section. This new output section is positioned within the segment following any other output sections with the same section type, or at the end of the segment if there are none.

    Note –

    If the input section has a user-defined section type value between SHT_LOUSER and SHT_HIUSER, the section is treated as a PROGBITS section. No method exists for naming this section type value in the mapfile, but these sections can be redirected using the other attribute value specifications (section flags, section name) in the entrance criterion.

Mapfile Directives for Predefined Segments and Entrance Criteria

The link-editor provides a predefined set of output segment descriptors and entrance criteria, as described in Predefined Segments. The link-editor already knows about these sections, so mapfile directives are not required to create them. The mapfile directives that could be used to produce them are shown for illustrative purposes, and as an example of a relatively complex mapfile specification. Mapfile segment directives can be used to modify or augment these built in definitions.

Normally, section to segment assignments are done within a single segment directive. However, the predefined sections have more complex requirements, requiring their entrance criteria to be processed in a different order than the segments are laid out in memory. Two passes are used to achieve this, the first to define all the segments in the desired order, and the second to establish entrance criteria in an order that will achieve the desired results. It is rare for a user mapfile to require this strategy.

        # Predefined segments and entrance criteria for the Oracle Solaris
        # link-editor
        $mapfile_version 2

        # The lrodata and ldata segments only apply to x86-64 objects.
        # Establish amd64 as a convenient token for conditional input
        $if _ELF64 && _x86
        $add amd64
        $endif

        # Pass 1: Define the segments and their attributes, but
        # defer the entrance criteria details to the 2nd pass.
        LOAD_SEGMENT text {
                FLAGS = READ EXECUTE;
        };
        LOAD_SEGMENT data {
                FLAGS = READ WRITE EXECUTE;
        };
        LOAD_SEGMENT bss {
                DISABLE;
                FLAGS=DATA;
        };
        $if amd64
                LOAD_SEGMENT lrodata {
                        FLAGS = READ
                };
                LOAD_SEGMENT ldata {
                        FLAGS = READ WRITE;
                };
        $endif
        NOTE_SEGMENT note;
        NULL_SEGMENT extra;

        # Pass 2: Define ASSIGN_SECTION attributes for the segments defined
	       # above, in the order the link-editor should evaluate them.

        # All SHT_NOTE sections go to the note segment
        NOTE_SEGMENT note {
                ASSIGN_SECTION {
                        TYPE = NOTE;
                };
        };
        $if amd64
                # Medium/large model x86-64 readonly sections to lrodata
                LOAD_SEGMENT lrodata {
                        ASSIGN_SECTION {
                                FLAGS = ALLOC AMD64_LARGE;
                        };
                };
        $endif

        # text receives all readonly allocable sections
        LOAD_SEGMENT text {
                ASSIGN_SECTION {
                        FLAGS = ALLOC !WRITE;
                };
        };

        # If bss is enabled, it takes the writable NOBITS sections
        # that would otherwise end up in ldata or data.
        LOAD_SEGMENT bss {
                DISABLE;
                ASSIGN_SECTION {
                        FLAGS = ALLOC WRITE;
                        TYPE = NOBITS;
                };
        };

        $if amd64
                # Medium/large model x86-64 writable sections to ldata
                LOAD_SEGMENT ldata {
                        ASSIGN_SECTION {
                                FLAGS = ALLOC WRITE AMD64_LARGE;
                        };
                        ASSIGN_SECTION {
                                TYPE = NOBITS;
                                FLAGS = AMD64_LARGE
                        };
                };
        $endif

        # Any writable allocable sections not taken above go to data
        LOAD_SEGMENT data {
                ASSIGN_SECTION {
                        FLAGS = ALLOC WRITE;
                };
        };

        # Any section that makes it to this point ends up at the
        # end of the object file in the extra segment. This accounts
        # for the bulk of non-allocable sections.
        NULL_SEGMENT extra {
                ASSIGN_SECTION;
        };