ld(1) (Software Generation System Utilities) ld(1)
NAME
ld - link editor for object files
SYNOPSIS
ld [options] files ...
DESCRIPTION
The ld command combines relocatable object files, performs
relocation, and resolves external symbols. ld operates in two modes,
static or dynamic, as governed by the -d option. In static mode,
-dn, relocatable object files given as arguments are combined to
produce an executable object file; if the -r option is specified,
relocatable object files are combined to produce one relocatable
object file. In dynamic mode, -dy, the default, relocatable object
files given as arguments are combined to produce an executable object
file that will be linked at execution with any shared object files
given as arguments; if the -G option is specified, relocatable object
files are combined to produce a shared object. In all cases, the
output of ld is left in a.out by default.
If any argument is a library, it is searched exactly once at the
point it is encountered in the argument list. The library may be
either a relocatable archive or a shared object. For an archive
library, only those routines defining an unresolved external
reference are loaded. The archive library symbol table [see ar(4)]
is searched sequentially with as many passes as are necessary to
resolve external references that can be satisfied by library members.
Thus, the ordering of members in the library is functionally
unimportant, unless there exist multiple library members defining the
same external symbol. A shared object consists of a single entity
all of whose references must be resolved within the executable being
built or within other shared objects with which it is linked.
The following options are recognized by ld:
-a In static mode only, produce an executable object file; give
errors for undefined references. This is the default behavior
for static mode. -a may not be used with the -r option.
-b In dynamic mode only, when creating an executable, do not do
special processing for relocations that reference symbols in
shared objects. Without the -b option, the link editor will
create special position-independent relocations for references
to functions defined in shared objects and will arrange for
data objects defined in shared objects to be copied into the
memory image of the executable by the dynamic linker at run
time. With the -b option, the output code may be more
efficient, but it will be less sharable.
8/91 Page 1
ld(1) (Software Generation System Utilities) ld(1)
-d[y|n]
When -dy, the default, is specified, ld uses dynamic linking;
when -dn is specified, ld uses static linking.
-e epsym
Set the entry point address for the output file to be that of
the symbol epsym.
-h name
In dynamic mode only, when building a shared object, record
name in the object's dynamic section. name will be recorded in
executables that are linked with this object rather than the
object's UNIX System file name. Accordingly, name will be used
by the dynamic linker as the name of the shared object to
search for at run time.
-lx Search a library libx.so or libx.a, the conventional names for
shared object and archive libraries, respectively. In dynamic
mode, unless the -Bstatic option is in effect, ld searches each
directory specified in the library search path for a file
libx.so or libx.a. The directory search stops at the first
directory containing either. ld chooses the file ending in .so
if -lx expands to two files whose names are of the form libx.so
and libx.a. If no libx.so is found, then ld accepts libx.a.
In static mode, or when the -Bstatic option is in effect, ld
selects only the file ending in .a. A library is searched when
its name is encountered, so the placement of -l is significant.
-m Produce a memory map or listing of the input/output sections on
the standard output.
-o outfile
Produce an output object file named outfile. The name of the
default object file is a.out.
-r Combine relocatable object files to produce one relocatable
object file. ld will not complain about unresolved references.
This option cannot be used in dynamic mode or with -a.
-s Strip symbolic information from the output file. The debug and
line sections and their associated relocation entries will be
removed. Except for relocatable files or shared objects, the
symbol table and string table sections will also be removed
from the output object file.
-t Turn off the warning about multiply defined symbols that are
not the same size.
-u symname
Enter symname as an undefined symbol in the symbol table. This
is useful for loading entirely from an archive library, since
Page 2 8/91
ld(1) (Software Generation System Utilities) ld(1)
initially the symbol table is empty and an unresolved reference
is needed to force the loading of the first routine. The
placement of this option on the command line is significant; it
must be placed before the library that will define the symbol.
-z defs
Force a fatal error if any undefined symbols remain at the end
of the link. This is the default when building an executable.
It is also useful when building a shared object to assure that
the object is self-contained, that is, that all its symbolic
references are resolved internally.
-z nodefs
Allow undefined symbols. This is the default when building a
shared object. It may be used when building an executable in
dynamic mode and linking with a shared object that has
unresolved references in routines not used by that executable.
This option should be used with caution.
-z text
In dynamic mode only, force a fatal error if any relocations
against non-writable, allocatable sections remain.
-B [dynamic|static]
Options governing library inclusion. -Bdynamic is valid in
dynamic mode only. These options may be specified any number
of times on the command line as toggles: if the -Bstatic
option is given, no shared objects will be accepted until
-Bdynamic is seen. See also the -l option.
-Bsymbolic
In dynamic mode only, when building a shared object, bind
references to global symbols to their definitions within the
object, if definitions are available. Normally, references to
global symbols within shared objects are not bound until run
time, even if definitions are available, so that definitions of
the same symbol in an executable or other shared objects can
override the object's own definition. ld will issue warnings
for undefined symbols unless -z defs overrides.
-G In dynamic mode only, produce a shared object. Undefined
symbols are allowed.
-I name
When building an executable, use name as the path name of the
interpreter to be written into the program header. The default
in static mode is no interpreter; in dynamic mode, the default
is the name of the dynamic linker, /usr/lib/libc.so.1. Either
case may be overrridden by -I. exec will load this interpreter
when it loads the a.out and will pass control to the
interpreter rather than to the a.out directly.
8/91 Page 3
ld(1) (Software Generation System Utilities) ld(1)
-L path
Add path to the library search directories. ld searches for
libraries first in any directories specified with -L options,
then in the standard directories. This option is effective
only if it precedes the -l option on the command line.
-M mapfile
In static mode only, read mapfile as a text file of directives
to ld. Because these directives change the shape of the output
file created by ld, use of this option is strongly discouraged.
-Q[y|n]
Under -Qy, an ident string is added to the .comment section of
the output file to identify the version of the link editor used
to create the file. This will result in multiple ld idents
when there have been multiple linking steps, such as when using
ld -r. This is identical with the default action of the cc
command. -Qn suppresses version.
-V Output a message giving information about the version of ld
being used.
-YP, dirlist
Change the default directories used for finding libraries.
dirlist is a colon-separated path list.
The environment variable LDLIBRARYPATH may be used to specify
library search directories. In the most general case, it will
contain two directory lists separated by a semicolon:
dirlist1;dirlist2
If ld is called with any number of occurences of -L, as in
ld ... -Lpath1 ...-Lpathn ...
then the search path ordering is
dirlist1 path1 ... pathn dirlist2 LIBPATH
LDLIBRARYPATH is also used to specify library search directories to
the dynamic linker at run time. That is, if LDLIBRARYPATH exists
in the environment, the dynamic linker will search the directories
named in it, before its default directory, for shared objects to be
linked with the program at execution.
The environment variable LDRUNPATH, containing a directory list,
may also be used to specify library search directories to the dynamic
linker. If present and not null, it is passed to the dynamic linker
by ld via data stored in the output object file.
Page 4 8/91
ld(1) (Software Generation System Utilities) ld(1)
FILES
libx.so libraries
libx.a libraries
a.out output file
LIBPATH usually /usr/ccs/lib:/usr/lib
SEE ALSO
as(1), cc(1).
exec(2), exit(2), end(3C), ar(4) in the Programmer's Reference
Manual.
The ``C Compilation System'' chapter and the ``Mapfile Option''
appendix in the Programmer's Guide: ANSI C and Programming Support
Tools.
NOTES
Through its options, the link editor gives users great flexibility;
however, those who use the -M mapfile option must assume some added
responsibilities. Use of this feature is strongly discouraged.
8/91 Page 5