Manual page for LD(1)
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 combined 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 specified by
-B
(which can appear anywhere in the line).
- -align datum
-
Force the global uninitialized data symbol
datum
(usually a
FORTRAN
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
symbol 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 program.
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 corresponding 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 specification 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
common 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 relocation bits to save
space (but impair the usefulness of the debuggers). This information can also
be removed by
strip.1
- -S
-
Strip the output by removing all symbols except locals and globals.
- -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 executable
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 wasting 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 control options specified by
`-B'
and the abbreviated library-names specified by
`-l'.
These may appear
anywhere, and their influence is dependent upon their location.
Some options may be obtained from
environment 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 references,
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 references, 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 executable
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 executable 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
relocations; 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
maintenance 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 information. 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.
Failure 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 version found at
ld-time,
a warning diagnostic is issued; program 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
programs 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-independent'' data references occurring in objects
that have been assembled with the assembler's
-k
flag (invoked on behalf of C compilations
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 undefined 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 specified 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 ALSO
ar.1v
as.1
cc.1v
lorder.1
ranlib.1
strip.1
tsort.1
ldconfig.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 situations.
The
-r
option does not properly handle programs assembled with
the
-k
(position-independent) flag, invoked from
cc
with
-pic
or
-PIC.
Created by unroff & hp-tools.
© somebody (See intro for details). All Rights Reserved.
Last modified 11/5/97