LD(1)LD(1)NAME
ld, ld.so - link editor, dynamic link editor
SYNOPSIS
ld [ -align datum ] [ -assert assertion-keyword ]
[ -A name ] [ -Bbinding-keyword ] [ -d ] [ -dc ]
[ -dp ] [ -D hex ] [ -e entry ] [ -lx ] [ -Ldir ]
[ -M ] [ -n ] [ -N ] [ -o name ] [ -p ] [ -r ] [ -s ] [ -S ]
[ -t ] [ -T[text] hex ] [ -Tdata hex ] [ -u name ]
[ -x ] [ -X ] [ -ysym ] [ -z ] filename ...
DESCRIPTION
ld combines object programs to create an executable file or another
object program suitable for further ld processing (with the -r option).
The object modules on which ld operates are specified on the command
line, and can be:
· simple object files, which typically end in the .o suffix,
and are referred to as “dot-oh” files
· ar(1V) library archives (.a), or “libraries”
· dynamically-bound, sharable object files (.so), are also
referred to as “shared libraries,” which are created from
previous ld executions.
Unless an output file is specified, ld produces a file named a.out.
This file contains the object files given as input, appropriately com‐
bined to form an executable file.
OPTIONS
When linking debugging or profiling objects, include the -g or -pg
option (see cc(1V)), as appropriate, in the ld command.
Options should appear before filenames, except for abbreviated library
names specified with -l options, and some binding control options spec‐
ified by -B (which can appear anywhere in the line).
-align datum
Force the global uninitialized data symbol datum (usually a FOR‐
TRAN common block) to be page-aligned. Increase its size to a
whole number of pages, and place its first byte at the start of
a page.
-assert assertion-keyword
Check an assertion about the link editing being performed. The
assertion desired is specified by the assertion-keyword string.
ld is silent if the assertion holds, else it yields a diagnostic
and aborts. Valid assertion-keyword's and their interpretations
are:
definitions If the resulting program were run now,
there would be no run-time undefined sym‐
bol diagnostics. This assertion is set by
default.
nodefinitions Permit the successful linking of a program
with unresolved references.
nosymbolic There are no symbolic relocation items
remaining to be resolved.
pure-text The resulting load has no relocation items
remaining in its text.
-A name
Incremental loading: linking is to be done in a manner so that
the resulting object may be read into an already executing pro‐
gram. name is the name of a file whose symbol table is taken as
a basis on which to define additional symbols. Only newly
linked material is entered into the text and data portions of
a.out, but the new symbol table will reflect all symbols defined
before and after the incremental load. This argument must
appear before any other object file in the argument list. One
or both of the -T options may be used as well, and will be taken
to mean that the newly linked segment will commence at the cor‐
responding addresses (which must be a multiple of the page
size). The default value is the old value of _end.
-Bbinding-keyword
Specify allowed binding times for the items which follow.
Allowed values of binding-keyword are:
dynamic Allow dynamic binding: do not resolve symbolic
references, allow creation of run-time symbol and
relocation environment. -Bdynamic is the
default. When -Bdynamic is in effect, all
sharable objects encountered until a succeeding
-Bstatic may be added dynamically to the object
being linked. Non-sharable objects are bound
statically.
nosymbolic Do not perform symbolic relocation, even if other
options imply it.
static Bind statically. Opposite of -Bdynamic. Implied
when either -n or -N is specified. Influences
handling of all objects following its specifica‐
tion on a command line until the next -Bdynamic.
symbolic Force symbolic relocation. Normally implied if
an entry point has been specified with -e, or if
dynamic loading is in effect.
-d Force common storage for uninitialized variables and other com‐
mon symbols to be allocated in the current ld run, even when the
-r flag is present (which would otherwise postpone this binding
until the final linking phase).
-dc Do -d, but also copy initialized data referenced by this program
from shared objects.
-dp Force an alias definition of undefined procedure entry points.
Used with dynamic binding to improve sharing and the locality of
run-time relocations.
-D hex Pad the data segment with zero-valued bytes to make it hex bytes
long.
-e entry
Define the entry point: the entry argument is made the name of
the entry point of the loaded program. Implies -Bsymbolic.
-lx[.v]
This option is an abbreviation for the library name libx.a,
where x is a string. ld searches for libraries first in any
directories specified with -L options, then in the standard
directories /lib, /usr/lib, and /usr/local/lib. A library is
searched when its name is encountered, so the placement of a -l
is significant. If a dynamically loadable object is found, and
-Bdynamic is in effect at that point on the command line, then
ld prepares to access the object for relocation at run-time. In
such a case, the optional .v suffix can be used to indicate a
specific library version.
-Ldir Add dir to the list of directories in which to search for
libraries. Directories specified with -L are searched before
the standard directories, /lib, /usr/lib, and /usr/local/lib.
When building a program in which one or more objects are loaded
when -Bdynamic is in effect, those directories specified by -L
options will be “remembered” for use at execution time. This
permits the construction of software that uses shared objects as
libraries not residing in the standard locations and avoids
requiring the specification of the LD_LIBRARY_PATH environment
variable in order to execute such software. Note that such
directories are retained in exactly the form specified in the
option, which means that relative directory specifications
(i.e., not beginning with “/”) will be evaluated relative to the
current directory when the program is run, not just during the
operation of ld.
-M Produce a primitive load map, listing the names of the files
which will be loaded.
-n Arrange (by giving the output file a 0410 “magic number”) that
when the output file is executed, the text portion will be read-
only with the data areas placed at the beginning of the next
address boundary following the end of the text. Implies
-Bstatic.
-N Do not make the text portion read-only. (Use “magic number”
0407.) Implies -Bstatic.
-o name
name is made the name of the ld output file, instead of a.out.
-p Arrange for the data segment to begin on a page boundary, even
if the text is not shared (with the -N option).
-r Generate relocation bits in the output file so that it can be
the subject of another ld run. This flag also prevents final
definitions from being given to common symbols, and suppresses
the “undefined symbol” diagnostics.
-s Strip the output, that is, remove the symbol table and reloca‐
tion bits to save space (but impair the usefulness of the debug‐
gers). This information can also be removed by strip(1).
-S Strip the output by removing all symbols except locals and glob‐
als.
-t Trace: display the name of each file as it is processed.
-T[text]hex
Start the text segment at location hex. Specifying -T is the
same as using the -Ttext option.
-Tdata hex
Start the data segment at location hex. This option is only of
use to programmers wishing to write code for PROMs, since the
resulting code cannot be executed by the system.
-u name
Enter name as an undefined symbol. This is useful for loading
wholly from a library, since initially the symbol table is empty
and an unresolved reference is needed to force the loading of
the first routine.
-x Preserve only global (non-.globl) symbols in the output symbol
table; only enter external symbols. This option saves some
space in the output file.
-X Record local symbols, except for those whose names begin with L.
This option is used by cc to discard internally generated labels
while retaining symbols local to routines.
-ysym Display each file in which sym appears, its type and whether the
file defines or references it. Many such options may be given
to trace many symbols. It is usually necessary to begin sym
with an `_', as external C, FORTRAN and Pascal variables begin
with underscores.
-z Arrange for the process demand paged from the resulting exe‐
cutable file (0413 “magic number”). This is the default.
Results in a (32-byte) header on the output file followed by
text and data segments, each of which has a multiple of page-
size bytes (being padded out with null characters in the file if
necessary). With this format the first few BSS segment symbols
may actually end up in the data segment; this is to avoid wast‐
ing the space resulting from rounding the data segment size.
Implies -Bdynamic.
USAGE
Command Line Processing
In general, options should appear ahead of the list of files to
process. Unless otherwise specified, the effect of an option covers
all of ld operations, independent of that option's placement on the
command line. Exceptions to this rule include some of the binding con‐
trol options specified by `-B' and the abbreviated library-names speci‐
fied by `-l'. These may appear anywhere, and their influence is depen‐
dent upon their location. Some options may be obtained from environ‐
ment variables, such options are interpreted before any on the command
line (see ENVIRONMENT, below).
Object File Processing
The files specified on the command line are processed in the order
listed. Information is extracted from each file, and concatenated to
form the output. The specific processing performed on a given file
depends upon whether it is a simple object file, a library archive, or
a shared library.
Simple object (.o) files are concatenated to the output as they are
encountered.
Library archive (.a) files are searched exactly once each, as each is
encountered; only those archive entries matching an unresolved external
reference are extracted and concatenated to the output. If a member of
an archive references a symbol defined by another member of that same
archive, the member making the reference must appear before the member
containing the definition.
On Sun386i, a library contains a dictionary of symbols, On other Sun
systems, processing library archives through ranlib(1) provides this
dictionary. In addition, you can use lorder(1), in combination with
tsort(1) to place library members in calling order (see lorder(1) for
details), or both (for fastest symbol lookup). The first member of an
archived processed by ranlib has the reserved name of __.SYMDEF, which
ld takes to be the dictionary of all symbols defined by members of the
archive.
Sharable objects (.so) are scanned for symbol definitions and refer‐
ences, but are not normally included in the output from ld, except in
cases where a shared library exports initialized data structures and
the -dc option is in effect. However, the occurrence of each sharable
object file in the ld command line is noted in the resulting executable
file; this notation is utilized by an execution-time variant of ld,
ld.so, for deferred and dynamic loading and binding during execution.
See Execution-Time Loading, below, for details.
The -l option specifies a short name for an object file or archive used
as a library. The full name of the object file is derived by adding
the prefix lib and a suffix of either .a or .so[.v] to indicate an
ar(1V) archive or a shared library, respectively. The specific suffix
used is determined through rules discussed in Binding and Relocation
Semantics, below.
ld searches for the desired object file through a list of directories
specified by -L options, the environment variable LD_LIBRARY_PATH, and
finally, the built-in list of standard library directories: /lib,
/usr/lib, and /usr/local/lib.
Binding and Relocation Semantics
The manner in which ld processes a given object file is dependent in
part upon the “binding mode” in which it is operating at the time the
file is encountered. This binding mode is specified by the -B flag,
which takes the keyword arguments:
dynamic Allow dynamic binding, do not resolve symbolic refer‐
ences, and allow creation of execution-time symbol and
relocation information. This is the default setting.
static Force static binding, implied by options that generate
non-sharable executable formats.
-Bdynamic and -Bstatic may be specified several times, and may be used
to toggle each other on and off. Like -l, the influence of each
depends upon its location within the command line. When -Bdynamic is
in effect, -l searches may be satisfied by the first occurrence of
either form of library (.so or .a), but if both are encountered, the
.so form is preferred. When -Bstatic is in effect, ld refuses to use
any .so libraries it encounters; it continue searching for the .a form.
Furthermore, an explicit request to load a .so file is treated as an
error.
After ld has processed all input files and command line options, the
form of the output it produces is based on the information provided in
both. ld first tries to reduce all symbolic references to relative
numerical offsets within the executable it is building. To perform
this “symbolic reduction,” ld must be able to determine that:
· all information relating to the program has been provided, in
particular, no .so is to be added at execution time; and/or
· the program has an entry point, and symbolic reduction can be
performed for all symbols having definitions existing in the
material provided.
It should be noted that uninitialized “common” areas (for example,
uninitialized C globals) are allocated by the link editor after it has
collected all references. In particular, this allocation can not occur
in a program that still requires the addition of information contained
in a .so file, as the missing information may affect the allocation
process. Initialized “commons” however, are allocated within the exe‐
cutable in which their definition appears.
After ld has performed all the symbolic reductions it can, it attempts
to transform all relative references to absolute addresses. ld is able
to perform this “relative reduction” only if it has been provided some
absolute address, either implicitly through the specification of an
entry point, or explicitly through ld command-line options. If, after
performing all the reductions it can, there are no further relocations
or definitions to perform, then ld has produced a completely linked
executable.
Execution-Time Loading
In the event that one or more reductions can not be completed, the exe‐
cutable will require further link editing at execution time in order to
be usable. Such executables contain an data structure identified with
the symbol __DYNAMIC. An incompletely linked “main” program should be
linked with a “bootstrap” routine that invokes ld.so, which uses the
information contained in the main program's __DYNAMIC to assemble the
rest of the executables constituting the entire program. A standard
Sun compilation driver (such as cc(1V)) automatically includes such a
module in each “main” executable.
When ld.so is given control on program startup, it finds all .so files
specified when the program was constructed (and all .so's on which they
depend), and loads them into the address space. The algorithm by which
such files are found mimics that used when ld is run, and like ld, can
be influenced by the setting of LD_LIBRARY_PATH and any -L options
specified to ld when the program was built. ld.so then completes all
remaining relocations, with the exception of procedure call reloca‐
tions; failure to resolve a given non-procedural relocation results in
termination of the program with an appropriate diagnostic.
Procedure relocations are resolved when the referencing instruction is
first executed. It should be noted that it is possible for “undefined
symbol” diagnostics to be produced during program execution if a given
target is not defined when referenced.
Although it is possible for binding errors to occur at execution-time,
such an occurrence generally indicates something wrong in the mainte‐
nance of shared objects. ld's -assert nodefinitions function (on by
default) checks at ld-time whether or not an execution-time binding
error would occur.
Version Handling for Shared Libraries
To allow the independent evolution of .so's used as libraries and the
programs which use them, ld's handling of .so files found through -l
options involves the retention and management of version control infor‐
mation. The .so files used as such “shared libraries” are post-fixed
with a Dewey-decimal format string describing the version of the
“library” contained in the file.
The first decimal component is called the library's “major version”
number, and the second component its “minor version” number. When ld
records a .so used as a library, it also records these two numbers in
the database used by ld.so at execution time. In turn, ld.so uses
these numbers to decide which of multiple versions of a given library
is “best” or whether any of the available versions are acceptable. The
rules are:
· Major Versions Identical: the major version used at execution
time must exactly match the version found at ld-time. Fail‐
ure to find an instance of the library with a matching major
version causes a diagnostic to be issued and the program's
execution to be terminated.
· Highest Minor Version: in the presence of multiple instances
of libraries that match the desired major version, ld.so uses
the highest minor version it finds. However, if the highest
minor version found at execution time is less than the ver‐
sion found at ld-time, a warning diagnostic is issued; pro‐
gram execution continues.
The semantics of version numbers are such that major version numbers
should be changed whenever interfaces are changed. Minor versions
should be changed to reflect compatible updates to libraries, and pro‐
grams will silently favor the highest compatible version they can
obtain.
Special Symbols
A number of symbols have special meanings to ld and programs should not
define these symbols. The symbols described below are those actually
seen by ld. Note: C and several other languages prepend symbols they
use with `_'.
_etext The first location after the text of the program.
_edata The first location after initialized data.
_end The first location after all data.
__DYNAMIC
Identifies an ld-produced data structure. It is defined with a
non-zero value in executables which require execution-time link
editing. By convention, if defined, it is the first symbol in
the symbol table associated with an a.out file.
__GLOBAL_OFFSET_TABLE_
A position-independent reference to an ld-constructed table of
addresses. This table is constructed from “position-indepen‐
dent” data references occurring in objects that have been assem‐
bled with the assembler's -k flag (invoked on behalf of C compi‐
lations performed with the -pic flag). A related table (for
which no symbol is currently defined) contains a series of
transfer instructions and is created from “position-independent”
procedure calls or, if -dp is specified to ld, a list of unde‐
fined symbols.
Symbols in object files beginning with the letter L are taken to be
local symbols and unless otherwise specified are purged from ld output
files.
ENVIRONMENT
LD_LIBRARY_PATH
A colon-separated list of directories in which to search for
libraries specified with the -l option. Similar to the PATH
environment variable. LD_LIBRARY_PATH also affects library
searching during execution-time loading, causing the search to
use first those directories found in the environment variable,
then any directories specified by -L options, and finally the
standard directories /usr/lib and /usr/local/lib. NOTE: when
running a set-user- or set-group-ID program, ld.so will only
search for libraries in directories it “trusts”, which are
/usr/lib, /usr/5lib, /usr/local/lib, and any directories speci‐
fied within the executable as a result of -L options given when
the executable was constructed.
LD_OPTIONS
A default set of options to ld. LD_OPTIONS is interpreted by ld
just as though its value had been placed on the command line,
immediately following the name used to invoke ld, as in:
example% ld $LD_OPTIONS ... other-arguments ...
Note: Environment variable-names beginning with the characters `LD_'
are reserved for possible future enhancements to ld.
FILES
/usr/lib/lib*.a libraries
lib*.so.v shared libraries
lib*.sa.v exported, initialized shared library data
/usr/lib/ld.so execution-time ld
/usr/lib/*crt*.o default program bootstraps
a.out output file
/usr/local/lib
SEE ALSOar(1V), as(1), cc(1V), lorder(1), ranlib(1), strip(1), tsort(1), ldcon‐
fig(8)BUGS
Options are being overloaded and are an inappropriate vehicle for
describing to ld the wide variety of things it can do. There needs to
be a link-editing language which can be used in the more complex situa‐
tions.
The -r option does not properly handle programs assembled with the -k
(position-independent) flag, invoked from cc with -pic or -PIC.
21 January 1990 LD(1)