JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris 11.1 Linkers and Libraries Guide     Oracle Solaris 11.1 Information Library
search filter icon
search icon

Document Information


Part I Using the Link-Editor and Runtime Linker

1.  Introduction to the Oracle Solaris Link Editors

2.  Link-Editor

Invoking the Link-Editor

Direct Invocation

Using a Compiler Driver

Cross Link-Editing

Specifying the Link-Editor Options

Input File Processing

Archive Processing

Shared Object Processing

Linking With Additional Libraries

Library Naming Conventions

Linking With a Mix of Shared Objects and Archives

Position of an Archive on the Command Line

Directories Searched by the Link-Editor

Directories Searched by the Runtime Linker

Initialization and Termination Sections

Symbol Processing

Symbol Visibility

Symbol Resolution

Simple Resolutions

Complex Resolutions

Fatal Resolutions

Undefined Symbols

Generating an Executable Output File

Generating a Shared Object Output File

Weak Symbols

Tentative Symbol Order Within the Output File

Defining Additional Symbols

Defining Additional Symbols with the -u option

Defining Symbol References

Defining Absolute Symbols

Defining Tentative Symbols

Augmenting a Symbol Definition

Reducing Symbol Scope

Symbol Elimination

External Bindings

String Table Compression

Generating the Output File

Identifying Capability Requirements

Identifying a Platform Capability

Identifying a Machine Capability

Identifying Hardware Capabilities

Identifying Software Capabilities

Creating a Family of Symbol Capabilities Functions

Creating a Family of Symbol Capabilities Data Items

Converting Object Capabilities to Symbol Capabilities

Exercising a Capability Family

Relocation Processing

Displacement Relocations

Stub Objects

Ancillary Objects

Debugger Access and Use of Ancillary Objects

Parent Objects

Debugging Aids

3.  Runtime Linker

4.  Shared Objects

Part II Quick Reference

5.  Link-Editor Quick Reference

Part III Advanced Topics

6.  Direct Bindings

7.  Building Objects to Optimize System Performance

8.  Mapfiles

9.  Interfaces and Versioning

10.  Establishing Dependencies with Dynamic String Tokens

11.  Extensibility Mechanisms

Part IV ELF Application Binary Interface

12.  Object File Format

13.  Program Loading and Dynamic Linking

14.  Thread-Local Storage

Part V Appendices

A.  Linker and Libraries Updates and New Features

B.  System V Release 4 (Version 1) Mapfiles


Ancillary Objects

By default, objects contain both allocable and non-allocable sections. Allocable sections are the sections that contain executable code and the data needed by that code at runtime. Non-allocable sections contain supplemental information that is not required to execute an object at runtime. These sections support the operation of debuggers and other observability tools. The non-allocable sections in an object are not loaded into memory at runtime by the operating system, and so, they have no impact on memory use or other aspects of runtime performance no matter their size.

For convenience, both allocable and non-allocable sections are normally maintained in the same file. However, there are situations in which it can be useful to separate these sections.

Traditionally, objects have been stripped of non-allocable sections in order to address these issues. Stripping is effective, but destroys data that might be needed later. The Solaris link-editor can instead write non-allocable sections to an ancillary object. This feature is enabled with the -z ancillary command line option.

$ ld ... -z ancillary[=outfile] ...

By default, the ancillary file is given the same name as the primary output object, with a .anc file extension. However, a different name can be provided by providing an outfile value to the -z ancillary option.

When -z ancillary is specified, the link-editor performs the following actions.

This organization makes it possible to acquire a full list of section headers, a complete symbol table, and a complete list of the primary and ancillary objects from either of the primary or ancillary objects.

The following example illustrates the underlying implementation of ancillary objects. An ancillary object is created by adding the -z ancillary command line option to an otherwise normal compilation. The file utility shows that the result is an executable named a.out, and an associated ancillary object named a.out.anc.

$ cat hello.c
#include <stdio.h>

main(int argc, char **argv) 
        (void) printf("hello, world\n");
        return (0);
$ cc -g -zancillary hello.c
$ file a.out a.out.anc
a.out: ELF 32-bit LSB executable 80386 Version 1 [FPU], dynamically
       linked, not stripped, ancillary object a.out
