ASSIGN_SECTION Attribute (LOAD, NOTE, NULL)

`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 Table 10-7, 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.

ANCILLARY

Specifies that the data for a matched non-allocable section should be directed to the ancillary output object given by anc_name. The anc_name must be defined by a previous ANCILLARY directive. See ANCILLARY Directive. ANCILLARY can only be used with SEGMENT_NULL directives.

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 10-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