ld(1) ld(1)
NAME
ld - link editor for object files
SYNOPSIS
ld [option ...] file ...
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, relocat-
able object files given as arguments are combined to produce an exe-
cutable 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 pro-
duce 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.
OPTIONS
-a In static mode only:
Produces an executable object file; gives error messages 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, does not do special processing for
relocations that reference symbols in shared objects. Without the
-b option, the link editor will create special position-indepen-
dent 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 shareable.
Page 1 Reliant UNIX 5.44 Printed 11/98
ld(1) 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
Sets the entry point address for the output file to be that of
the epsym symbol.
-h name
In dynamic mode only:
When building a shared object, records name in the object's
dynamic section. name will be recorded in executables that are
linked with this object rather than the object's Reliant UNIX
system filename. Accordingly, name will be used by the dynamic
linker as the name of the shared object to search for at run
time.
-lx Searches a libx.so or libx.a library. These are 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 Produces a memory map or listing of the input/output sections on
standard output.
-o outfile
Produces an output object file named outfile. The name of the
default object file is a.out.
-r Combines 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 Strips 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 sym-
bol table and string table sections will also be removed from the
output object file.
-t Turns off the warning about multiply defined symbols that are not
the same size.
Page 2 Reliant UNIX 5.44 Printed 11/98
ld(1) ld(1)
-u symname
Enters symname as an undefined symbol in the symbol table. This
is useful for loading entirely from an archive library, since
initially the symbol table is empty and an unresolved reference
is needed to force the loading of the first routine. The place-
ment of this option on the command line is significant; it must
be placed before the library that will define the symbol.
-z defs
Forces 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 refer-
ences are resolved internally.
-z nodefs
Allows 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:
Forces a fatal error if any relocations against non-writable,
allocatable sections remain.
-B[dynamic|static]
Controls the inclusion of libraries. -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.
Warning: If the last option you specify when using the -B options
is -Bstatic, the libc standard library will be used as the static
library.
-Bcountmultigots=number
Used in conjunction with -Bmultigot to set the number of GOTs and
GPs that the linker will create (default = 3). If your program
needs too many GOT entries you may get a "not enough space for
multiple GOTs, use -Bcountmultigots=<number>" error at link
time.
-Bdojmpopt
Directs the linker to fill empty delay slots of jump and jump-
and-link instructions during linkage. This is most effective with
the -Kold or -Kselpic flags. Note that this option may effect
debugging because the compiler may generate code that skips the
first instruction of a function.
Page 3 Reliant UNIX 5.44 Printed 11/98
ld(1) ld(1)
-Bkeepmdebug
Keep the .mdebug section in the output file. This section con-
tains symbolic debugging information for dbx. By default the
.mdebug section is removed from the output file.
-Blargedynsym
When building an dynamic executable, put all global symbols in
the dynamic symbol table, .dynsym. By default, ld only puts sym-
bols needed for dynamic linkage in the .dynsym section, i.e.
undefined symbols and symbols referenced by shared libraries.
This option may be necessary when loading shared libraries using
libdl. Adding this option ensures that all defined global symbols
in a.out are available to shared libraries loaded via dlopen(3X).
-Bloadall
Causes the linker to unconditionally load all the object modules
from an archive. Only affects those archives that appear after it
on the link-line until canceled by -Bloadsymbolic.
-Bloadsymbolic
Restores the default behavior for loading modules from archives
so that the modules are loaded to resolved undefined symbols,
canceling the effect of -Bloadall. Only affects those archives
that appear after it on the link-line.
-Bmultigot
Creates multiple Global Offset Tables (GOT). All entries in the
GOT need to be accessible from a 16-bit offset from a common GP
(Global Pointer). If the GOT grows too big you may get a "gp
relocation overflows 16 bits" error at link time. This option
will allow the linker to create multiple GOTs and GPs thus avoid-
ing the error. By default, the linker creates 3 Global Offset
Tables.
All the GP-specific relocations of one relocatable object file
must fit together in one GOT. The compiler guarantees this for
simple relocatable object files. Using ld -r, you can exceed this
limit when you combine some relocatable object files to a new
one. By linking such a relocatable object file with -Bmultigot
you may get an error such as "A module requires <number> GOT
entries. The maximum number is 16384." at link time.
-Bnocalltuning
When building an executable, does not adjust the values of global
function symbols to skip the gp-register calculation at the
beginning of PIC functions. Adding this option will reduce per-
formance.
-Bnolibraryreplacement
When building an executable, directs the dynamic linker to always
ignore the LDLIBRARYPATH environment variable.
Page 4 Reliant UNIX 5.44 Printed 11/98
ld(1) ld(1)
-Bprintlibs
Shows the pathnames of all the libraries that ld actually uses to
build the output file.
-Bptcbigpage
Orders the output file so it is suitable for preloading using the
preload utility. Applications that have a large working set size
(e.g. databases) will benefit the most from this feature. To
benefit from this option, the output file must be preloaded
before it is executed. See the preload(8) man page for details.
-Brpath=pathname
pathname contains a directory list which is used to specify
library search directories to the dynamic linker.
This option has the same meaning as the environment variable
LDRUNPATH (see below). If LDRUNPATH is also set, the environ-
ment variable is ignored.
-Bsymbolic
In dynamic mode only:
When building a shared object, binds references to global symbols
to their definitions within the object, if definitions are avail-
able. 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 execut-
able or other shared objects can override the object's own defin-
ition. ld will issue warnings for undefined symbols unless -z
defs overrides.
-BGnum:num
Controls the allocation of SHNCOMMON symbols to the .sbss sec-
tion. ld allocates SHNCOMMON symbols whose size is less than or
equal to num to the .sbss section. All other SHNCOMMON symbols
are allocated in the .bss section. num defaults to 8. No space
may appear on entire side of the : symbol.
-BACOMMONsize:size
In dynamic mode, determines what SHNCOMMON symbols are allocated
in .bss or .sbss. ld allocates in .sbss or .bss all SHNCOMMON
symbols whose size is less than or equal to size. Any remaining
SHNCOMMON symbols is allocated at run-time by the dynamic
linker. By default, size is effectively infinite. No space may
appear on the entire side of the : symbol.
-B64s
Indicates that a 64-bit object is to be produced, default is 32-
bit. No mixture of 32-bit and 64-bit object files is allowed. If
this option is not set, but the first o file on ld's command line
is a 64-bit object file, ld will switch to 64-bit mode.
Page 5 Reliant UNIX 5.44 Printed 11/98
ld(1) ld(1)
-G In dynamic mode only:
Produces a shared object. Undefined symbols are allowed.
-I name
When building an executable file, uses name as the pathname 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 overwritten by -I. exec will load this inter-
preter when it loads the a.out and will pass control to the
interpreter rather than to the a.out directly.
-L path
Adds 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 only effective
if it precedes the -l option on the command line.
-M mapfile
In static mode only:
Reads 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 Outputs a message giving information about the version of ld
being used.
-YP dirlist
Changes the default directories used for finding libraries.
dirlist is a comma-separated list of pathnames.
The LDLIBRARYPATH environment variable 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 occurrences of -L, as in
ld ... -Lpath1 ...-Lpathn ...
then the search path ordering is:
Page 6 Reliant UNIX 5.44 Printed 11/98
ld(1) ld(1)
dirlist1 path1 ... pathn dirlist2 LIBPATH
Note that LDLIBRARYPATH is also used by the dynamic linker. If
LDLIBRARYPATH is set in the environment, the dynamic linker will
search the directories listed there for shared objects to be linked
with the program at execution time.
If a 64-bit object is created, LDLIBRARY64sPATH is evaluated instead
of LDLIBRARYPATH, if it is set in the environment. If
LDLIBRARY64sPATH is not set, LDLIBRARYPATH is used.
The LDRUNPATH environment variable, 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.
NOTES
Global variables, which are declared with the same name in different
objects (without the suffix "extern"), are summarized as one variable.
In this case, ld issues a warning that must be acknowledged:
ld: file.o: warning: size of symbol `Progname` from file
/usr/lib/libnsl.so overridden with size of tentative definition
In the example above, this message indicates that a global variable
"Progname" which was declared in the file "file.c" is already con-
tained in the "libnsl.so" library. At runtime, both have the same
memory address.
If this is not intended, the above warning must be heeded and the
individual variable renamed.
FILES
libx.so libraries
libx.a libraries
a.out output file
LIBPATH usually /usr/ccs/lib:/usr/lib
SEE ALSO
cc(1), exec(2), exit(2), end(3C), a.out(4), ar(4), preload(8).
Page 7 Reliant UNIX 5.44 Printed 11/98