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.

The ?E flag allows the creation of an empty segment. This empty segment has no sections associated with it. This segment can only be specified for executables, and must be of type LOAD with a specified size and alignment. Multiple segment definitions of this type are permitted.

The ?N flag enables you control whether the ELF header, and any program headers are included as part of the first loadable segment. By default, the ELF header and program headers are included with the first segment. The information in these headers is used within the mapped image, typically by the runtime linker. The use of the ?N option causes the virtual address calculations for the image to start at the first section of the first segment.

The ?O flag enables you control the order of sections in the output file. This flag is intended for use 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. Because the -xF option forces one function per section, the use of the ?O flag to control the order of sections in effect controls the order of functions.

Consider the following user-defined mapfile:

        text = LOAD ?RXO;
        text: .text%foo;
        text: .text%bar;
        text: .text%main;

The first declaration associates the ?O flag with the default text segment.

If the order of function definitions in the source file is main, foo, and bar, then the final executable contains functions in the order foo, bar, and main.

For static functions with the same name, the file names must also be used. The ?O flag forces the ordering of sections as requested in the mapfile. For example, if a static function bar() exists in files a.o and b.o, and function bar() from file a.o is to be placed before function bar() from file b.o, then the mapfile entries should read:

        text: .text%bar: a.o;
        text: .text%bar: b.o;

Although the syntax allows for the entry:

        text: .text%bar: a.o b.o;

this entry does not guarantee that function bar() from file a.o is placed before function bar() from file b.o. The second format is not recommended as the results are not reliable.

Mapping Directives

A mapping directive instructs the link-editor how to map input sections to output segments. Basically, you name the segment that you are mapping to and indicate what the attributes of a section must be in order to map into the named segment. The set of section_attribute_values that a section must have to map into a specific segment is called the entrance criteria for that segment. In order to be placed in a specified segment of the output file, a section must meet the entrance criteria for a segment exactly.

A mapping directive has the following syntax:

        segment_name : {section_attribute_value}* [: {file_name}+];

For a segment_name, you specify any number of section_attribute_values in any order, each separated by a space. At most, one section attribute value is allowed for each section attribute. You can also specify that the section must come from a certain .o file through a file_name declaration. The section attributes and their valid values are shown in the following table.

Table 9-2 Section Attributes

Note the following points when entering mapping directives:

• You must choose at most one section_type from the section_types listed above. The section_types listed above are built-in types. For more information on section_types, see Sections.

• The section_flags values are A for allocatable, W for writable, or X for executable. If an individual flag is preceded by an exclamation mark (!), the link-editor checks that the flag is not set. No spaces are allowed between the question mark, exclamation marks, and the individual flags that make up the section_flags value.

• file_name can be any legal file name, of the form *filename, or of the form archive_name(component_name), for example, /usr/lib/libc.a(printf.o). The link-editor does not check the syntax of file names.

• If a file_name is of the form *filename, the link-editor simulates a basename(1) on the file from the command line and uses it to match against the specified file name. In other words, the filename from the mapfile only needs to match the last part of the file name from the command line. See Mapping Example.

• If you use the -l option during a link-edit, and the library after the -l option is in the current directory, you must precede the library with ./, or the entire path name, in the mapfile in order to create a match.

• More than one directive line can appear for a particular output segment. For example, the following set of directives is legal:

  S1 : $PROGBITS; S1 : $NOBITS;

  
  

  Entering more than one mapping directive line for a segment is the only way to specify multiple values of a section attribute.

• A section can match more than one entrance criteria. In this case, the first segment encountered in the mapfile with that entrance criteria is used. For example, if a mapfile reads:

  S1 : $PROGBITS; S2 : $PROGBITS;

  
  

  the $PROGBITS sections are mapped to segment S1.

Section-Within-Segment Ordering

By using the following notation you can specify the order that sections are placed within a segment:

        segment_name | section_name1;
        segment_name | section_name2;
        segment_name | section_name3;

The sections that are named in the above form are placed before any unnamed sections, and in the order they are listed in the mapfile.

Size-Symbol Declarations

Size-symbol declarations enable you to define a new global-absolute symbol that represents the size, in bytes, of the specified segment. This symbol can be referenced in your object files. A size-symbol declaration has the following syntax:

        segment_name @ symbol_name;

symbol_name can be any legal C identifier. The link-editor does not check the syntax of the symbol_name.

File Control Directives

File control directives enable you to specify which version definitions within shared objects are to be made available during a link-edit. The file control definition has the following syntax:

        shared_object_name - version_name [ version_name ... ];

version_name is a version definition name contained within the specified shared_object_name.

Mapping Example

The following example is a user-defined mapfile. 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 9-1 User-Defined Mapfile

    1.  elephant : .data : peanuts.o *popcorn.o; 
    2.  monkey : $PROGBITS ?AX; 
    3.  monkey : .data; 
    4.  monkey = LOAD V0x80000000 L0x4000; 
    5.  donkey : .data; 
    6.  donkey = ?RX A0x1000; 
    7.  text = V0x80008000;

Four separate segments are manipulated in this example. The implicitly declared segment elephant (line 1) receives all of the .data sections from the files peanuts.o and popcorn.o. Notice that *popcorn.o matches any popcorn.o file that can be supplied to the link-edit. The file need not be in the current directory. On the other hand, if /var/tmp/peanuts.o was supplied to the link-edit, it does not match peanuts.o because it is not preceded by an *.

The implicitly declared segment monkey (line 2) receives all sections that are both $PROGBITS and allocatable-executable (?AX), as well as all sections not already in the segment elephant with the name .data (line 3). The .data sections entering the monkey segment need not be $PROGBITS or allocatable-executable because the section_type and section_flags values are entered on a separate line from the section_name value.

An "and" relationship exists between attributes on the same line as illustrated by $PROGBITS "and" ?AX on line 2. An "or" relationship exists between attributes for the same segment that span more than one line, as illustrated by $PROGBITS ?AX on line 2 "or" .data on line 3.

The monkey segment is implicitly declared in line 2 with segment_type value LOAD, segment_flags value RWX, and no virtual_address, physical_address, length or alignment values specified (defaults are used). In line 4 the segment_type value of monkey is set to LOAD. Because the segment_type attribute value does not change, no warning is issued. The virtual_address value is set to 0x80000000 and the maximum length value to 0x4000.

Line 5 implicitly declares the donkey segment. The entrance criteria are designed to route all .data sections to this segment. Actually, no sections fall into this segment because the entrance criteria for monkey in line 3 capture all of these sections. In line 6, the segment_flags value is set to ?RX and the alignment value is set to 0x1000. Because both of these attribute values changed, a warning is issued.

Line 7 sets the virtual_address value of the text segment to 0x80008000.

The example of a user-defined mapfile is designed to cause warnings for illustration purposes. If you want to change the order of the directives to avoid warnings, use the following example:

    1.  elephant : .data : peanuts.o *popcorn.o; 
    4.  monkey = LOAD V0x80000000 L0x4000; 
    2.  monkey : $PROGBITS ?AX; 
    3.  monkey : .data; 
    6.  donkey = ?RX A0x1000; 
    5.  donkey : .data; 
    7.  text = V0x80008000;

The following mapfile example uses the segment-within-section ordering:

    1.  text = LOAD ?RXN V0xf0004000; 
    2.  text | .text; 
    3.  text | .rodata; 
    4.  text : $PROGBITS ?A!W; 
    5.  data = LOAD ?RWX R0x1000;