Mapfiles

• Create and/or modify output segments
• Define how input sections are assigned to segments, and the relative order of those sections.
• Specify symbol scope and/or versioning, creating stable backward compatible interfaces for sharable objects.
• Define the versions to use from sharable object dependencies
• Set header options in the output object
• Set process stack attributes for a dynamic executable
• Set or override hardware and software capabilities

Note: The link-editor used without a mapfile will always produce a valid ELF output file. The mapfile option provides the user with a great deal of flexibility and control over the output object, some of which has the potential to produce an invalid or unusable object. The user is expected to have knowledge of the rules and conventions that govern the ELF format.

The -M command line option is used to specify the mapfile to be used. Multiple mapfiles can be used in a single link operation. When more than one mapfile is specified, the link-editor processes each one in the order given, as if they represented a single logical mapfile. This occurs before any input objects are processed.

The system provides sample mapfiles for solving common problems in the /usr/lib/ld directory.

Mapfile Structure and Syntax

Syntax Notations

• 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. Comments are not interpreted by the link-editor, and exist solely for documentation purposes.

• All directives are terminated by a semicolon. The final semicolon within a { ... } section can be omitted.

• All entries in constant width, all colons, semicolons, equal signs, and { ... } brackets are typed in literally.

• All entries in italics are substitutable.

• [ ... ] brackets are used to delineate optional syntax. The brackets are not literal, and do not appear in the actual directives.

