Go to main content

Oracle® Solaris 11.4 Linkers and Libraries Guide

Exit Print View

Updated: March 2019
 
 

Mapfile Directives

The following directives are accepted by the link-editor.

Table 6  Mapfile Directives
Directive
Purpose
CAPABILITY
Hardware, software, machine, and platform capabilities
DEPEND_VERSIONS
Specify allowed versions from sharable object dependencies
FILTER
Specify that object is a shared object filter
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
RESERVE_SEGMENT
Create memory reservation segment
SEGMENT_ORDER
Specify the order of segments in the output object and program header array
STACK
Process Stack Attributes
STUB_OBJECT
Specify that object can be built as a stub object
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.

  • If the "+=" operator is used, the value specified is added to the current value for that capability, and removed from the exclude values for that capability.

  • If the "-=" operator is used, the value specified is added to the exclude values for that capability, and removed from the current value for that capability.

  • If the "=" operator is used, the value specified replaces the previous value, and exclude is reset to 0. In addition, the use of "=" overrides any capabilities that are collected from input file processing.

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.

FILTER Directive

The FILTER directive can be used when building a shared object. The symbol table of this object acts as a filter to one or more shared objects, referred to as filtees. At runtime, filters are used to redirect symbol lookup from one object to another. Filters are frequently used to provide backward compatibility for existing executables when functionality is moved from one library to another. See Shared Objects as Filters.

FILTER {
        FILTEE = soname;
        TYPE = filter_type;
};

FILTER can only be used with shared objects. Multiple FILTER directives of a single type can be specified. If multiple FILTER directives are used, their values are merged such that the resulting object will act as a filter to all of the specified filtees.

FILTEE Attribute

The FILTEE attribute specifies the target shared object for the filter.

TYPE Attribute

The TYPE attribute defines the type of filter. The allowed filter types are as follows. If no TYPE attribute is specified, STANDARD is assumed.

STANDARD

A standard filter. See Generating Standard Filters

AUXILIARY

An auxiliary filter. See Generating Auxiliary Filters

WEAK

A weak standard filter. Weak filters are identical to standard filters at runtime. At link-edit time, if unused dependency processing is active, a weak filter symbol from a dependency can be ignored in favor of the same symbol from the target filtee. Weak filters are the preferred type when using filters to provide backward compatibility when code moves between libraries. See Generating Weak Filters.

HDR_NOALLOC Directive

Every ELF object has an ELF header at offset 0 in the file. Dynamic 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, NOTE, NULL, and RESERVE_SEGMENT Directives

A segment is a contiguous portion of the output object that contains sections, or a memory reservation within the process that uses the object. The family of mapfile segment directives are used to specify the segments for an object. The following directives are provided.

LOAD_SEGMENT Directive

A loadable segment contains code or data that is mapped into the address space of a process at runtime. The link-editor creates a PT_LOAD program header entry for each allocable segment, which is used by the runtime linker to locate and map the segment.

        LOAD_SEGMENT segment_name {
                ALIGN = value;

                ASSIGN_SECTION [assign_name];
                ASSIGN_SECTION [assign_name] {
                        FILE_BASENAME = file_basename;
                        FILE_BASENAME = MATCH(...);

                        FILE_OBJNAME = objname;
                        FILE_OBJNAME = MATCH(...);

                        FILE_PATH = file_path;
                        FILE_PATH = MATCH(...);

                        FLAGS = section_flags;
                        TYPE = section_type;

                        IS_NAME = section_name;
                        IS_NAME = MATCH(...);
                
                        OUTPUT_SECTION {
                                DISCARD;
                        
                                FLAGS = section_flags;
                                FLAGS += section_flags;
                                FLAGS -= section_flags;

                                NAME = section_name;
                                NAME = MATCHREF(...);

                                TYPE = section_type;
                        };
                };

                DISABLE;

                FLAGS  = segment_flags;
                FLAGS += segment_flags;
                FLAGS -= segment_flags;
    
                IS_ORDER  = assign_name....;
                IS_ORDER += assign_name....;

                MAX_SIZE = value;
                NOHDR;

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

                PADDR = value;
                ROUND = value;

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

                VADDR = value;
        };
NOTE_SEGMENT Directive