a.out.anc: ELF 32-bit LSB ancillary 80386 Version 1, primary object a.out
$ ./a.out
hello world

The resulting primary object is an ordinary executable that can be executed in the usual manner. It is no different at runtime than an executable built without the use of ancillary objects, and then stripped of non-allocable content using the strip or mcs commands.

As previously described, the primary object and ancillary objects contain the same section headers. To see how this works, it is helpful to use the elfdump utility to display these section headers and compare them. The following table shows the section header information for a selection of headers from the previous link-edit example.

Section Name
Primary Flags
Ancillary Flags
Primary Size
Ancillary Size

The data for most sections is only present in one of the two files, and absent from the other file. The SHF_SUNW_ABSENT section header flag is set when the data is absent. The data for allocable sections needed at runtime are found in the primary object. The data for non-allocable sections used for debugging but not needed at runtime are placed in the ancillary file. A small set of non-allocable sections are fully present in both files. These are the .SUNW_ancillary section used to relate the primary and ancillary objects together, the section name string table .shstrtab, as well as the symbol table.symtab, and its associated string table .strtab.

It is possible to strip the symbol table from the primary object. A debugger that encounters an object without a symbol table can use the .SUNW_ancillary section to locate the ancillary object, and access the symbol contained within.

The primary object, and all associated ancillary objects, contain a .SUNW_ancillary section that allows all the objects to be identified and related together.

$ elfdump -T SUNW_ancillary a.out a.out.anc
Ancillary Section:  .SUNW_ancillary
     index  tag                    value
       [0]  ANC_SUNW_CHECKSUM     0x8724              
       [1]  ANC_SUNW_MEMBER       0x1         a.out
       [2]  ANC_SUNW_CHECKSUM     0x8724         
       [3]  ANC_SUNW_MEMBER       0x1a3       a.out.anc
       [4]  ANC_SUNW_CHECKSUM     0xfbe2              
       [5]  ANC_SUNW_NULL         0                   

Ancillary Section:  .SUNW_ancillary
     index  tag                    value
       [0]  ANC_SUNW_CHECKSUM     0xfbe2              
       [1]  ANC_SUNW_MEMBER       0x1         a.out
       [2]  ANC_SUNW_CHECKSUM     0x8724              
       [3]  ANC_SUNW_MEMBER       0x1a3       a.out.anc
       [4]  ANC_SUNW_CHECKSUM     0xfbe2              
       [5]  ANC_SUNW_NULL         0          

The ancillary sections for both objects contain the same number of elements, and are identical except for the first element. Each object, starting with the primary object, is introduced with a MEMBER element that gives the file name, followed by a CHECKSUM that identifies the object. In this example, the primary object is a.out, and has a checksum of 0x8724. The ancillary object is a.out.anc, and has a checksum of 0xfbe2. The first element in a .SUNW_ancillary section, preceding the MEMBER element for the primary object, is always a CHECKSUM element, containing the checksum for the file being examined.

Debugger Access and Use of Ancillary Objects

Debuggers and other observability tools must merge the information found in the primary and ancillary object files in order to build a complete view of the object. This is equivalent to processing the information from a single file. This merging is simplified by the primary object and ancillary objects containing the same section headers, and a single symbol table.

The following steps can be used by a debugger to assemble the information contained in these files.

  1. Starting with the primary object, or any of the ancillary objects, locate the .SUNW_ancillary section. The presence of this section identifies the object as part of an ancillary group, contains information that can be used to obtain a complete list of the files and determine which of those files is the one currently being examined.

  2. Create a section header array in memory, using the section header array from the object being examined as an initial template.

  3. Open and read each file identified by the .SUNW_ancillary section in turn. For each file, fill in the in-memory section header array with the information for each section that does not have the SHF_SUNW_ABSENT flag set.

The result will be a complete in-memory copy of the section headers with pointers to the data for all sections. Once this information has been acquired, the debugger can proceed as it would in the single file case, to access and control the running program.

Note - The ELF definition of ancillary objects provides for a single primary object, and an arbitrary number of ancillary objects. At this time, the Oracle Solaris link-editor only produces a single ancillary object containing all non-allocable sections. This may change in the future. Debuggers and other observability tools should be written to handle the general case of multiple ancillary objects.