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 {
                                ANCILLARY = anc_name;

                                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.