A note segment contains note sections. The link-editor creates a PT_NOTE program header entry that references the segment. Note segments are not allocable.

The syntax of the ASSIGN_SECTION attribute is identical to that of the LOAD_SEGMENT directive, and is not reproduced here in the interest of brevity.

        NOTE_SEGMENT segment_name {
                ASSIGN_SECTION [assign_name];
                ASSIGN_SECTION [assign_name] {
                        ...See LOAD_SEGMENT...
                };

                DISABLE;

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

                OS_ORDER  = section_name....;
                OS_ORDER += section_name....;
        };
NULL_SEGMENT Directive

A null segment holds sections that are included in the output object, but which are not available to the object at runtime. Common examples of such sections are the .symtab symbol table, and the various sections produced for the benefit of debuggers. No program header is created for a null segment.

The syntax of the ASSIGN_SECTION attribute is identical to that of the LOAD_SEGMENT directive, and is not reproduced here in the interest of brevity.

        NULL_SEGMENT segment_name {
                ASSIGN_SECTION [assign_name];
                ASSIGN_SECTION [assign_name] {
                        See LOAD_SEGMENT...
                };

                DISABLE;

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

                OS_ORDER  = section_name....;
                OS_ORDER += section_name....;
        };
RESERVE_SEGMENT Directive

A memory reservation provides the means to reserve a portion of a process address. Mapping operations are able to use the reserved memory by explicitly specifying a fixed address within the reserved range. However, the system will not otherwise choose to map objects and or other files within a reserved range. The TYPE attribute determines the type of memory reservation to be created.

        RESERVE_SEGMENT segment_name {
                ALIGN = value;
                PADDR = value;
                ROUND = value;
                SIZE = value;

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

                TYPE = reservation_type
                VADDR = value;
        };

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.

The LOAD_SEGMENT, NOTE_SEGMENT, and NULL_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;

The RESERVE_SEGMENT directive always requires the VADDR, and SIZE attributes to be specified, and so, cannot be empty.

All of the attributes accepted by one or more of the segment directives are described below. For each attribute, the name of the directives that accept it are shown in the section title, in parenthesis, with the _SEGMENT suffix omitted.

ALIGN Attribute (LOAD, RESERVE)

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 0 or 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 related to the PADDR and VADDR attributes, and must be compatible with them.

ASSIGN_SECTION Attribute (LOAD, NOTE, NULL)

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.

FILE_BASENAME, FILE_OBJNAME, FILE_PATH

These attributes allow the selection of sections based on the path (FILE_PATH), basename (FILE_BASENAME), or object name (FILE_OBJNAME) of the file they come from. The path or name can be specified as a string literal, or as a MATCH expression. See MATCH and MATCHREF Expressions.

File paths are specified using the standard UNIX slash delimited convention. The final path segment is the basename of the path, also known simply as the filename. In the case of an archive, the basename can be augmented with the name of the archive member, using the form archive_name(component_name). For example, /lib/libfoo.a(bar.o)specifies the object bar.o, found in an archive named /lib/libfoo.a.

FILE_BASENAME and FILE_OBJNAME are equivalent when applied to a non-archive, and compare the given name to the basename of the file. When applied to an archive, FILE_BASENAME examines the basename of the archive name, while FILE_OBJNAME examines the name of the object contained within the archive.

Each ASSIGN_SECTION maintains a list of all FILE_BASENAME, FILE_PATH, and FILE_OBJNAME values. A file match occurs if any one of these definitions match an input file.

IS_NAME

Input section name. The name can be specified as a string literal, or as a MATCH expression. See MATCH and MATCHREF Expressions.

TYPE

Specifies an ELF section_type, which can be any of the SHT_ constants defined in <sys/elf.h>, with the SHT_ prefix removed. For example, PROGBITS, SYMTAB, or NOBITS.

FLAGS

The FLAGS attribute uses section_flags to specify section attributes as a space separated list of one or more of the SHF_ constants defined in <sys/elf.h>, with the SHF prefix removed. The most commonly used flags are given in Figure 7, Table 7, Section FLAGS Values, which correspond to the SHF_ values defined in <sys/elf.h>. If an individual flag is preceded by an exclamation mark (!), that attribute must explicitly not be present. In the following example, a section is defined allocable and not writable.

        ALLOC !WRITE

