Mapfile Option

The link-editor automatically and intelligently maps input sections from relocatable objects to segments in the output file being created. The -M option with an associated mapfile enables you to change the default mapping provided by the link-editor. In addition, new segments can be created, attributes modified, and symbol versioning information can be supplied with the mapfile.

Note - When using a mapfile option, you can easily create an output file that does not execute. The link-editor knows how to produce a correct output file without the use of the mapfile option.

Sample mapfiles provided on the system reside in the /usr/lib/ld directory.

Mapfile Structure and Syntax

You can enter four basic types of directives into a mapfile:

• Segment declarations.

• Mapping directives.

• Section-to-segment ordering.

• Size-symbol declarations.

• File control directives.

Each directive can span more than one line and can have any amount of white space, including new lines, as long as that white space is followed by a semicolon.

Typically, segment declarations are followed by mapping directives. You declare a segment and then define the criteria by which a section becomes part of that segment. If you enter a mapping directive or size-symbol declaration without first declaring the segment to which you are mapping, except for built-in segments, the segment is given default attributes. Such segment is an implicitly declared segment.

Size-symbol declarations and file control directives can appear anywhere in a mapfile.

The following sections describe each directive type. For all syntax discussions, the following notations apply:

• All entries in constant width, all colons, semicolons, equal signs, and at (@) signs are typed in literally.

• All entries in italics are substitutable.

• { ... }* means "zero or more."

• { ... }+ means "one or more."

• [ ... ]  means "optional."

• section_names and segment_names follow the same rules as C identifiers, where a period (.) is treated as a letter. For example, .bss is a legal name.

• section_names, segment_names, file_names, and symbol_names are case sensitive. Everything else is not case sensitive.

• Spaces, or new-lines, can appear anywhere except before a number or in the middle of a name or value.

• Comments beginning with # and ending at a newline can appear anywhere that a space can appear.

Segment Declarations

A segment declaration creates a new segment in the output file, or changes the attribute values of an existing segment. An existing segment is one that you previously defined or one of the four built-in segments described immediately following.

A segment declaration has the following syntax:

        segment_name = {segment_attribute_value}*;

For each segment_name, you can specify any number of segment_attribute_values in any order, each separated by a space. Only one attribute value is allowed for each segment attribute. The segment attributes and their valid values are as shown in the following table.

Table 8-1 Mapfile Segment Attributes

There are four built-in segments with the following default attribute values:

• text - LOAD, ?RX, no virtual_address, physical_address, or length specified, alignment values set to defaults per CPU type.

• data - LOAD, ?RWX, no virtual_address, physical_address, or length specified, alignment values set to defaults per CPU type.

• bss - disabled, LOAD, ?RWX, no virtual_address, physical_address, or length specified, alignment values set to defaults per CPU type.

• note - NOTE.

By default, the bss segment is disabled. Any sections of type SHT_NOBITS, which are its sole input, are captured in the data segment. See Table 7-12 for a full description of SHT_NOBITS sections. The simplest bss declaration:

        bss =;

is sufficient to enable the creation of a bss segment. Any SHT_NOBITS sections will be captured by this segment, rather than captured in the data segment. In its simplest form, this segment is aligned using the same defaults as applied to any other segment. The declaration can also provide additional segment attributes that both enable the segment creation and assign the specified attributes.

The link-editor behaves as if these segments are declared before your mapfile is read in. See "Mapfile Option Defaults".

Note the following when entering segment declarations:

• A number can be hexadecimal, decimal, or octal, following the same rules as in the C language.

• No space is allowed between the V, P, L, R, or A and the number.

• The segment_type value can be either LOAD, NOTE or STACK. If unspecified it defaults to LOAD.

• The segment_flags values are R for readable, W for writable, X for executable, and O for order. No spaces are allowed between the question mark (?) and the individual flags that make up the segment_flags value.

• The segment_flags value for a LOAD segment defaults to RWX.

• NOTE segments cannot be assigned any segment attribute value other than a segment_type.

• One segment_type of value STACK is permitted. Only the access requirements of the segment, selected from the segment_flags, can be specified.

• Implicitly declared segments default to segment_type value LOAD, segment_flags value RWX, a default virtual_address, physical_address, and alignment value, and have no length limit.

  ---

  Note - The link-editor calculates the addresses and length of the current segment based on the previous segment's attribute values.

  ---

• LOAD segments can have an explicitly specified virtual_address value or physical_address value, as well as a maximum segment length value.

• If a segment has a segment_flags value of ? with nothing following, the value defaults to not readable, not writable, and not executable.

• The alignment value is used in calculating the virtual address of the beginning of the segment. This alignment only affects the segment for which it is specified. Other segments still have the default alignment unless their alignments are also changed.

• If any of the virtual_address, physical_address, or length attribute values are not set, the link-editor calculates these values as it creates the output file.

• If an alignment value is not specified for a segment, it is set to the built-in default. This default differs from one CPU to another and might even differ between software revisions.

• If both a virtual_address and an alignment value are specified for a segment, the virtual_address value takes priority.

• If a virtual_address value is specified for a segment, the alignment field in the program header contains the default alignment value.

• If the rounding value is set for a segment, that segment's virtual address will be rounded to the next address that conforms to the value given. This value only effects the segments that it is specified for. If no value is given, no rounding is performed.

Note - If a virtual_address value is specified, the segment is placed at that virtual address. For the system kernel, this method creates a correct result. For files that start through exec(2), this method creates an incorrect output file because the segments do not have correct offsets relative to their page boundaries.