ld(1)
ld --
link editor for object files
Synopsis
ld [options] 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, 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.
ld will combine object files compiled for either the Intel IA-64
architecture or the Intel IA-32 architecure (also known as x86
or Pentium®). For IA-64, ld accepts objects compiled for
either the LP64 or ILP32 programming models.
The first object given to
ld on its command line determines what kind of file ld
will produce (IA-64 LP64, IA-64 ILP32 or IA-32). All subsequent
objects must match the model of the first object.
If any argument is a library, it is searched only
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 object file members 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 typically 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-
(For IA-32 objects only.)
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.
-d yn-
ld uses static linking only when yn is n;
otherwise, by default, or when yn is y,
ld uses dynamic linking.
-e epsym-
Set the entry point address for the output file to be that of
the symbol
epsym.
-f arg-
where arg is a processor -specific linking option:
udk-
(For IA-32 objects only.)
The system uses certain heuristics in distinguishing
between binaries compiled for SCO OpenServer using
the SCO OpenServer application binary interface
and binaries compiled for SCO UnixWare 2.X or UnixWare 7
using the binary interface specified by the
"System V Application Binary Interface Intel386
Processor Supplement." These heuristics can fail in rare cases.
The udk flag can be used in cases when
the heuristcs break down. It instructs the linker
to add a special mark to a binary object to
positively identify it as a binary compiled
by the UnixWare 7 compiler and intended to be
able to run on UnixWare 7, SCO OpenServer and SCO UnixWare 2.X.
osr5-
iabi-
(For IA-32 objects only.)
By default, object files compiled for SCO OpenServer
cannot be linked with object files compiled
for SCO UnixWare 2.X or for UnixWare 7. If the linker
detects an attempt to mix such objects, it
will issue a fatal error. The osr5 flag
instructs the linker to accept mixed SCO OpenServer,
SCO UnixWare 2.X and UnixWare 7 objects and to create
an output file that appears to the system as if
targeted for SCO OpenServer.
The iabi flag instructs the linker to accept mixed
SCO OpenServer, SCO UnixWare 2.X and UnixWare 7 objects but to
create an output file that appears to the system
as if targeted for SCO UnixWare 2.X or UnixWare 7.
The osr5 flag cannot be combined with the udk flag.
elf64-
(For IA-64 LP64 objects only). Only when producing
a relocatable object (-r).
IA-64 relocatable objects that use the LP64
programming model may still use a 32-bit ELF container
if all file offsets can be represented in 32 bits.
Using a 32-bit ELF object instead of a 64-bit
object saves disk space. By default, ld will attempt
to create a 32-bit ELF relocatable when the input objects
use the LP64 model. This option forces ld to create
a 64-bit object.
-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 shared object's pathname.
Accordingly, name will be used by the dynamic linker
as the pathname 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 order of the -l, -B and -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-
ld normally warns if two common symbols with the same
name or a common symbol and an initialized definition
with the same name have different sizes. -t turns
off this warning.
-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
the symbol.
-v-
Turn on verbose tracing. ld will print the name of
each symbol that causes an object to be extracted from
an archive file, along with the name of the object.
-y symbol-
Print the names of all files that reference or define the
named symbol.
-x-
Remove local symbols and debugging
information from a shared object or static or dynamic executable.
-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 multidefs-
ld will allow multiple defintions of the same global symbol
within the same output object. Only the first definition
is used in symbol resolution.
-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 origin-
Creates a DT_ORIGIN entry in the object's dynamic section
array. This signals to the dynamic linker that this
object will use a $ORIGIN directive in a pathname
specified to
dlopen(3C);
the dynamic linker will calculate
the originating path for this object.
-z text-
In dynamic mode
only, force a fatal error if any relocations against
non-writable, allocatable sections remain.
This is the default for IA-64 objects.
-z warn_common-
ld will issue a warning when a definition for a symbol
from a shared object overrides a common definition
for the same symbol coming from a relocatable object file.
-B arg-
where arg can be any one of the following:
dynstat-
dynstat can be either
dynamic
or
static.
These options govern library inclusion.
dynamic is valid in dynamic mode only.
These options may be specified any number of times
on the command line as toggles:
if -Bstatic is given,
no shared objects will be accepted
until -Bdynamic is seen.
See also the -l option.
import:symfile]-
Import files provide a specification for the symbols
that are provided by a shared object. They permit
you to check that symbol definitions referenced by the objects
you are linking together are actually provided by
another shared object, without actually having that object
in hand to link against.
symfile contains a list of symbols specifications and
directives, one per line. Blank lines are ignored.
A ``#'' character introduces a comment: the ``#'' and
anything following it on the same line are ignored.
A directive is introduced by a directive name,
all of which begin with a ``%''. The directive
name is followed on the same line by a string
containing no white-space, or a string enclosed
in double-quotes (").
Each symbol specification has the following form:
name [tag [number]]
where tag may be one of: function, object,
syscall
and number is a decimal, octal or hexadecimal number.
The tag and number are optional. For symbols with
the tags function and object, the optional number
represents the symbol's size. The syscall tag is
used by kernel extensions that define their own
system calls. For symbols with
the syscall tag, the optional number represents the system
call number (this is typically used only by the
implementation and should be ommitted for kernel
extensions).
The -Bimport directive is processed as it is seen
on the command line. Each symbol specified is
processed as if it were defined in a shared object that
has been specified on the ld command line. Normal
symbol resolution rules apply. Symbols with the
special syscall tag result in the creation of
a special symbol defined against the SHN_MONTEREY_SYSCALL
section. The value of such symbols is either 0 or
the optional system call number supplied.
If the import file contains a %soname directive,
the string provided by the directive is used
to create a DT_NEEDED entry in the object's dynamic
section array. This creates an explicit dependency
on the object specified.
When building an IA-64 shared object only, the import
file may also contain a %iversion directive. This
directive supplies an interface name and version
for use by kernel extensions. It specifies the name
and version of the interface for the symbols specified
in the import file. The interface name and version are supplied
within a single string and are separated by a colon
(for example: %iversion my_version_name:123).
ld creates a DT_IMP_IVERSION entry with the given string
in the object's dynamic section array. Only one
%iversion directive may be given in a single import
file. If multiple import files are specified on the command
line and more than one references the same interface
name, they must all reference the same version of that
interface.
symbolic [=list | :symfile]-
where list is a comma separated sequence of symbol names.
symfile is a symbol file as described under -Bimport.
-Bsymbolic does not recognize any symbol file directives.
The optional tag and number fields in symbol specifications
are ignored.
When building a shared object,
if a definition for a named symbol exists,
bind all references to the named symbol to that definition.
If no list of symbols is provided,
bind all references to symbols to definitions that are available;
ld will issue warnings for undefined symbols unless -z defs
overrides.
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.
bind_now-
In dynamic mode only, this option adds a DT_BIND_NOW entry to the
``.dynamic'' section of the output file. This entry instructs the
dynamic linker to process all relocations for the object containing this
entry before transferring control to the program. The presence of
DT_BIND_NOW takes precedence over a directive to use lazy
binding for this object when specified through the environment or
via dlopen.
export[=list | :symfile]-
hide [=list | :symfile]-
where list is a comma separated sequence of
symbol names.
symfile is a symbol file as described under -Bimport.
-Bhide does not recognize any symbol file directives.
For -Bhide, the optional tag and number fields in symbol
specifications are ignored.
Normally, when building a shared object or relocatable object,
ld makes
all global and weak names defined in the shared
object visible outside of the object itself (exported).
When building an executable, it makes visible only those
names used by the shared objects with which the executable is
linked. All other names are hidden. This behavior
can be modified with -Bhide and -Bexport.
When building a shared object or relocatable object
-Bexport is the default.
All global and weak definitions are exported.
-Bexport with a set of symbol names instructs ld to
hide all global and weak definitions, except those
in the specified set. -Bhide means to hide all global
and weak definitions.
-Bhide with a set of symbol names means to export
all global and weak definitions, except for those in the
set of names.
When building an executable, -Bhide is the default.
Only those names referenced by the shared objects
with which the executable is linked are exported.
-Bhide with a set of symbol names instructs ld to
export all global and weak definitions, except those
in the specified set. Names in a -Bhide list that
are referenced by the shared objects with which the
executable is linked, are ignored, that is, they
are exported. -Bexport means to export all global
and weak definitions. -Bexport with a set of symbol
names means to hide all global and weak definitions
except those in the set of names and those referenced
by the shared objects with which the executable is
linked.
If -Bhide and -Bexport are used together, one of the
options must contain a set of symbol names and the other
must not. In this case,
the option without the symbol set is ignored.
-Bhide and -Bexport may be used when creating a
dynamically-linked executable, shared object or relocatable object.
Neither may be used when creating a statically linked executable.
In symbol specifications for -Bexport, the optional
tag syscall may be used by kernel extensions if
they define their own system calls. The symbol table
entries for such symbols will be marked specially so
they can be recognized by the kernel loader.
The function and object tags and the optional number
field are ignored for -Bexport.
When building an IA-64 object shared object only,
-Bexport recognizes a single symbol
file directive: %iversion.
This directive is used to specify an interface name
and version number for kernel extensions.
The interface name and version number are supplied within a
single string and are separated by a colon
(for example, %iversion my_version_name:323).
This directive causes ld to produce
a DT_MONTEREY_EXP_IVERSION
member in the output object's dynamic section array.
A single export file may contain only one %iversion directive,
but a shared object may export symbols to multiple
interfaces or multiple versions of the same interface
by specifying multiple export files.
init-
Specify the name of the routine whose address is used
as the value of the DT_INIT dynamic section array entry
(_init, by default).
fini-
Specify the name of the routine whose address is used
as the value of the DT_FINI dynamic section array entry
(_fini, by default).
sortbss-
All uninitialized global variables within a module will be assigned contiguous
addresses.
This is the way these variables were assigned by the COFF version
of the link editor.
-G-
In dynamic mode only, produce a shared object.
Undefined symbols are allowed unless the -z defs
option is specified.
-I name-
When building an executable, use 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 overridden 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.
-L path-
Add path to the library search directories.
ld searches for libraries first in any directories specified
with -L options (in order), and then in the standard directories
(see the -YP option).
This option is effective only if it precedes
a -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 yn-
If yn is y, an identification 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 instances of such
when there have been multiple linking steps,
such as when using ld -r.
This is identical with the default action of the cc command.
If yn is n (the default), the version information is suppressed.
-R path-
Create a DT_RUNPATH entry in the object's dynamic section
array. Path is a colon-separated list of pathnames.
The dynamic linker will search this path to find
this object's immediate dependencies at run-time. The path
supplied by DT_RUNPATH is searched before the default
search directory and after paths supplied by the
environment variable LD_LIBRARY_PATH.
-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 LD_LIBRARY_PATH 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
Thus, if ld is called with the following occurrences of -L:
ld . . . -Lpath1 . . . -Lpathn . . . -lx
then the search path ordering for the library x (libx.so
or libx.a) is:
dirlist1 path1 . . . pathn dirlist2 LIBPATH
LD_LIBRARY_PATH is also used to specify library
search directories to the dynamic linker at run time.
That is, if LD_LIBRARY_PATH exists in the
environment, the dynamic linker will search
the directories it names
before its default directory for shared objects to
be linked with the program at execution.
Additionally, the environment variable LD_RUN_PATH (which also
contains a directory list)
may be used to specify library search directories to the dynamic linker.
If present and not empty, it is passed to the dynamic linker by ld
via data stored in the output object file.
LD_RUN_PATH is ignored if building a shared object. The paths
it specifies are searched by the dynamic linker before those
specified by LD_LIBRARY_PATH. LD_RUN_PATH is obsolete. Its
use is discouraged in favor of the -R option to ld.
If -R is
specified, LD_RUN_PATH is ignored.
Files
libx.so-
libraries
libx.a-
libraries
a.out-
output file
LIBPATH-
usually /usr/ccs/lib:/usr/lib
/usr/lib/local/locale/LC_MESSAGES/uxcds-
language-specific message file [See LANG on
environ(5).]
References
a.out(4),
ar(4),
as(1),
cc(1),
elfmark(1),
end(3C),
exec(2),
exit(2)
Notices
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.
ld should be invoked directly only if -r is used
to create a relocatable object to be used in a later link.
Creation of an executable or shared object should be done through the
CC or cc command.
The CC command must be used if any input object files contain
C++ code.
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004