Flags not explicitly in a section_flags list are ignored. In the preceding example, only the value of ALLOC and WRITE are examined when matching a section against the specified flags. The other section flags can have any value.

OUTPUT_SECTION

By default, output sections inherit their name and other properties from the input sections that are assigned to them. The OUTPUT_SECTION attribute is used to modify or override these properties. OUTPUT_SECTION accepts the following.

DISCARD

Discard the matched input section instead of copying it to the output object. The DISCARD attribute cannot be combined with any other OUTPUT_SECTION attribute.

FLAGS

The FLAGS attribute specifies section flags as a space separated list of the SHF_ constants defined in <sys/elf.h>, with the SHF_ prefix removed. There are three forms allowed.

        FLAGS  = section_flags;
        FLAGS  += section_flags;
        FLAGS  -= section_flags;

The simple "=" assignment operator replaces the flags inherited from the input section 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.

NAME

Specifies a new name for the output section, either as a string literal, or with a MATCHREF expression. When a MATCHREF expression is used, substrings from the input section and file name can be substituted from MATCH expressions used with the ASSIGN_SECTION FILE_BASENAME, FILE_OBJNAME, FILE_PATH, and IS_NAME attributes. The MATCHREF substitution tokens for the FILE_ attributes use the identifier character f, and are of the form ${fN}, where N is an integer value specifying the substring. Substitution tokens for the IS_NAME attribute use the identifier character n, and have the form ${nN}. See MATCH and MATCHREF Expressions.

TYPE

Specifies an ELF section_type, which can be any of the SHT_ constants defined in <sys/elf.h>, with the SHT_ prefix removed. For example, PROGBITS, SYMTAB, or NOBITS.

Table 7  Section FLAGS Values
Flag Value
Meaning
ALLOC
Section is allocable
WRITE
Section is writable
EXECUTEINSTR / EXECUTE
Section is executable
AMD64_LARGE
Section can be larger than 2 Gbytes

DISABLE Attribute (LOAD, NOTE, NULL)

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)

The FLAGS attribute specifies segment permissions as a space separated list of the permissions in Figure 3, Table 3, Segment Flags. 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 (LOAD, NOTE, NULL)

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)

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)

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 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 (LOAD, NOTE, NULL)

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, RESERVE)

The PADDR attribute is used to specify an explicit physical address for the segment. The value specified must be 0 or a power of 2. 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, RESERVE)

The ROUND attribute is used to align the offset of the first section of a segment within the file image being created. By default, sections within a file image are concatenated together based on the alignment requirements of each section. Padding is added by the link editor between sections to ensure that the overall alignment requirement for each section are met. This model produces the most compact file image, but can yield segment offsets within the file image that do not align with virtual memory pages. The ROUND attribute can be used to align segment offsets optimally for mapping to a memory image.

The alignment of the first segment in an ELF object is sufficient to create an optimal mapping without the use of ROUND. ROUND is commonly used on segments other than the first, usually for the data segment that follows the text segment.


Note - The first segment typically starts with ELF headers, followed by section data. ROUND applies to the section data. As such, the application of ROUND to the first segment can require the link-editor to introduce a padding gap between the headers and the section data.

The rounding value specified must be 0 or 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. The system provides /usr/lib/ld/map.pagealign to set alignments that are the most appropriate for memory mapping on a given platform.

SIZE Attribute (RESERVE)

The SIZE attribute specifies the size of a memory reservation segment.

SIZE_SYMBOL Attribute (LOAD, RESERVE)

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.

TYPE (RESERVE)

The TYPE attribute is used to specify the type of memory reservation.

RESERVE

A standard virtual memory address reservation. If TYPE is not specified, RESERVE is the default. A virtual address reservation provides the means to reserve a portion of a process address. Mapping operations such as mmap(2), and shmat(2) are able to use the reserved memory by explicitly specifying a fixed address within the reserved range. However, the system will not otherwise choose to map objects and or other files within a reserved range. The link-editor creates a PT_LOAD program header entry with the p_flags, and p_filesz fields set to zero. The VADDR, and SIZE attributes are required for a RESERVE memory reservation segment.

