ld - link editor
ld [option...] file... [option...]
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-sensitive 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 -noarchive option or to archive libraries by the
-noso option. The -so_archive option removes either of
these search restrictions.
Use the following position-sensitive 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 linktime
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. Adjust the data
segment address for optimal loading when the system
page size is set to num. The argument num is a hexadecimal
number and must be a multiple of 8K
(0x2000). This option is ignored if the final
object is not a ZMAGIC 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. Establish a fill pattern for use in
filling the last page of the text section of a
ZMAGIC file to the page boundary. 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 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 sensitive.
(Used for shared linkage only.) Convert
all external symbols from objects following this
option into local symbols. This option is position
sensitive. (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. This option is position sensitive.
Turn off the -hidden option for a single symbol,
specified by pattern. Pattern matching uses shell
wildcard characters (?, *, [, ]). This option is
position sensitive. For more information, see
sh(1). Ignore any unresolved symbols that match
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). Set the RHF_NO_MOVE
bit in the DT_MIPS_FLAGS field of the dynamic
header. If this bit is set in a shared library,
sbin/loader will not relocate this shared library
at load time. The library will either be mapped at
its quickstart address or the load will fail with a
message. 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 return a nonzero error status when
unresolved symbols are encountered, except for
those matching -expect_unresolved. This is the
default behavior for linking executable programs.
When building an executable program and
-error_unresolved is in effect, the output file is
not marked as executable if unresolved symbols are
present.
When building shared libraries and -error_unresolved
is in effect, an output file (.so file) is
produced even if unresolved sysmbols are present,
overwriting any pre-existing output file with the
same name.
See the Programmer's Guide for information about
how to control the overwriting of linker output
files. Link in all of the objects from the
archives following this option. This option is used
with -shared and is position sensitive. Turn off
the -all option. This option is position sensitive.
Exclude the specified object from the shared object
being created by the linker. This option is used
with -all and -shared, and is position sensitive.
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 position sensitive 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 -noso or
-so_archive option. Require -l references to
resolve to archive libraries. Note that this option
is position sensitive 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 -noarchive or -so_archive
option. Turn off either the -noarchive or -noso
options allowing -l references to resolve to either
shared objects or archive libraries in shared or
call_shared links. This option is position sensitive.
Check the location of this shared object's
segments and make sure they stay out of the way of
other object's segments in 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 linking with
-shared or -call_shared. If an item in the path
supplied to -rpath is of the form $VARNAME or
${VARNAME}, the linker copies it to the output
file's rpath record without expanding it. The environment
variable references are preserved so that
the loader can expand them at run time. If you use
multiple -rpath options, only the last one specified
is accepted.
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. This option is used with
-shared. 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. This option is used with
-shared. 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 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 used 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
with -call_shared. Alters the search algorithm
used to resolve symbol references. Instead of
starting with the executable file using a breadthfirst
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 breadthfirst
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 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.
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, -l, -none,
-non_hidden, -noarchive, -noso, and -so_archive. They are
described in the OPTIONS section in this reference page.
The symbols _etext, _edata, _end, _ftext, _fdata, _fbss,
_gp, __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 cc(1)), 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.
The linker also recognizes subsystem-generated initialization
and termination routines that begin with the prefix
__INIT_ or __FINI_. User initialization and termination
routines should not have names starting with these prefixes.
The different types of initialization and termination routines
are run in the following order: Initialization routines:
Special initialization routines added by ld for
exception handling, speculative execution, and TLS (Thread
Local Storage). Initialization routines prefixed by
__INIT_, in alphabetic order. Initialization routines
added with -init or prefixed by __init_. Termination routines:
Termination routines added with -fini or prefixed
by __fini_. Termination routines prefixed by __FINI_, in
reverse alphabetic order. Special termination routines
added by ld for exception handling and TLS.
The __INIT_ and __FINI_ prefixes are followed by an
alphanumeric sequence-id string, for example,
__INIT_02_id-name-string. The sequence-id string (02_ in
the example) establishes a subsystem ordering scheme that
governs the execution of the __INIT_ and __FINI_ routines.
The following sequence-id strings are currently assigned:
Exception handling Speculative execution Thread local
storage (TLS)
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 and 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 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.
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 [Toc] [Back] 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 [Toc] [Back] 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 multipledefinition
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
(see nm(1)).
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.
shared libraries libraries, include files, and other files
compiler executable files directory directory output file
as(1), ar(1), cc(1), end(3), loader(5), nm(1)
Object File/Symbol Table Format Specification
Programmer's Guide
Assembly Language Programmer's Guide
ld(1)
[ Back ] |