• Names are case sensitive strings. They can be specified in three different forms:

  Unquoted

  An unquoted name is a sequence of letters and digits. The first character must be a letter, followed by zero or more letters or digits. The characters percent (%), slash (/), period (.), and underscore (_) count as a letter. The characters dollar ($), and hypen (-) counts as a digit.

  Single Quotes

  Within single quotes ('), a name can contain any character other than a single quote, or newline. All characters are interpreted as literal characters. This form of quoting is convenient when specifying filepaths, or other names that contain normal printable characters that are not allowed in an unquoted name.

  Double Quotes

  Within double quotes ("), a name can contain any character other than a double quote, or newline. Backslash(\) is an escape character which operates similarly to the way it is used in the C programming language within a string literal. Characters prefixed by a backslash are replaced by the character they represent, as shown in the following table:

  Escape Sequence	Meaning
  \a	alert (bell)
  \b	backspace
  \f	formfeed
  \n	newline
  \r	return
  \t	horizontal tab
  \v	vertical tab
  \\	backslash
  \'	single quote
  \"	double quote
  \ooo	An octal constant, where ooo is one to three octal digits (0...7)

  Any other character following a backslash is an error.

  The following is a list of widely used names and other strings found in mapfiles:

  Name	Purpose
  segment_name	Name of ELF segment
  section_name	Name of ELF section
  symbol_name	Name of ELF symbol
  file_path	A Unix file path of slash (/) delimited names used to reference an ELF object, or an archive that contains ELF objects
  file_basename	Final component (basename(1)) of a file_path
  objname	Either a file_basename, or the name of an object contained within an archive
  soname	Sharable object name, as used for the SONAME of a sharable object (e.g. libc.so.1)
  version_name	Name of a symbol version, as used within an ELF versioning section
  inherited_version_name	Name of a symbol version inherited by another symbol version

• value represents a numeric value, and can be hexadecimal, decimal, or octal, following the rules used by the C language for integer constants. All values are unsigned integer values, and are 32-bit for 32-bit output objects, and 64-bit for 64-bit output objects.

• segment_flags specify memory access permissions as a space separated list of one or more of the following values, which correspond to the PF_ values defined in <sys/elf.h>:

  Flag Value	Meaning
  READ	Segment is readable
  WRITE	Segment is writable
  EXECUTE	Segment is executable
  0	All permission flags are cleared
  DATA	Data segment flags for target platform (platform dependent)
  STACK	Default stack flags as defined by platform ABI

  DATA and STACK are not unique values. Rather, they are formed from the combination of the READ, WRITE, and EXECUTE flags appropriate for the target platform.

Mapfile Version

$mapfile_version 2

A mapfile that does not begin with a version declaration is assumed to be written in the original mapfile language defined for System V Release 4 Unix (SVR4) by AT&T. The link-editor retains the ability to process such mapfiles. Their syntax is documented in Appendix ZZZ - AT&T System V Release 4 Mapping Syntax.

Conditional Input

$if expr
...
[$elif expr]
...
[$else]
...
$endif

Each of the directives ($if, $elif, $else, and $endif) appear alone on a line. The logical expressions in $if and subsequent $elif lines are evaluated in order until an expression that evaluates to True is found. Text following a line with a False value is discarded. The text following a successful directive line is treated normally. "Text" here refers to any material, that is not part of the conditional structure. Once a successful $if or $elif has been found, and its text processed, succeeding $elif and $else lines, together with their text, are discarded. If all the expressions are zero, and there is a $else, the text following the $else is treated normally.

The scope of an $if directive cannot extend across multiple mapfiles. A $if directive must be terminated by a matching $endif within the mapfile that uses it, or the link-editor will issue an error.

The link-editor maintains an internal table of names that can be used in the logical expressions evaluated by $if and $elif. At startup, this table is initialized with each of the following names that apply to the output object being created:

Name	Meaning
_ELF32	32-bit object
_ELF64	64-bit object
_sparc	Sparc machine (32 or 64-bit)
_x86	x86 machine (32 or 64-bit)
true	Always defined

The names are case sensitive, and must be used exactly as shown. For example, true is defined, but TRUE is not. Any of these names can be used by themselves as a logical expression. For example:

$if _ELF64
...
$endif

More complex logical expressions can be written, using the following operators:

Operator	Meaning
&&	Logical AND
||	Logical OR
(expr)	Sub-expression
!	Negate boolean value of following expression

For example, the lines in the following construct will be evaluated when building 64-bit objects for X86 platforms:

$if _ELF64 && _x86
...
$endif

$if _ELF64 && _x86
$add amd64
$endif

$if amd64
...
$endif

$clear amd64

The effect of the $add directive persists beyond the end of the mapfile that uses it, and is visible to any subsequent mapfile that is processed by the link-editor in the same link operation. If this is not desired, use $clear at the end of the mapfile containing the $add to remove it.

Finally, the $error directive causes the link-editor to print all remaining text on the line as a fatal error, and halt the link operation. This can be used to ensure that a programmer porting an object to a new machine type will not be able to silently build an incorrect object that is missing a necessary mapfile definition:

$if _sparc
...
$elif _x86
...
$else
$error unknown machine type
$endif

C language programmers will recognize that the syntax used for mapfile conditional input resembles that of the C preprocessor macro language (cpp). This similarity is intentional. However, mapfile conditional input directives are by design considerably less powerful than those provided by cpp. They provide only the most basic facilities required to support linking operations in a cross platform environment.

Among the significant differences between the two languages:

• The C preprocessor defines a full macro language, and the macros are applied to both the source text, and to the expressions evaluated by the #if and #elif preprocessor statements. Linker mapfiles do not implement a macro capability.

• The expressions evaluated by CPP involve numeric types, and a rich set of operators. Mapfile logical expressions involve boolean True/False values, and a limited set of operators.

• C preprocessor expressions involve arbitrary numeric values, possibly defined as macros, and defined() is used to evaluate whether a given macro is defined or not, yielding a True (1) or False (0) value. Mapfile logical expressions only manipulate boolean values, and names are used directly without a defined() operation. The specified names are considered to be True if they exist in the link-editor's table of known names, and False otherwise.

Mapfile Directives

Directive	Purpose
CAPABILITY	Hardware and software capabilities
DEPEND_VERSIONS	Specify allowed versions from sharable object dependencies
HDR_NOALLOC	ELF header and program headers are not allocable
LOAD_SEGMENT	Create new loadable segment, or modify an existing one
NOTE_SEGMENT	Create note segment, or modify an existing one
NULL_SEGMENT	Create null segment, or modify an existing one
PHDR_ADD_NULL	Add Null Program Header Entries
SEGMENT_ORDER	Specify the order of segments in the output object and program header array.
STACK	Process Stack Attributes
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 simplest form is a directive name without a value:

directive;

directive = value...;

In addition to the '=' operator shown, the '+=' and '-=' forms of assignment are allowed. The '=' operator sets the given directive to the given value, or value list. The '+=' operator can be used to specify that the value on the right hand side is to be added to the current value, and the '-=' operator is used to remove values.

More complex directives manipulate items that take multiple attributes enclosed within {...} brackets to group the attributes together as a unit:

directive [name] {
        attribute [= value];
        ...
} [name...];

There can be a name before the opening '{', which is used to name the result of the given statement. Similarly, one or more optional names may follow the closing '}', prior to the terminating ';'. These names are used to express that the named item being defined has relationship with other named items.

Note that the format for attributes within a grouping use the same syntax described for simple directives with a value above, with a '=', '+=', or '-=' assignment operator, followed by a value, or whitespace sepated list of values, terminated with a semicolon (';').

A directive may have sub-attributes that in turn have sub-attributes. In such cases, the sub-attributes are also grouped within nested { ... } brackets to reflect this hierarchy:

directive [name] {
        attribute {
                subattribute [= value];
                ...
        };
                ...
} [name...];

The mapfile syntax grammar puts no limit on the depth to which such nesting is allowed. It depends solely on the requirements of the directive.

The specific syntax for each supported mapfile directive is shown in the sections that follow.

CAPABILITY Directive

CAPABILITY {
        HW = hwcap_flags;
        HW += hwcap_flags;
        HW -= hwcap_flags;

        SF = sfcap_flags;
        SF += sfcap_flags;
        SF -= sfcap_flags;

        HW_1 = value;
        HW_1 += value;
        HW_1 -= value;

        HW_2 = value;
        HW_2 += value;
        HW_2 -= value;

        SF_1 = value;
        SF_1 += value;
        SF_1 -= value;
};	

• If the '+=' operator is used, the value specified is added to the current value for that capability.

• If the '-=' operator is used, the value specified is added to the exclude values for that capability.

• If the '=' operator is used, the value specified replaces the previous value, and exclude is reset to 0. In addition, the fact that the '=' form was used for that capability is remembered by the link-editor.

Prior to wring the resulting capability value to the output object, the link-editor subtracts any capability values specified with the '-=' operator.

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 maps internally to the appropriate mask and bit. The numbered attributes (HW_1, etc) 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. When possible, the HW and SF attributes should be used.

HW

SF

HW_1, HW_2

SF_1

DEPEND_VERSIONS Directive

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

REQUIRE

HDR_NOALLOC Directive

HDR_NOALLOC;

PHDR_ADD_NULL Directive

PHDR_ADD_NULL = value;

LOAD_SEGMENT, NOTE_SEGMENT, and NULL_SEGMENT Directives

LOAD_SEGMENT

Specifies a loadable segment containing code or data to be 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.

NOTE_SEGMENT

A NOTE_SEGMENT holds NOTE sections. The link-editor creates a PT_NOTE program header entry that references it. Note segments are not allocable.

NULL_SEGMENT

A null segment holds non-allocable sections that 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.

If segment_name is a pre-existing segment, then the attributes specified modify it. Otherwise, a new segment is created and the specified attributes are applied to it. The link-editor fills in default values for attributes not explicitly supplied.

Note: When selecting a segment name, bear in mind that future versions of the link-editor may add new predefined segments. If the name used in your segment directive matches this new name, it 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 (e.g. hello_world_data_segment).

All three segment directives share a common set of core attributes. Substituting one of (LOAD_SEGMENT, NOTE_SEGMENT, NULL_SEGMENT) for directive in the following, the syntax for this shared core is:

directive segment_name {

        ASSIGN_SECTION [assign_name];
        ASSIGN_SECTION [assign_name] {
                FILE_BASENAME = file_basename;
                FILE_OBJNAME = objname;
                FILE_PATH = file_path;
                FLAGS = section_flags;
                IS_NAME = section_name;
                TYPE = section_type;
        };

        DISABLE;

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

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

The LOAD_SEGMENT directive accepts an additional set of attributes specific to loadable segments. The syntax for these additional attributes is:

LOAD_SEGMENT segment_name {
        ALIGN = value;

        FLAGS  = segment_flags;
        FLAGS += segment_flags;
        FLAGS -= segment_flags;

        MAX_SIZE = value;

	NOHDR;

        PADDR = value;
        ROUND = value;

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

        VADDR = value;
};

Any of the segment directives can be specified as an empty directive. When an empty segment directive creates a new segment, default values are established for all of its attributes:

LOAD_SEGMENT segment_name;

NOTE_SEGMENT segment_name;

NULL_SEGMENT segment_name;

All of the attributes accepted by one or more of the segment directives are described below.

ALIGN (LOAD_SEGMENT only)

The alignment specified must be 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 mutually exclusive to the PADDR and VADDR attributes, and cannot be used with them together. When PADDR or VADDR is specified, the p_align field of the corresponding program header will be set to the default value.

ASSIGN_SECTION

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 it satisfies any one of the ASSIGN_SECTION attributes. The link-editor will not assign sections to a segment unless it 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 criteria 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 criteria in turn. The section is assigned to the segment associated with the first entrance criteria 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 attribute allows the selection of sections based on the path (FILE_PATH), basename (FILE_BASENAME), or object name (FILE_OBJNAME) of the file they come from.

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/libc.a(printf.o) specifies the object printf.o, found in an archive named /lib/libc.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 still examines the basename of the file (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

TYPE

Specifies an ELF section_type, which can be any of the SHT_ constants defined in , with the SHT_ prefix removed. (e.g. PROGBITS, SYMTAB, NOBITS, etc).

FLAGS

The FLAGS attribute uses section_flags to specify section attributes as a space separated list of one or more of the following values, which correspond to the SHF_ values defined in <sys/elf.h>:

Flag Value	Meaning
ALLOC	Section is allocable
WRITE	Section is writable
EXECUTE	Section is executable
AMD64_LARGE	Section can be larger than 2GB

If an individual flag is preceded by an exclamation mark (!), that attribute must explicitly not be present. For example,

ALLOC !WRITE

specifies that a section must be allocable, and not writable. Flags not explicitly in a section_flags list are ignored. In the above 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.

DISABLE

segment segment_name;

FLAGS (LOAD_SEGMENT only)

There are three forms allowed:

FLAGS  = segment_flags;
FLAGS += segment_flags;
FLAGS -= segment_flags;

IS_ORDER

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 it 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;
};

MAX_SIZE (LOAD_SEGMENT only)

NOHDR (LOAD_SEGMENT only)

The NOHDR attribute differs from the top level HDR_NOALLOC directive in that it 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 Appendix ZZZ - AT&T System V Mapping Syntax for more details.

The HDR_NOALLOC directive is recommended in preference to the segment NOHDR attribute.

ROUND (LOAD_SEGMENT only)

SIZE_SYMBOL (LOAD_SEGMENT only)

The '=' form of assignment can be used to establish an initial value. It 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.

OS_ORDER

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 (LOAD_SEGMENT only)

VADDR (LOAD_SEGMENT only)

SEGMENT_ORDER Directive

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 via the VADDR attribute of the LOAD_SEGMENT directive, sorted by address

2. Segments ordered via the SEGMENT_ORDER directives come next, in the specified order.

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 readonly, 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.

STACK Directive

STACK {
        FLAGS  = segment_flags;
        FLAGS += segment_flags;
        FLAGS -= 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 can be specified using the segment flag name 'STACK'.

On some platforms, the ABI mandated default permissions include EXECUTE. It 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_SUNWSTACK program header entry.

SYMBOL_SCOPE and SYMBOL_VERSION Directives

The syntax for SYMBOL_VERSION is:

SYMBOL_VERSION version_name {
	symbol_scope:

	*;
	symbol_name;
	symbol_name {
		AUXILIARY = soname;
		FILTER = soname;
		FLAGS = symbol_flags;
		SIZE = value;
		TYPE = symbol_type
		VALUE = value;
	};
} [inherited_version_name...];

SYMBOL_SCOPE is identical, except that it does not accept version names:

SYMBOL_SCOPE {
        ...
};

symbol_scope defines the scope of symbols in a SYMBOL_SCOPE or SYMBOL_VERSION mapfile 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:

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 Table 7-20.
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 Table 7-20.
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 Table 7-20.
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 Table 7-20.
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 Table 7-20.
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 Table 7-20. Note that local symbols can also be eliminated by using the link-editor -z redlocsym option.

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.

A symbol_name can be listed by itself in order to simply assign it to a version and/or specify its scope. Optional symbol attributes can be specified within {} brackets. Valid attributes are described below.

AUXILIARY

FILTER

FLAGS

Flag	Meaning
DIRECT	Indicates that this symbol should be directly bound to. When used with a symbol definition, this flag 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 Appendix D, "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" on page 270. 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 flag 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 flag is silently ignored.
INTERPOSE	Indicates that this symbol acts an interposer. This flag can only be used when generating a dynamic 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 Appendix D, "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" on page 270.
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 flag is silently ignored.

SIZE

TYPE

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 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" on page 146.

VALUE

Predefined Segments

The text, data, and extra segments are of primary interest, while the others serve more specialized purposes, as described below.

text

The text segment is the first segment in the process, so the link-editor will place the ELF header, and the program header array into it. This can be prevented using the HDR_NOALLOC mapfile directive.

data

extra

note

lrodata and ldata

bss

p_memsz >= p_filesz

The default assignment rules send readonly NOBITS sections to the text segment, and writable NOBITS sections to the data segment. The link-editor defines the bss segment as an alternative segment that can accept writable NOBITS sections. This segment is disabled by default, and must be explicitly enabled to be used.

Since writable NOBITS sections are easily handled as part of the data segment, the benefit of having a separate bss segment may not be immediately obvious. By convention, the process dynamic memory heap starts at the end of the final segment, which must be writable. This is usually the data segment, but if bss is enabled, it becomes the final segment. When building a dynamic executable, enabling the bss segment with an appropriate alignment can be used to enable large page assignment of the heap. For example, the following enables the bss segment and sets an alignment of 4MB:

LOAD_SEGMENT bss {
        ALIGN=0x400000;
};

Examples: Section to Segment Assignment

Example 1

1    $mapfile_version 2
2    LOAD_SEGMENT elephant {
3            ASSIGN_SECTION {
4                    IS_NAME=.data;
5                    FILE_PATH=peanuts.o;
6            };
7            ASSIGN_SECTION {
8                    IS_NAME=.data;
9                    FILE_OBJNAME=popcorn.o;
10           };
11   };
12
13   LOAD_SEGMENT monkey {
14           VADDR=0x80000000;
15           MAX_SIZE=0x4000;
16           ASSIGN_SECTION {
17                   TYPE=progbits;
18                   FLAGS=ALLOC EXECUTE;
19           };
20           ASSIGN_SECTION {
21                   IS_NAME=.data
22           };
23   };
24
25   LOAD_SEGMENT donkey {
26           FLAGS=READ EXECUTE;
27           ALIGN=0x1000;
28           ASSIGN_SECTION {
29                   IS_NAME=.data;
30           };
31   };
32
33   LOAD_SEGMENT text {
34           VADDR=0x80008000
35   };

Segment monkey (lines 13-23) has a virtual address of 0x80000000, and a maximum length of 0x4000. This segment receives all sections that are both PROGBITS and allocable-executable, as well as all sections not already in the segment elephant with the name .data. The .data sections entering the monkey segment need not be PROGBITS or allocable-executable, because they match the entrance criteria on line 20 rather than the one on line 16. This illustrates that an "and" relationship exists between the sub-attributes within a ASSIGN_SECTION attribute, while an "or" relationship exists between the different ASSIGN_SECTION attributes for a single segment.

The donkey segment (lines 25-31) is given non-default permission flags and alignment, and will accept all sections named .data. However, this segment will never be assigned any sections, and as a result, segment donkey will never appear in the output object. The reason for this is that the link-editor examines entrance criteria in the order they appear in the mapfile. In this mapfile, segment elephant accepts some .data sections, and segment takes any that are left, leaving none for donkey.

Lines 33-35 set the virtual address of the text segment to 0x80008000. The text segment is one of the standard predefined segments, as described in Predefined Segments, so this statement modifies the existing segment rather than creating a new one.

Example 2

1    $mapfile_version 2
2    HDR_NOALLOC;
3
4    LOAD_SEGMENT text {
5            VADDR=0xf0004000;
6            FLAGS=READ EXECUTE;
7            OS_ORDER=.text .rodata;
9            ASSIGN_SECTION {
10                   TYPE=PROGBITS;
11                   FLAGS=ALLOC !WRITE;
12           };
13   };
14
15   LOAD_SEGMENT data {
16           FLAGS=READ WRITE EXECUTE;
17           ALIGN=0x1000;
18           ROUND=0x1000;
19   };

The segment directive on lines 4-13 set a virtual address and permission flags for the text segment. It also specifies that sections named .text sections should be placed at the head of the segment, followed by any sections named .rodata, and that all other sections will follow these. Finally, allocable, non-writable PROGBITS sections are assigned to it.

The segment directive on lines 15-19 specifies that the data segment must be aligned on a boundary of 0x1000. This has the effect of aligning the first section within the segment at the same alignment. The length of the segment is to be rounded up to a multiple of the same value as the alignment. The segment permissions are set to read, write, and execute.

Link-Editor Internals: Section and Segment Processing

Section To Segment Assignment

Input Sections

Input sections are read from relocatable objects input to the link editor. Some are examined and processed by the link-editor, while others are simply passed to the output without examination of their contents (e.g. PROGBITS).

Output Sections

Output sections are sections that are written to the output object. Some are formed from the concatenation of sections passed through from the input objects. Others, such as symbol tables and relocation sections are generated by the link-editor itself, often incorporating information read from the input objects.

When the link-editor passes an an input section through to become an output section, it usually retains its original name. However, the link-editor can modify the name in certain circumstances. For instance, the link-editor translates input section names of the form name%XXX, dropping the '%' character and any characters following it from the output section name.

Segment Descriptors

The link-editor maintains a list of known segments. It initially contains the predefined segments, described in Predefined Segments. When a LOAD_SEGMENT, NOTE_SEGMENT, or NULL_SEGMENT mapfile directive is used to create a new segment, an additional segment descriptor for it is added to this list. The new segment goes at the end of the list following other segments of hte same type, unless explicitly ordered by setting a virtual address for it (LOAD_SEGMENT), or by using the SEGMENT_ORDER directive.

When creating the output object, the link-editor only creates program headers for the segments that receive a section. Empty segments are quietly ignored. Hence, user specified segment definitions have the power to completely replace the use of the predefined segments definitions, despite the fact that there is no explicit facility for removing a segment definition from the link-editor list.

Entrance Criteria

The set of section attributes required in order to place that section in a given segment is called an entrance criteria for the segment. A given segment can have an arbitrary number of entrance criteria.

The link-editor maintains an internal list of all defined entrance criteria. This list is used to place sections into segments, as described below. Each mapfile inserts the entrance criteria created by the ASSIGN_SECTION attribute to the LOAD_SEGMENT, NOTE_SEGMENT, or NULL_SEGMENT mapfile directive at the head of this list, in the order they are encountered in the mapfile. The entrance criteria for the built-in segments discussed in Predefined Segments are placed at the bottom of this list. Therefore, mapfile defined entrance criteria take precedence over the built in rules, and mapfiles at the end of the command line take precedence over those found at the beginning.

For each section written to the output object, the link-editor performs the following steps to place it in an output segment:

1. The attributes of the section are compared to each record in the internal entrance criteria list, starting at the head of the list and considering each entrance criteria in turn. A match occurs when every attribute in the entrance criteria matches exactly, and the segment associated with the entrance criteria is not disabled. The search stops with the first entrance criteria that matches, and the section is directed to the associated segment.

   If no Entrance Criteria match is found, the section is placed at the end of the output file after all other segments. No program header entry is created for this information. Most non-allocable sections (debug sections, etc) end up in this area.

2. When the section falls into a segment, the link-editor checks the list of existing output sections in that segment as follows.

   If the section attribute values match those of an existing output section exactly, the section is placed at the end of the list of sections associated with that output section.

   If no matching output section is found, a new output section is created with the attributes of the section being placed, and the section is placed within it. This new output section is positioned within the segment following any other output sections with the same section type, or at the end of the segment if there are none.

   Note: If the input section has a user-defined section type value between SHT_LOUSER and SHT_HIUSER, it is treated as a PROGBITS section. No method exists for naming this section type value in the mapfile, but these sections can be redirected using the other attribute value specifications (section flags, section name) in the entrance criteria.

Mapfile Directives for Predefined Segments and Entrance Criteria

Normally, section to segment assignments are done within a single segment directive. However, the predefined sections have more complex requirements, requiring their entrance criteria to be processed in a different order than the segments are laid out in memory. In order to achieve this, we use two passes, the first to define all the segments in the desired order, and the second to establish entrance criteria in an order that will achieve the desired results. It is rare for a user mapfile to require this strategy.

        # Predefined segments and entrance criteria for the Solaris link-editor
        $mapfile_version 2

        # The lrodata and ldata segments only apply to amd64 objects.
        # Establish amd64 as a convenient token for conditional input
        $if _ELF64 && _x86
        $add amd64
        $endif

        # Pass 1: Define the segments and their attributes, but
        # defer the entrance criteria details to the 2nd pass.
        LOAD_SEGMENT text {
                FLAGS = READ EXECUTE;
        };
        LOAD_SEGMENT data {
                FLAGS = READ WRITE EXECUTE;
        };
        LOAD_SEGMENT bss {
                DISABLE;
                FLAGS=DATA;
        };
        $if amd64
                LOAD_SEGMENT lrodata {
                        FLAGS = READ
                };
                LOAD_SEGMENT ldata {
                        FLAGS = READ WRITE;
                };
        $endif
        NOTE_SEGMENT note;
        NULL_SEGMENT extra;

        # Pass 2: Define ASSIGN_SECTION attributes for the segments defined
	# above, in the order we require the link-editor to evaluate them.

        # All SHT_NOTE sections go to the note segment
        NOTE_SEGMENT note {
                ASSIGN_SECTION {
                        TYPE = NOTE;
                };
        };
        $if amd64
                # Medium/large model amd64 readonly sections to lrodata
                LOAD_SEGMENT lrodata {
                        ASSIGN_SECTION {
                                FLAGS = ALLOC AMD64_LARGE;
                        };
                };
        $endif

        # text receives all readonly allocable sections
        LOAD_SEGMENT text {
                ASSIGN_SECTION {
                        FLAGS = ALLOC !WRITE;
                };
        };

        # If bss is enabled, it takes the writable NOBITS sections
        # that would otherwise end up in ldata or data.
        LOAD_SEGMENT bss {
                DISABLE;
                ASSIGN_SECTION {
                        FLAGS = ALLOC WRITE;
                        TYPE = NOBITS;
                };
        };

        $if amd64
                # Medium/large model amd64 writable sections to ldata
                LOAD_SEGMENT ldata {
                        ASSIGN_SECTION {
                                FLAGS = ALLOC WRITE AMD64_LARGE;
                        };
                        ASSIGN_SECTION {
                                TYPE = NOBITS;
                                FLAGS = AMD64_LARGE
                        };
                };
        $endif

        # Any writable allocable sections not taken above go to data
        LOAD_SEGMENT data {
                ASSIGN_SECTION {
                        FLAGS = ALLOC WRITE;
                };
        };

        # Any section that makes it to this point ends up at the
        # end of the object file in the extra segment. This accounts
        # for the bulk of non-allocable sections.
        NULL_SEGMENT extra {
                ASSIGN_SECTION;
        };