SYSSTAT

Reserved for internal use. The link-editor creates a PT_SUNW_SYSSTAT memory reservation. The VADDR attribute is required for a SYSSTAT memory reservation segment. If SIZE is specified, the mapping is given the specified size. Otherwise, the default system defined size for the mapping type is provided.

SYSSTAT_ZONE

Reserved for internal use. The link-editor creates a PT_SUNW_SYSSTAT_ZONE memory reservation. The VADDR attribute is required for a SYSSTAT_ZONE memory reservation segment. If SIZE is specified, the mapping is given the specified size. Otherwise, the default system defined size for the mapping type is provided.

VADDR (LOAD, RESERVE)

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 LOAD segments as the output file is created, and the VADDR attribute is optional. The VADDR attribute is required for RESERVE segments.

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.
  • The first loadable segment is expected to be read-only, allocable, and executable, and receives the ELF header and program header array. This is usually the predefined text segment.

  • The final loadable segment in an executable is expected to be writable, and the head of the dynamic heap is usually located immediately following within the same virtual memory mapping.

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


Note - This directive is maintained for backward compatibility. A more extensive mechanism of requesting security extensions is provided using the link-editor's –z sx option. See Requesting Security Extensions.

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 Figure 3, Table 3, Segment Flags.

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_SUNW_STACK program header entry.

STUB_OBJECT Directive

The STUB_OBJECT directive informs the link-editor that the object described by the mapfile can be built as a stub object.

        STUB_OBJECT;

A stub shared object is built entirely from the information in the mapfiles supplied on the command line. When the –z stub option is specified to build a stub object, the presence of the STUB_OBJECT directive in a mapfile is required, and the link-editor uses the information in symbol ASSERT attributes to create global symbols that match those of the real object.

