Content-type: text/html
Man page of ld
ld
Section: User Commands (1)
Index
Return to Main Contents
NAME
ld - link editor
SYNOPSIS
ld [option...] file...
OPTIONS
When searching for libraries,
ld
looks for them,
by default, in the following directories in the order shown:
/usr/shlib
/usr/ccs/lib
/usr/lib/cmplrs/cc
/usr/lib
/usr/local/lib
/var/shlib
You can use the following position-dependent qualifiers to alter the
ld
command's library directory search order for all libraries subsequently
referenced on the command line. Note that any of these options is effective
only if it precedes the
-l
option on the command line for
the libraries it is meant to affect.
Change the library directory search order for shared object
and archive libraries (libx.{so|a}) so that
ld
looks for
them in
dir
before looking in the default library
directories.
Change the library directory search order for shared object
and archive libraries (libx.{so|a}) so that
ld
never
looks for them in the default library directories. Use
this option when the default library directories should not be searched and
only the directories specified by
-Ldir
are to be searched.
Eliminate the search of the default library directories and
instead cause
ld
to search the single directory
dir. Instead of using this option, which is intended exclusively
for the compiler driver, you should use the
-L
and
-Ldir
options in combination to obtain
a similar effect.
When linking a shared object,
ld
searches all library
directories for the shared object library (libx.so). If it cannot find the shared object
library, it again searches all library directories for the archive library
(libx.a).
You use the following switches to alter the manner in which
ld
searches library directories for shared object and archive libraries
and the manner in which
ld
establishes the order of initialization
routines in the image:
Cause
ld
to search each library directory,
first for the shared object library (libx.so) and then for the archive library (libx.a).
Request that the execution order of
init
routines match the link order of the objects and archive libraries from which
the routines are loaded. This ordering might not match the execution order
used when archive libraries are replaced with shared libraries.
Reverse the execution order of
init
routines.
This option does not affect
init
routines identified by
the
-init
option; nor does it affect
fini
routines. This option also does not change the relative order of groups of
init
routines linked in from archive libraries, but it does affect
the relative order of
init
routines within those groups.
The library search can be restricted to shared libraries by the
-no_archive
option or to archive libraries by the
-no_so
option. The
-so_archive
option removes either of these search
restrictions.
Use the following position-dependent qualifiers to determine which libraries
ld
searches for in the library directories when resolving symbol
names. The order of these options is significant because
ld
searches for a shared object or archive library when it encounters its name
on the command line.
Search a library,
libx.{so|a}, where
x
is
a string.
This option is identical to the
-lx
option in usage and behavior except for the following difference:
if the library specified by
-qlx
is not found, the linker does not produce error or warning messages. However,
the linker reports unresolved symbol errors and other link-time errors normally.
The
ld
command also accepts the following options:
Direct the linker to read the contents of file
filename
as if the contents had been supplied on the command
line.
-
Inside file
filename, lines ending with \
are treated as continuation lines, and lines starting with
#
are treated as comment lines and ignored. The
-v
option can
be used to display the expansion of files specified in a
-input
file. The files can be nested up to 20 levels.
Produce an output object file with the name
outfile. The name of the default object file is
a.out.
Strip the symbolic information from the output object file.
Do not preserve local (non-.globl) symbols
in the output symbol table; enter external and static symbols only. This option
reduces the size of the output file.
Retain relocation entries in the output file. Relocation entries
must be saved if the output file is to become an input file in a subsequent
ld
run. This option also prevents final definitions from being given
to common symbols and suppresses ``undefined symbol'' diagnostics.
Force definition of common storage and define linker-defined
symbols even if
-r
is present.
Force definition of common storage. (Linker-defined symbols
are not defined.)
Enter
symname
in the symbol table
as an undefined symbol. This is useful for loading entirely from a library
because the symbol table is initially empty and an unresolved reference is
needed to force the loading of the first routine.
Create a ZMAGIC (demand paged) output file. Text and data
segments are aligned on page boundaries and their sizes are a multiple of
the page size. This is the default.
Produce an
msym
table for a dynamic executable
or shared object. This table contains additional dynamic symbol information.
If an executable or shared library is built without an
msym
table, the loader creates one each time the executable or shared library is
loaded. Use of the
-msym
option causes the linker to create
the
msym
table, thus reducing load time and the amount
of dynamic memory allocated by the loader. Unlike the loader-generated
msym
tables, the linker produces
msym
tables
that are shared between processes.
Create an NMAGIC (shared text) output file. Text and data
segment addresses are 0x20000000 and 0x40000000 respectively. The text and
data segments sizes are a multiple of the page size.
Create an NMAGIC (shared text) output file. Text and data
segments are aligned on page boundaries and their sizes are a multiple of
the page size. The data segment immediately follows the text segment in the
address space.
Create an OMAGIC (impure) output file. Text and data segments
are aligned on 16-byte boundaries and their sizes are a 16-byte multiple.
The data segment immediately follows the text segment in the address space.
Set the text segment origin. The argument
num
is a hexadecimal number. See the
NOTES
section for restrictions.
Set the data segment origin. The argument
num
is a hexadecimal number. See the
NOTES
section for restrictions.
Set the
bss
segment origin. The argument
num
is a hexadecimal number. This option can be used only if
the final object is an OMAGIC file.
Set the default entry point address for the output file to
be that of the symbol
epsym.
Produce a map or listing of the input/output sections on the
standard output (UNIX System V-like map).
Produce a primitive load map, listing the names of the files
to be loaded (UNIX 4.3BSD-like map).
Set silent mode and suppress nonfatal errors.
Set verbose mode. Print the name of each file as it is processed.
Indicate each file in which
sym
appears,
sym's type, and whether the file defines
or references
sym. To allow you to trace multiple
symbols, this option can be specified many times on a command line.
Print a message that provides information about the version
of
ld
being used.
Use
num
as the decimal version
stamp to identify the
a.out
file that is produced. The
version stamp is stored in the optional and symbolic headers.
Set the fill pattern for ``holes'' within an output
section. The argument
fill
is a four-byte hexadecimal
constant.
Do not merge the symbolic information entries for the same
file into one entry for that file. This is needed only when the symbolic
information from the same file appears differently in any of the objects to
be linked. This can occur when object files are compiled, by means of conditional
compilation, with an apparently different version of an include file.
Perform additional type processing to provide improved symbolic
debugging information.
Perform incremental loading, that is, do linking in a way
that allows the resulting object to be read into an already executing program.
The next argument,
file, is the name of a file
whose symbol table will be taken as a basis on which to define additional
symbols. Only newly linked material will be entered into the text and data
portions of
a.out, but the new symbol table will reflect
every symbol defined before and after the incremental load. This argument
must appear before any other object file in the argument list. The
-T
option can be used as well and will be taken to mean that the newly
linked segment will commence at the corresponding address (which must be a
correct multiple for the resulting object type). The default resulting object
type is an OMAGIC file, and the default starting address of the text is the
old value of
_end
rounded to SCNROUND as defined in the
include file
<scnhdr.h>. Using the defaults,
when this file is read into an already executing program, the initial value
of the program break (see
brk(2)) must also be rounded.
Produce a static executable. The output object created will
not use any shared objects during execution. The
-init
and
-fini
switches cannot be used in combination with the
-non_shared
switch. This is the default.
Disable the automatic recognition of symbols prefixed with
__init_
as initialization routines as well as disabling
the automatic recognition of symbols prefixed with
__fini_
as termination routines. This option is only for applications
that already have defined symbols with the prefixes
__init_
or
__fini_. (This option does not disable
__INIT_
or
__FINI_
routines.)
Produce a shared object. This includes creating all of the
tables for run-time linking and resolving references to other specified shared
objects. The object created may be used by the linker to produce dynamic
executables.
Produce a dynamic executable. The object created may use
shared objects at run time.
Convert the symbol following this option into a local symbol.
This option is position independent. (Used for shared linkage only.)
Convert all external symbols from objects following this option
into local symbols. (Used for shared linkage only.)
Turn off the
-hidden
option. To turn off
the
-hidden
option for a single symbol, use the
-exported_symbol
option.
Turn off the
-hidden
option for a single symbol,
specified by
pattern. Pattern matching uses shell
wildcard characters (?, *, [, ]). For more information, see
sh(1).
Ignore any unresolved symbols matching
pattern. Such symbols are not displayed and are not treated as errors
or warnings. You can enter this option multiple times on a command line. The
patterns use shell wildcard characters (?, *, [, ]). The wildcard characters
must be properly quoted to prevent them from being expanded by the shell.
For more information, see
sh(1).
Produce a warning message when unresolved symbols are encountered,
except for those matching
-expect_unresolved. This is the
default behavior for building shared libraries.
Produce an error message and cause the link to fail when unresolved
symbols are encountered, except for those matching
-expect_unresolved. This is the default behavior for linking executable programs.
Link in all of the objects from the archives following this
option. This option is used in conjunction with the
-shared
option to create a shared object.
Turn off the
-all
option.
Exclude the specified object from the shared object being
created by the linker. Used in conjunction with
-all
and
-shared.
Require
-l
references to resolve to shared
objects. Normally, if the shared object as specified by the
-l
is not found, the linker attempts to find the corresponding archive to resolve
undefined symbols. This option disallows using those archives. Note that
this option is positional and can be used more than once on a command line.
It affects only those options that follow it, and it is turned off by the
next occurrence of a
-no_so
or
-so_archive
option.
Require
-l
references to resolve to archive
libraries. Note that this option is positional and can be used more than once
on a command line. It affects only those options that follow it, and it is
turned off by the next occurrence of a
-no_archive
or
-so_archive
option.
Turn off either the
-no_archive
or
-no_so
options allowing
-l
references to resolve to
either shared objects or archive libraries in shared or call_shared links.
Check the location of this shared object's segments and make
sure they stay out of the way of other object's segments in the
location_file. Multiple instances of this option are allowed. This
option is used with
-shared.
Register the location of this shared object's segments and
make sure they stay out of the way of others in the
location_file. The
location_file
is updated if
it is writable. This option is used with
-shared.
Set an option in the dynamic section of the output object
so that rld does not allow exec-time or run-time changing of the path (except
for super user) to find the shared objects. Typically, the option is used
by system utilities for security purposes.
Create an
rpath
record containing the specified
path
string. The
path
string is
a colon-separated list of directories that is meaningful only when creating
an executable with shared linkage. If an item in the
path
supplied to
-rpath
is of the form
$VARNAME
or
${VARNAME}, the linker interprets it as an environment
variable.
-
Additional
rpath
directories found in shared objects
on the link command line are appended to
path.
Duplicate entries are excluded. The loader uses the
rpath
record to search for shared libraries at run time.
Set DT_SONAME for a shared object. The name can be a single
component name (for example,
libc.a), a full pathname
(starting with a slash), or a relative pathname (containing a slash). The
default DT_SONAME used for shared objects is the filename component of the
output file name. Specify the output file name using the
-o
option as described previously. Used in conjunction with
-shared
option.
Make the procedure represented by the symbol into an initialization
routine. An initialization routine is a routine that is called without an
argument when either the file that contains the routine is loaded or the program
that contains the routine is started.
Make the procedure represented by the symbol into a termination
routine. A termination routine is a routine that is called without an argument
when either the file that contains the routine is unloaded or the program
that contains the routine exits.
Cause
ld
to link in any shared object that
occurs in the dependency list in addition to those shared objects on the link
command line. If
ld
cannot find the shared object in the
dependency list, it will cause a fatal error.
Turn off all code optimizations performed by the linker. This
is the default.
Turn on the code optimizations that can be performed quickly
with little additional time and memory overhead during the link. Note that
cc(1)
passes
-O1
as the default when linking.
Turn on all code optimizations that can be performed by the
linker.
Set an option in the dynamic section of the object produced
by the linker. The option directs the loader to ensure that the shared libraries
used by this dynamic object at run time match the shared libraries referenced
at link time. By default, a shared library's version is included in the match
test. This option requires a stricter test that includes shared library checksums
and timestamps.
-
This option is used when building a dynamic executable file (with
-call_shared) or a shared library (with
-shared).
Establish the version identifier (or identifiers) associated
with a shared library. The string
version-string
is either a single version identifier or a colon-separated list of version
identifiers. No restrictions are placed on the names of version identifiers;
however, it is highly recommended that UNIX directory naming conventions be
followed.
-
If a shared library is built with this option, any executable built
against it will record a dependency on the specified version or, if a list
of version identifiers is specified, the rightmost version specified in the
list. If a shared library is built with a list of version identifiers, the
loader will allow any executable to run that has a shared library dependency
on any of the listed versions.
-
This option is only useful when building a shared library (with
-shared).
Set an option in the dynamic section in output objects requesting
a depth_first, ring_search method for resolving symbol references between
shared objects. See
loader(5)
for a complete description of this alternate symbol resolution
policy. This option is used in conjunction with
-call_shared.
Alters the search algorithm used to resolve symbol references.
Instead of starting with the executable file using a breadth-first search
order (the default), the loader starts with a shared object using a depth-first
search order. If a symbol cannot be resolved in the shared object and its
dependencies (if any), the loader then searches the executable file and the
other shared objects as it would by default. (Note: The depth-first search
avoids symbol preemption confusion that would occur in some cases of a breadth-first
search.)
-
Use this option when building a shared library, to override the default
symbol resolution policy.
Direct the linker to load the executable in the lower 31-bit
addressable virtual address range. The
-T
and
-D
options to the
ld(1)
command can also be used to ensure that the text and data
segments addresses, respectively, are loaded into low memory. The
-taso
option, however, in addition to setting default addresses for
text and data segments, also causes shared libraries linked outside the 31-bit
address space to be appropriately relocated by the loader. If you specify
-taso
and also specify text and data segment addresses with
-T
and
-D, those addresses override the
-taso
default addresses. The
-taso
option can be helpful
when porting programs that assume address values can be stored in 32-bit variables
(that is, programs that assume that pointers are the same length as
int
variables).
Generates an OMAGIC file suitable for input to the
om
post-link optimizer. This option should be used only with the
cc
command.
DESCRIPTION
Note
Information about the
uld
linker has been deleted
from this manpage. See
ld(1old)
for information on the
uld
linker.
The
ld
command invokes the Tru64 UNIX link
editor (``linker'') which links extended COFF object files.
The
ld
command combines several object files into
one, performs relocation, resolves external symbols, builds tables and relocation
information for run-time linkage in case of doing a shared link, and supports
symbol table information for symbolic debugging. In the simplest case, the
names of several object
files
are specified on
the command line. The
ld
command combines them, producing
an object module that can be executed or used as input by a subsequent
ld
command. (In the latter case, the
-r
option must
be given to preserve the relocation entries.) The output of
ld
is left in
a.out. By default, this file is a static executable
(-non_shared) if no errors occurred during the load.
The object files are concatenated in the order specified. The entry
point of the output is the beginning of the text segment (unless the
-e
option is specified).
If any argument is a library, it is searched exactly once at the point
it is encountered in the argument list. There are two kinds of libraries,
archives and dynamic shared objects:
Archives are used if the output is to be static. In that
case, only those object files defining an unresolved external reference are
loaded. The archive symbol table (see
ar(1)) is searched to resolve external
references that can be satisfied by archive library members. The ordering
of library members is important (see
lorder(1)).
Shared objects are normally used if the output is to be dynamic.
In that case, only the name is used for external resolution; no object is
included as part of the output object file.
Position-sensitive options affect link behavior for objects and libraries
that follow the option in the command. These options include
-L,
-all,
-exclude,
-exported_symbol,
-hidden,
-hidden_symbol,
-kl,
-l,
-none,
-non_hidden,
-no_archive,
-no_so, and
-so_archive. They
are described in detail in the
OPTIONS
section in this
reference page.
The symbols
_etext,
_edata,
_end,
_ftext,
_fdata,
_fbss,
_gp,
.fini,
.data,
.text,
.init,
.rdata,
.sdata,
.sbss,
.bs,
.lit4,
.lit8,
.comment,
__istart,
__fstart,
data_init_table,
_DYNAMIC,
_DYNAMIC_LINK,
_BASE_ADDRESS,
_GOT_OFFSET,
_procedure_tabl,
_procedure_table_size,
_procedure_string_table,
_cobol_main, and
_unwind
are reserved. If the
-std1
option is not set (see the
cc(1)
reference page), the symbols
etext,
edata,
end, and
unwind
are also reserved. These linker-defined symbols, if referred
to, are set to the values described in
end(3). Undefined results may occur
if user code defines any of these symbols.
Symbol names that start with
__init_
and
__fini_
have special meaning to the linker:
All routines that start with
__init_
are treated, by default, as initialization routines. These are routines that
are called without an argument when the file that contains them is loaded
or when the program that contains them is started.
All routines that start with
__fini_
are treated by default as termination routines, which are routines that are
called without an argument when the file that contains them is unloaded or
when the program that contains them exits.
Any executable program that references the builtin symbol
_fpdata_size
(either directly or through a shared object) and all
shared objects, regardless of whether they reference the builtin symbol, causes
the linker to generate and include code and data to support exception handling.
For shared objects, this is always done because the programmer creating the
shared object might not know whether the program referencing the shared object
uses exception handling. This support is needed so that the exception handling
system can unwind stack frames and find handlers for exceptions (see
exception_intro(3)).
Exception support consists of the following:
Generating data structures that the exception system can use
to perform unwinds
Generating
.init
and
.fini
section calls to register the exception data structures within the exception
system
Linking
libexc_init.a, which contains
a set of bridge routines that call the exception system registration routines
The
libc
library has a set of dummy routines that
replace the exception routines when the exception system is not present. By
default, this replacement works because
libc
is generally
specified last on the link line. The
cc(1)
command ensures that
libc
is the last library on the command line unless otherwise specified.
Users requiring the exception system must not explicitly specify
libc
before
libexc
on the command line.
NOTES
Any of the three types of objects (ZMAGIC, NMAGIC, OMAGIC) can be run
on Tru64 UNIX systems. Within the objects, segments must not overlap
and all addresses must be less than 0x40000000000:
For ZMAGIC files, the default text segment address is 0x120000000
and the default data segment address is 0x140000000. (If
-taso
is specified the default addresses for the text and data segments are 0x12000000
and 0x14000000, respectively.)
For NMAGIC files, the default text segment address is 0x20000000
and the default data segment address is 0x40000000.
For OMAGIC files, the default text segment address is 0x10000000,
with the data segment following the text segment.
The stack starts below the text segment and grows through lower addresses,
so space should be left for it.
An additional constraint is that all addresses within an executable's
data segment must not be any farther than 0x7fff8000 from all addresses within
the text segment.
For all types of files, the bss segment follows the data segment by
default. For OMAGIC files, the
-B
option should not be used
because the bss segment must always follow the data segment. For NMAGIC and
ZMAGIC files, the location of the bss segment does not have any distance requirements.
OBJECT AND LIBRARY ORDERING
The ordering of object files, archive libraries, and shared libraries
on the command line affects how symbols are resolved. For example, if an
archive library appears before an object file or shared library that references
one of its symbols, the linker may report that symbol as unresolved.
Unresolved symbol errors can be avoided by adhering to the following
suggestions:
Object files should be ordered before all archive libraries
and shared libraries.
If archives and shared libraries cannot be specified in dependency
order, shared libraries should be ordered before archive libraries.
If necessary, archives can be specified more than once on
the
ld
command line to handle unresolved symbols that were
encountered after previous symbol-resolution passes through the archives.
Symbols defined in object files are always included in the output object.
Ordering object files first might prevent the inclusion of conflicting symbols
that are also defined in archive libraries or shared libraries specified on
the
ld
command line.
As each object, archive library, and shared library is processed by
the linker, new symbol definitions and references are added to the output
object. If a symbol reference is added for a symbol that does not yet have
an associated symbol definition, it is an ``undefined'' symbol.
The linker must find a definition of every undefined symbol. The definition
must exist in either an object, archive, or shared library specified on the
command line. Archives and shared libraries are processed in the following
ways:
When the linker processes an archive library, it extracts
objects from the archive that define any symbols that are currently undefined.
As each object is extracted from an archive library, the linker processes
the object, identifies any additional undefined symbols, and extracts the
objects that define those symbols.
When the linker processes a shared library, it extracts symbol
definitions from the shared library for symbols that are currently undefined.
These symbol definitions are added to the output object. The shared library
might also define many symbols that are not added to the output object. These
symbols will not be considered as additional objects (archive libraries and
shared libraries) are processed; however, the linker does not report these
symbols as unresolved if they are referenced in objects ordered after the
shared library on the command line.
-
The linker also identifies new undefined symbols while processing a
shared library. These undefined symbols are not added to the output object
and are not reported as unresolved, but the linker does consider these undefined
symbols as it processes additional objects on the command line.
COMMON SYMBOL RESOLUTION
A symbol's class determines how the linker will resolve it, particularly
when there are multiple objects, archives and shared libraries on the command
line that define the same symbol. In general, if the linker processes more
than one object defining the same text or data symbol, it reports an error
indicating that the symbol is multiply defined. On the other hand, certain
classes of symbols such as commons and allocated commons can be defined in
multiple objects and libraries without causing multiple-definition errors.
The linker uses symbol class, size, and command-line ordering to determine
which symbol definition to use in the output object. Symbols are selected
according to the following precedence, in descending order:
Data or text
Largest allocated common
Largest common
Common symbols are characterized by their size and type only. These
symbols are displayed as type C in
nm
output.
Allocated common symbols are commons that have an address as well as
a size and type. These symbols are displayed as type S or B in
nm
output.
All other symbols are either data, text, or undefined.
The linker searches archive libraries only to extract definitions for
symbols that are undefined. It does not replace an existing symbol definition
with a symbol of higher precedence extracted from an archive. The linker
applies the precedences rules only when choosing between multiple symbol definitions
in object files and shared libraries.
FILES
shared libraries
libraries, include files, and other files
compiler executable files
directory
directory
output file
SEE ALSO
as(1),
ar(1),
cc(1),
end(3),
loader(5)
Programmer's Guide
Assembly Language Programmer's Guide
Index
- NAME
-
- SYNOPSIS
-
- OPTIONS
-
- DESCRIPTION
-
- NOTES
-
- OBJECT AND LIBRARY ORDERING
-
- COMMON SYMBOL RESOLUTION
-
- FILES
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 02:42:47 GMT, October 02, 2010