| Skip Navigation Links | |
| Exit Print View | |
|
Oracle Solaris 11.1 Linkers and Libraries Guide Oracle Solaris 11.1 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Oracle Solaris 11.1 Linkers and Libraries Guide Oracle Solaris 11.1 Information Library |
Part I Using the Link-Editor and Runtime Linker
1. Introduction to the Oracle Solaris Link Editors
5. Link-Editor Quick Reference
7. Building Objects to Optimize System Performance
LOAD_SEGMENT / NOTE_SEGMENT / NULL_SEGMENT Directives
ALIGN Attribute (LOAD_SEGMENT only)
FLAGS Attribute (LOAD_SEGMENT only)
MAX_SIZE Attribute (LOAD_SEGMENT only)
NOHDR Attribute (LOAD_SEGMENT only)
PADDR Attribute (LOAD_SEGMENT only)
ROUND Attribute (LOAD_SEGMENT only)
SIZE_SYMBOL Attribute (LOAD_SEGMENT only)
Example: Section to Segment Assignment
Example: Predefined Section Modification
Link-Editor Internals: Section and Segment Processing
Mapfile Directives for Predefined Segments and Entrance Criteria
10. Establishing Dependencies with Dynamic String Tokens
Part IV ELF Application Binary Interface
13. Program Loading and Dynamic Linking
A. Linker and Libraries Updates and New Features
The following directives are accepted by the link-editor.
Table 8-6 Mapfile Directives
|
The specific syntax for each supported mapfile directive is shown in the sections that follow.
The hardware, software, machine, and platform capabilities of a relocatable object are typically recorded within an object at compile time. The link-editor combines the capabilities of any input relocatable objects to create a final capabilities section for the output file. Capabilities can be defined within a mapfile, to augment, or completely replace, the capabilities that are supplied from input relocatable objects.
CAPABILITY [capid] {
HW = [hwcap_flag...];
HW += [hwcap_flag...];
HW -= [hwcap_flag...];
HW_1 = [value...];
HW_1 += [value...];
HW_1 -= [value...];
HW_2 = [value...];
HW_2 += [value...];
HW_2 -= [value...];
MACHINE = [machine_name...];
MACHINE += [machine_name...];
MACHINE -= [machine_name...];
PLATFORM = [platform_name...];
PLATFORM += [platform_name...];
PLATFORM -= [platform_name...];
SF = [sfcap_flag...];
SF += [sfcap_flag...];
SF -= [sfcap_flag...];
SF_1 = [value...];
SF_1 += [value...];
SF_1 -= [value...];
};
If present, the optional capid name provides a symbolic name for the object capabilities, resulting in a CA_SUNW_ID capability entry in the output object. If multiple CAPABILITY directives are seen, the capid provided by the final directive is used.
An empty CAPABILITY directive can be used to specify a capid for the object capabilities without specifying any capability values.
CAPABILITY capid;
For each type of capability, the link-editor maintains a current value (value), and a set of values to be excluded (exclude). For hardware and software capabilities, these values are bitmasks. For machine and platform capabilities, they are lists of names. Prior to processing mapfiles, the value and exclude values for all capabilities are cleared. The assignment operators work as follows.
If the “+=” operator is used, the value specified is added to the current value for that capability, and removed from the exclude values for that capability.
If the “-=” operator is used, the value specified is added to the exclude values for that capability, and removed from the current value for that capability.
If the “=” operator is used, the value specified replaces the previous value, and exclude is reset to 0. In addition, the use of “=” overrides any capabilities that are collected from input file processing.
Input objects are processed after mapfiles have been read. Capability values specified by the input objects are merged with those from the mapfiles, unless the “=” operator was used, in which case that capability is ignored when encountered in an input object. Hence, the “=” operator overrides the input objects, whereas the “+=” operator is used to augment them.
Prior to writing the resulting capability value to the output object, the link-editor subtracts any capability values specified with the “-=” operator.
To completely eliminate a given capability from the output object, it suffices to use the “=” operator and an empty value list. For example, the following suppresses any hardware capabilities contributed by the input objects:
$mapfile_version 2
CAPABILITY {
HW = ;
};
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 translates to the appropriate mask and bit. The numbered attributes (HW_1, HW_2, SF_1) 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. Where possible, use of the HW and SF attributes is recommended.
Hardware capabilities are specified as a space separated list of symbolic capability names. For SPARC platforms, hardware capabilities are defined as AV_ values in <sys/auxv_SPARC.h>. For x86 platforms, hardware capabilities are defined as AV_ values in <sys/auxv_386.h>. Mapfiles use the same names, without the AV_ prefix. For example, the x86 AV_SSE hardware capability is called SSE within a mapfile. This list can contain any of the capability names defined for the CA_SUNW_HW_ capability masks.
The HW_1 and HW_2 attributes allow the CA_SUNW_HW_1 and CA_SUNW_HW_2 capability masks to be specified directly as numeric values, or as the symbolic hardware capability names that correspond to that mask.
The MACHINE attribute specifies the machine hardware names for the systems that the object can execute upon. The machine hardware name of a system can be displayed by the utility uname(1) with the -m option. A CAPABILITY directive can specify multiple machine names. Each name results in a CA_SUNW_MACH capability entry in the output object.
The PLATFORM attribute specifies the platform names for the systems that the object can execute upon. The platform name of a system can be displayed by the utility uname(1) with the -i option. A CAPABILITY directive can specify multiple platform names. Each name results in a CA_SUNW_PLAT capability entry in the output object.
Software capabilities are specified as a space separated list of symbolic capability names. Software capabilities are defined as SF1_SUNW_ values in <sys/elf.h>. Mapfiles use the same names, without the SF1_SUNW_ prefix. For example, the SF1_SUNW_ADDR32 software capability is called ADDR32 in a mapfile. This list can contain any of the capability names defined for the CA_SUNW_SF_1.
The SF_1 attribute allows the CA_SUNW_SF_1 capability mask to be specified directly as a numeric value, or as symbolic software capability names that correspond to that mask.
When linking against a sharable object, the symbols from all versions exported by the object are normally available for use by the link-editor. The DEPEND_VERSIONS directive is used to limit access to specified versions only. Restricting version access can be used to ensure that a given output object does not use newer features that might not be available on an older version of the system.
A DEPEND_VERSIONS directive has the following syntax.
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 using 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.
The ALLOW attribute specifies that the specified version, and versions inherited by that version, are available to the link-editor for resolving symbols in the output object. The link-editor will add a requirement for the highest version used in the inheritance chain containing this version to the output object requirements.
REQUIRE adds the specified version to the output object requirements, whether or not the version is actually required to satisfy the link operation.
Every ELF object has an ELF header at offset 0 in the file. Executable and sharable objects also contain program headers, which are accessed through the ELF header. The link-editor normally arranges for these items to be included as part of the first loadable segment. The information contained in these headers is therefore visible within the mapped image, and is typically used by the runtime linker. The HDR_NOALLOC directive prevents this.
HDR_NOALLOC;
When HDR_NOALLOC is specified, the ELF header and program header array still appear at the start of the resulting output object file, but are not contained in a loadable segment, and virtual address calculations for the image start at the first section of the first segment rather than at the base of the ELF header.
The PHDR_ADD_NULL directive causes the link-editor to add a specified number of additional program header entries of type PT_NULL at the end of the program header array. Extra PT_NULL entries can be used by post processing utilities.
PHDR_ADD_NULL = value;
value must be a positive integer value, and gives the number of extra PT_NULL entries to create. All fields of the resulting program header entries will be set to 0.
A segment is a contiguous portion of the output object that contains sections. The mapfile segment directives allow the specification of three different segment types.
LOAD_SEGMENT
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.
NOTE_SEGMENT
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.
NULL_SEGMENT
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.
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.
All three segment directives share a common set of core attributes. Substituting one of LOAD_SEGMENT, NOTE_SEGMENT, NULL_SEGMENT for directive, a segment declaration is as follows.
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 of these additional attributes is as follows.
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 segment attributes. Empty segments are declared as follows.
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.
The ALIGN attribute is used to specify the alignment for a loadable segment. The value specified is set in the p_align field of the program header corresponding to the segment. Segment alignment is used in calculating the virtual address of the beginning of the segment.
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. When PADDR or VADDR is specified, the p_align field of the corresponding program header will be set to the default value.
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.
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.
TYPE
Specifies an ELF section_type, which can be any of the SHT_ constants defined in <sys/elf.h>, with the SHT_ prefix removed. (e.g. PROGBITS, SYMTAB, NOBITS).
FLAGS
The FLAGS attribute uses section_flags to specify section attributes as a space separated list of one or more of the values given in Table 8-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 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.
Table 8-7 Section FLAGS Values
|
The DISABLE attribute causes the link-editor to ignore the segment. No sections will be assigned to a disabled segment. The segment is automatically re-enabled when referenced by a following segment directive. Hence, an empty reference suffices to re-enable a disabled section.
segment segment_name;
The FLAGS attribute specifies segment permissions as a space separated list of the permissions in Table 8-3. By default, user defined segments receive READ, WRITE, and EXECUTE permissions. The default flags for the predefined segments described in Predefined Segments are supplied by the link-editor, and in some cases can be platform-dependent.
There are three forms allowed.
FLAGS = segment_flags...;
FLAGS += segment_flags...;
FLAGS -= segment_flags...;
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 link-editor normally places output sections into the segment in the order they are encountered. Similarly, the input sections that make up the output section are placed in the order they are encountered. The IS_ORDER attribute can be used to alter this default placement of input sections. IS_ORDER specifies a space separated list of entrance criterion names (assign_name). Sections matched by one of these entrance criteria are placed at the head of the output section, sorted in the order given by IS_ORDER. Sections matched by entrance criteria not found in the IS_ORDER list are placed following the sorted sections, in the order they are encountered.
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 the % 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;
};
No matter the order in which these three functions are found in the source code, or encountered by the link-editor, their order in the output object text segment will be foo(), bar(), and main().
By default, the link-editor will allow a segment to grow to the size required by the contents of the segment. The MAX_SIZE attribute can be used to specify a maximum size for the segment. If MAX_SIZE is set, the link-editor will generate an error if the segment grows beyond the specified size.
If a segment with the NOHDR attribute set becomes the first loadable segment in the output object, the ELF and program headers will not be included within the segment.
The NOHDR attribute differs from the top level HDR_NOALLOC directive in that HDR_NOALLOC 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 B, System V Release 4 (Version 1) Mapfiles for more details.
The HDR_NOALLOC directive is recommended in preference to the segment NOHDR attribute.
The link-editor normally places output sections into the segment in the order they are encountered. The OS_ORDER attribute can be used to alter this default placement of output sections. OS_ORDER specifies a space separated list of output section names (section_name). The listed sections are placed at the head of the segment, sorted in the order given by OS_ORDER. Sections not listed in OS_ORDER are placed following the sorted sections, in the order they are encountered.
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.
The PADDR attribute is used to specify an explicit physical address for the segment. The value specified is set in the p_addr field of the program header corresponding to the segment. By default, the link-editor sets the physical address of segments to 0, as this field has no meaning for user mode objects, and is primarily of interest non-userland objects such as operating system kernels.
The ROUND attribute is used to specify that the size of the segment should be rounded up to the given value. The rounding value specified must be a power of 2. By default, the link-editor sets the rounding factor of a segment to 1, meaning that the segment size is not rounded up.
The SIZE_SYMBOL attribute defines a space separated list of section size symbol names to be created by the link-editor. A size symbol is a global-absolute symbol that represents the size, in bytes, of the segment. These symbols can be referenced in your object files. In order to access the symbol within your code, you should ensure that symbol_name is a legal identifier in that language. The symbol naming rules for the C programming language are recommended, as such symbols are likely to be accessible from any other language.
The “=” form of assignment can be used to establish an initial value, and 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.
The VADDR attribute is used to specify an explicit virtual address for the segment. The value specified is set in the p_vaddr field of the program header corresponding to the segment. By default, the link-editor assigns virtual addresses to segments as the output file is created.
The SEGMENT_ORDER directive is used to specify a non-default ordering for segments in the output object.
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.
Loadable segments with explicit addresses set with the VADDR attribute of the LOAD_SEGMENT directive, sorted by address.
Segments ordered using the SEGMENT_ORDER directive, in the order specified.
Loadable segments without explicit addresses, not found in the SEGMENT_ORDER list.
Note segments without explicit addresses, not found in the SEGMENT_ORDER list.
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 read-only, 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.
Unless the HDR_NOALLOC directive is specified, the link-editor enforces the requirement that the first segment must be a loadable segment, and not a note or null segment. HDR_NOALLOC cannot be used for userland objects, and is therefore of little practical use. This feature is used when building operating system kernels.
The STACK directive specifies attributes of the process stack.
STACK {
FLAGS = segment_flags...;
FLAGS += segment_flags...;
FLAGS -= segment_flags...;
};
The FLAGS attribute specifies a white space separated list of segment permissions consisting of any of the values described in Table 8-3.
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 is specified using the segment flag name STACK.
On some platforms, the ABI mandated default permissions include EXECUTE. EXECUTE 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.
The STUB_OBJECT directive informs the link-editor that the object described by the mapfile can be built as a stub object.
STUB_OBJECT;
A stub shared object is built entirely from the information in the mapfiles supplied on the command line. When the -z stub option is specified to build a stub object, the presence of the STUB_OBJECT directive in a mapfile is required, and the link-editor uses the information in symbol ASSERT attributes to create global symbols that match those of the real object.
The SYMBOL_SCOPE and SYMBOL_VERSION directives are used to specify the scope and attributes of global symbols. SYMBOL_SCOPE operates within the context of the unnamed base symbol version, while SYMBOL_VERSION is used to gather symbols into explicitly named global versions. The SYMBOL_VERSION directive allows the creation of stable interfaces that support object evolution in a backward compatible manner.
SYMBOL_VERSION has the following syntax.
SYMBOL_VERSION version_name {
symbol_scope:
*;
symbol_name;
symbol_name {
ASSERT = {
ALIAS = symbol_name;
BINDING = symbol_binding;
TYPE = symbol_type;
SIZE = size_value;
SIZE = size_value[count];
VALUE = value;
};
AUXILIARY = soname;
FILTER = soname;
FLAGS = symbol_flags...;
SIZE = size_value;
SIZE = size_value[count];
TYPE = symbol_type;
VALUE = value;
};
} [inherited_version_name...];
SYMBOL_SCOPE does not accept version names, but is otherwise identical.
SYMBOL_SCOPE {
...
};
In a SYMBOL_VERSION directive, version_name provides a label for this set of symbol definitions. This label identifies a version definition within the output object. One or more inherited versions (inherited_version_name) can be specified, separated by white space, in which case the newly defined version inherits from the versions named. See Chapter 9, Interfaces and Versioning.
symbol_scope defines the scope of symbols in a SYMBOL_SCOPE or SYMBOL_VERSION 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.
Table 8-8 Symbol Scope Types
|
A symbol_name is the name of a symbol. This name can result in a symbol definition, or a symbol reference, depending on any qualifying attributes. In the simplest form, without any qualifying attributes, a symbol reference is created. This reference is exactly the same as would be generated using the -u option discussed in Defining Additional Symbols with the -u option. Typically, if the symbol name is followed by any qualifying attributes, then a symbol definition is generated using the associated attributes.
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.
If a SYMBOL_VERSION directive is specified, or if auto-reduction is specified with either SYMBOL_VERSION or SYMBOL_SCOPE, then versioning information is recorded in the image created. If this image is an executable or shared object, then any symbol reduction is also applied.
If the image being created is a relocatable object, then by default, no symbol reduction is applied. In this case, any symbol reductions are recorded as part of the versioning information. These reductions are applied when the relocatable object is finally used to generate an executable or shared object. The link-editor's -B reduce option can be used to force symbol reduction when generating a relocatable object.
A more detailed description of the versioning information is provided in Chapter 9, Interfaces and Versioning.
Note - To ensure interface definition stability, no wildcard expansion is provided for defining symbol names.
A symbol_name can be listed by itself in order to simply assign the symbol to a version and/or specify its scope. Optional symbol attributes can be specified within {} brackets. Valid attributes are described below.
The ASSERT attribute is used to specify the expected characteristics of the symbol. The link-editor compares the symbol characteristics that result from the link-edit to those given by ASSERT attributes. If the real and asserted attributes do not agree, a fatal error is issued and the output object is not created.
The interpretation of the ASSERT attribute is dependent on whether the STUB_OBJECT directive or -z stub command line option are used. The three possible cases are as follows.
ASSERT attributes are not required when the STUB_OBJECT directive is not used. However, if ASSERT attributes exist, their attributes are verified against the real values collected with the link-edit. Should any ASSERT attributes not match their associated real values, the link-edit terminates unsuccessfully.
When the STUB_OBJECT directive is used, and the -z stub command line option is specified, the link-editor uses the ASSERT directives to define the attributes of the global symbols provided by the object. See Stub Objects.
When the STUB_OBJECT directive is used, and -z stub command line option is not specified, the link-editor requires that all global data in the resulting object have an associated ASSERT directive that declares it as data and supplies a size. In this mode, if the TYPE ASSERT attribute is not specified, GLOBAL is assumed. Similarly, if SH_ATTR is not specified, a default value of BITS is assumed. These defaults ensure that the data attributes of the stub and real objects are compatible. The resulting ASSERT statements are evaluated in the same manner as in the first case above. See STUB_OBJECT Directive.
ASSERT accepts the following.
ALIAS
Defines an alias for a previously defined symbol. An alias symbol has the same type, value, and size as the main symbol. The ALIAS attribute cannot be used with the TYPE, SIZE, and SH_ATTR attributes. When ALIAS is specified, the type, size, and section attributes are obtained from the alias symbol.
BIND
Specifies an ELF symbol_binding, which can be any of the STB_ values defined in <sys/elf.h>, with the STB_ prefix removed. For example, GLOBAL, or WEAK.
TYPE
Specifies an ELF symbol_type, which can be any of the STT_ constants defined in <sys/elf.h>, with the STT_ prefix removed. For example, OBJECT, COMMON, or FUNC. In addition, for compatibility with other mapfile usage, FUNCTION and DATA can be specified for STT_FUNC and STT_OBJECT, respectively. TYPE cannot be used with ALIAS.
SH_ATTR
Specifies attributes of the section associated with the symbol. The section_attributes that can be specified are given in Table 8-9. SH_ATTR cannot be used with ALIAS.
SIZE
Specifies the expected symbol size. SIZE cannot be used with ALIAS. The syntax for the size_value argument is as described in the discussion of the SIZE attribute. See SIZE Attribute.
VALUE
Specifies the expected symbol value.
Table 8-9 SH_ATTR Values
|
Indicates that this symbol is an auxiliary filter on the shared object name (soname). See Generating Auxiliary Filters.
Indicates that this symbol is a filter on the shared object name. See Generating Standard Filters. Filter symbols do not require any backing implementation to be provided from an input relocatable object. Therefore, use this directive together with defining the symbol's type, to create an absolute symbol table entry.
symbol_flags specify symbol attributes as a space separated list of one or more of the following values.
Table 8-10 Symbol FLAG Values
|
Sets the size attribute. This attribute results in the creation of a symbol definition.
The size_value argument can be a numeric value, or it can be the symbolic name addrsize. addrsize represents the size of a machine word capable of holding a memory address. The link-editor substitutes the value 4 for addrsize when building 32-bit objects, and the value 8 when building 64-bit objects. addrsize is useful for representing the size of pointer variables and C variables of type long, as it automatically adjusts for 32 and 64-bit objects without requiring the use of conditional input.
The size_value argument can be optionally suffixed with a count value, enclosed in square brackets. If count is present, size_value and count are multiplied together to obtain the final size value.
The symbol type attribute. This attribute can be either COMMON, DATA, or FUNCTION. COMMON results in a tentative symbol definition. DATA and FUNCTION result in a section symbol definition or an absolute symbol definition. See Symbol Table Section.
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 following 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.
Indicates the value attribute. This attribute results in the creation of a symbol definition.
|