SYMBOL_SCOPE and 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 {
                        ASSERT = {
                                ALIAS = symbol_name;
                                BINDING = symbol_binding;
                                TYPE = symbol_type;

                                SIZE = size_value;
                                SIZE = size_value[count];
                                VALUE = value;
                        };

                        DEFERRED = soname;
                
                        AUXILIARY = soname;
                        FILTER = soname;
                        FILTER {
                                FILTEE = soname;
                                TYPE = filter_type;
                        };

                        FLAGS = symbol_flags....;
                
                        RENAME = symbol_name;
                        RENAME = MATCHREF(...);

                        SIZE = size_value;
                        SIZE = size_value[count];

                        TYPE = symbol_type;
                        VALUE = value;
                };

                MATCH(...);
                MATCH(...) {
                        See symbol_name
                };
        } [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 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 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 Figure 34, Table 34, ELF Symbol Visibility.
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 Figure 34, Table 34, ELF Symbol Visibility.
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 Figure 34, Table 34, ELF Symbol Visibility.
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 Figure 34, Table 34, ELF Symbol Visibility.
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 Figure 34, Table 34, ELF Symbol Visibility.
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 Figure 34, Table 34, ELF Symbol Visibility.

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.

The symbol can also be specified as a MATCH expression. See MATCH and MATCHREF Expressions.

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 a dynamic 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 a dynamic 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 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.

ASSERT Attribute

The ASSERT attribute is used to specify the expected characteristics of the symbol. The link-editor compares the symbol characteristics that result from the link-edit to those given by ASSERT attributes. If the real and asserted attributes do not agree, a fatal error is issued and the output object is not created.

The interpretation of the ASSERT attribute is dependent on whether the STUB_OBJECT directive or –z stub command line option are used. The three possible cases are as follows.

  1. ASSERT attributes are not required when the STUB_OBJECT directive is not used. However, if ASSERT attributes exist, their attributes are verified against the real values collected with the link-edit. Should any ASSERT attributes not match their associated real values, the link-edit terminates unsuccessfully.

  2. When the STUB_OBJECT directive is used, and the –z stub command line option is specified, the link-editor uses the ASSERT directives to define the attributes of the global symbols provided by the object. See Stub Objects.

  3. When the STUB_OBJECT directive is used, and –z stub command line option is not specified, the link-editor requires that all global data in the resulting object have an associated ASSERT directive that declares it as data and supplies a size. In this mode, if the TYPE ASSERT attribute is not specified, GLOBAL is assumed. Similarly, if SH_ATTR is not specified, a default value of BITS is assumed. These defaults ensure that the data attributes of the stub and real objects are compatible. The resulting ASSERT statements are evaluated in the same manner as in the first case. See STUB_OBJECT Directive.

ASSERT accepts the following attributes.

ALIAS

Defines an alias for a previously defined symbol. An alias symbol has the same type, value, and size as the main symbol. The ALIAS attribute cannot be used with the TYPE, SIZE, and SH_ATTR attributes. When ALIAS is specified, the type, size, and section attributes are obtained from the alias symbol.

BIND

Specifies an ELF symbol_binding, which can be any of the STB_ values defined in <sys/elf.h>, with the STB_ prefix removed. For example, GLOBAL, or WEAK.

TYPE

Specifies an ELF symbol_type, which can be any of the STT_ constants defined in <sys/elf.h>, with the STT_ prefix removed. For example, OBJECT, COMMON, or FUNC. In addition, for compatibility with other mapfile usage, FUNCTION and DATA can be specified for STT_FUNC and STT_OBJECT, respectively. TYPE cannot be used with ALIAS.

SH_ATTR

Specifies attributes of the section associated with the symbol. The section_attributes that can be specified are given in Figure 9, Table 9, SH_ATTR Values. SH_ATTR cannot be used with ALIAS.

SIZE

Specifies the expected symbol size. SIZE cannot be used with ALIAS. The syntax for the size_value argument is as described in the discussion of the SIZE attribute. See SIZE Attribute.

VALUE

Specifies the expected symbol value.

Table 9  SH_ATTR Values
Section Attribute
Meaning
BITS
Section is not of type SHT_NOBITS
NOBITS
Section is of type SHT_NOBITS

DEFERRED Attribute

Indicates that this symbol is a deferred reference on the shared object name (soname). See Deferred Symbol References.

AUXILIARY Attribute

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

The AUXILIARY attribute is equivalent to the following.

        FILTER {
                FILTEE = soname;
                TYPE = AUXILIARY;
        };

FILTER Attribute

The FILTER attribute indicates that this symbol is a filter to another shared object. It shares the same syntax as the FILTER directive, differing in that it works at the per-symbol level rather than the entire object.

FILTER accepts the following attributes.

STANDARD

A standard filter. Standard 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. See Generating Standard Filters.

AUXILIARY

An auxiliary filter. See Generating Auxiliary Filters.

WEAK

A weak standard filter. Weak filters are identical to standard filters at runtime. At link-edit time, if unused dependency processing is active, a weak filter symbol from a dependency can be ignored in favor of the same symbol from the target filtee. Weak filters are the preferred type when using filters to provide backward compatibility when code moves between libraries. See Generating Weak Filters.

The simplified form of the FILTER attribute has the following form.

        FILTER = soname;

This creates a standard filter, and is equivalent to the following.

        FILTER {
                FILTEE = soname;
                TYPE = STANDARD;
        };

FLAGS Attribute

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

Table 10  Symbol FLAGS 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 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 an 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 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.
STUB_ELIMINATE
Indicates that this symbol should be omitted from stub objects. See Using Stub Objects to Hide Obsolete Interfaces.

RENAME Attribute

Specifies a new name for the symbol in the output object, either as a string literal, or with a MATCHREF expression. When a MATCHREF expression is used, substrings from the original name can be substituted from a MATCH expression used to specify the symbol_name. The MATCHREF substitution tokens for the name use the identifier character n, and are of the form {$nN}. See MATCH and MATCHREF Expressions.

SIZE Attribute

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

The size_value argument can be a numeric value, or it can be the symbolic name addrsize. addrsize represents the size of a machine word capable of holding a memory address. The link-editor substitutes the value 4 for addrsize when building 32-bit objects, and the value 8 when building 64-bit objects. addrsize is useful for representing the size of pointer variables and C variables of type long, as it automatically adjusts for 32 and 64-bit objects without requiring the use of conditional input.

The size_value argument can be optionally suffixed with a count value, enclosed in square brackets. If count is present, size_value and count are multiplied together to obtain the final size value.

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.