Manual page for ld(1)
ld - link editor for object files
command combines relocatable object files,
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;
option is specified,
relocatable object files are combined to produce
one relocatable object file.
In dynamic mode,
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;
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
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.
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.
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.
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 creates
special position-independent relocations for
references to functions defined in shared objects
and arranges for data objects defined in shared objects to be copied into
the memory image of the executable by the runtime linker.
With the -b option, the output code may be
more efficient, but it will be less sharable.
In dynamic mode only, produce a shared object.
Undefined symbols are allowed.
setting. This option is useful when an
setting is in effect to influence the
runtime library search, which would interfere
with the link editing being performed.
Produce a memory map or listing of the input/output sections,
together with any non-fatal multiply defined symbols,
on the standard output.
Strip symbolic information from the output file.
Any debugging information, that is
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.
Turn off the warning about multiply defined symbols that are
not the same size.
Output a message giving information about the version of
- -B dynamic|static
Options governing library inclusion.
is valid in dynamic mode only.
These options may be specified any number of times
on the command line as toggles:
if the -B static option is given,
no shared objects will be accepted
See also the -l option.
- -B local
Cause any global symbols, not assigned to a version definition,
to be reduced to local. Version definitions can be supplied via
a mapfile, and indicate the global symbols
that should remain visible in the generated object.
This option achieves the same symbol reduction as the auto-reduction
directive available as part of a mapfile version definition, and may
be useful when combining versioned and non-versioned
- -B reduce
When generating a relocatable object, cause the reduction of symbolic
information as defined by any version definitions. Version definitions
can be supplied via a mapfile, and indicate the global symbols
that should remain visible in the generated object. By default,
when generating a relocatable object, version definitions are only
recorded in the output image. The actual reduction of symbolic information
will be carried out when the object itself is used in the construction
of a dynamic executable or shared object. When creating a dynamic
executable or shared object, this option is applied automatically.
- -B symbolic
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 runtime,
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
- -D token,token,..
Print debugging information, as specified by each token, to the
standard error. The special token help indicates the full list of
- -e epsym
Set the entry point address for the output file to be that of
- -F name
Useful only when building a shared object. Specifies that the symbol table
of the shared object is used as a "filter" on the symbol table of the
shared object specified by name.
- -f name
Useful only when building a shared object. Specifies that
the symbol table of the shared object is used as an
``auxiliary filter'' on the symbol table of the
shared object specified by
- -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 runtime linker
as the name of the shared object to search for at runtime.
- -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 runtime linker, /usr/lib/ld.so.1.
Either case may be overridden by -Iname.
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.
- -L path
Add path to the library search directories.
ld searches for libraries first in any directories specified
by the -L options, and then in the standard directories.
This option is useful only if it precedes
the -l options to which it applies on the command line.
The environment variable
may be used to
supplement the library search path (see
- -l x
Search a library libx.so or
libx.a, the conventional names
for shared object and archive libraries, respectively.
In dynamic mode, unless the
option is in effect,
ld searches each directory specified in the library
search path for a file
The directory search stops at the first directory containing either.
ld chooses the file ending in .so if
expands to two files whose names are of the form
In static mode, or when the -B static 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
- -M mapfile
Read mapfile as a text file of directives to ld. This option
may be specified multiple times. If mapfile is a directory then all
regular files (as defined by
within the directory will be processed.
for description of mapfiles.
- -o outfile
Produce an output object file named
The name of the default object file is
- -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 identification.
- -R path
A colon-separated list of directories used to specify
library search directories to the runtime linker. If present
and not null, it is recorded in the output object file and
passed to the runtime linker. Multiple instances of this option
are concatenated together with each
separated by a colon.
- -u symname
Enter 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 placement of this option
on the command
line is significant; it must be placed before the library that will define
- -Y P,dirlist
Change the default directories used for finding libraries.
dirlist is a colon-separated path list.
- -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 muldefs
Allows multiple symbol definitions. By default, multiple symbol
definitions occurring between relocatable objects will result in a fatal error
condition. This option suppresses the error condition, and allows
the first symbol definition to be taken.
- -z nodefs
Allow undefined symbols.
This is the default when building a shared object.
When used with executables, the behavior of references to such
"undefined symbols" is unspecified.
- -z noversion
Do not record any versioning sections. Any version sections or
associated .dynamic section entries will not be generated
in the output image.
- -z text
In dynamic mode
only, force a fatal error if any relocations against
non-writable, allocatable sections remain.
A list of directories in which to search
for libraries specified with the
Multiple directories are separated by a colon.
In the most general case, it will contain two directory
lists separated by a semicolon:
is called with any number of occurrences of
ld ... -Lpath1 ... -Lpathn ...
then the search path ordering is:
dirlist1 path1 ... pathn dirlist2 LIBPATH
When the list of directories does not contain a semicolon, it is
is also used to specify library search
directories to the runtime linker.
That is, if
exists in the environment, the runtime
linker will search the directories named in it, before its
default directory, for shared objects to be linked with the
program at execution.
Note: When running a set-user-ID or
set-group-ID program, the runtime linker will only search
for libraries in any full pathname specified
within the executable as a result of a runpath
being specified when the executable was constructed, or in
Any library dependencies specified as relative pathnames will
be silently ignored.
A default set of options to
is interpreted by
just as though its value had been placed on the
command line, immediately following the name used to invoke
ld $LD_OPTIONS ... other-arguments ...
A list of shared objects that are to be interpreted by the
The specified shared objects
are linked in after the program being executed and before
any other shared objects that the program references.
Note: When running a set-user-ID or
set-group-ID program, this option has some restrictions.
The runtime linker will only search for these shared objects in
any full pathname specified within the executable as a result of a
runpath being specified when the executable was constructed, or in
Any shared object specified as a relative, or full pathname, will
be silently ignored.
An alternative mechanism for specifying a runpath to the link editor
option). If both
option are specified,
Provide a list of tokens that will cause the runtime linker to print
debugging information to the standard error. The special token
help indicates the full list of tokens available. The environment
may also be supplied to specify a file to which the
debugging information is sent. The filename will be suffixed with the
process id of the application generating the debugging information.
A shared object that will be profiled by the runtime linker.
When profiling is enabled, a
profiling buffer file is created and mapped. The name
of the buffer file is the name of the shared object being profiled
with a `.profile' extension. By default this buffer is placed under
The environment variable
may also be supplied to indicate an alternative directory in which to
place the profiling buffer.
This buffer contains
and call count information similar to the gmon.out information
generated by programs that have been linked with the
Any applications that use the named shared object
and run while this environment variable is set, will accumulate
data in the profile buffer. The profile buffer information may be
Note that environment variable-names beginning with the characters
`LD_' are reserved for possible future enhancements to
Options No Longer Supported
The following SunOS 4.x.y options do not have any replacement
in this release: -B nosymbolic (this is now
the default if -B symbolic is not used), -d,
-dc, and -dp,
(these are now the default, see -b above to override the default),
-M, -S, -t, -x, -X,
The following SunOS 4.x.y options are not supported:
-A name, -D -p, -T[text] hex,
Much of the functionality of these options can be achieved
using the -Mmapfile option.
The following SunOS 4.x.y options are obsolete
in this release: -n, -N, and -z.
Created by unroff & hp-tools.
© by Hans-Peter Bischof. All Rights Reserved (1997).
Last modified 21/April/97