ld(1)ld(1)NAMEld - link editor
SYNOPSISld [option...] file... [option...]
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-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 directo‐
ries. 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 combi‐
nation 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 ar‐
chive 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 exe‐
cution order of init routines. This option does not affect init rou‐
tines 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 rela‐
tive 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 behav‐
ior except for the following difference: if the library specified by
-qlx is not found, the linker does not produce error or warning mes‐
sages. 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 contin‐
uation 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 ta‐
ble; 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 sym‐
bols and suppresses “undefined symbol” diagnostics. Force defi‐
nition 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 seg‐
ments 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 load‐
ing 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 sym‐
bolic 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 addi‐
tional 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 cor‐
rect multiple for the resulting object type). The default
resulting object type is an OMAGIC file, and the default start‐
ing address of the text is the old value of _end rounded to SCN‐
ROUND as defined in the include file <scnhdr.h>. Using the
defaults, when this file is read into an already executing pro‐
gram, 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 auto‐
matic recognition of symbols prefixed with __init_ as initial‐
ization 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 sym‐
bols 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 exe‐
cutables. 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 sensi‐
tive. (Used for shared linkage only.) Convert all external sym‐
bols 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 wild‐
card 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 multi‐
ple times on a command line. The patterns use shell wildcard
characters (?, *, [, ]). The wildcard characters must be prop‐
erly 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. Pro‐
duce 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_unre‐
solved. This is the default behavior for linking executable pro‐
grams.
When building an executable program and -error_unresolved is in
effect, the output file is not marked as executable if unre‐
solved 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 speci‐
fied object from the shared object being created by the linker.
This option is used with -all and -shared, and is position sen‐
sitive. 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 ar‐
chives. 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 occur‐
rence of a -noso or -so_archive option. Require -l references
to resolve to archive libraries. Note that this option is posi‐
tion 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 allow‐
ing -l references to resolve to either shared objects or archive
libraries in shared or call_shared links. This option is posi‐
tion sensitive. Check the location of this shared object's seg‐
ments 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 loca‐
tion 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. Typi‐
cally, the option is used by system utilities for security pur‐
poses. 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 compo‐
nent 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 compo‐
nent 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 sym‐
bol into a termination routine. A termination routine is a rou‐
tine that is called without an argument when either the file
that contains the routine is unloaded or the program that con‐
tains 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 per‐
formed 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). Estab‐
lish 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 identi‐
fiers. No restrictions are placed on the names of version iden‐
tifiers; 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 ver‐
sion 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 sym‐
bol 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 breadth-
first search order (the default), the loader starts with a
shared object using a depth-first search order. If a symbol can‐
not 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 command can also be used
to ensure that the text and data segments addresses, respec‐
tively, are loaded into low memory. The -taso option, however,
in addition to setting default addresses for text and data seg‐
ments, 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 suit‐
able for input to the om post-link optimizer. This option should
be used only with the cc command.
DESCRIPTION
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 reloca‐
tion, resolves external symbols, builds tables and relocation informa‐
tion 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 sym‐
bol 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, _proce‐
dure_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 con‐
tains them is unloaded or when the program that contains them exits.
The linker also recognizes subsystem-generated initialization and ter‐
mination 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 order‐
ing scheme that governs the execution of the __INIT_ and __FINI_ rou‐
tines. 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 han‐
dling. For shared objects, this is always done because the programmer
creating the shared object might not know whether the program referenc‐
ing 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 com‐
mand 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 can‐
not be specified in dependency order, shared libraries should be
ordered before archive libraries. If necessary, archives can be speci‐
fied 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 cur‐
rently 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 process‐
ing 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, particu‐
larly 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 allo‐
cated 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 deter‐
mine 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 def‐
inition 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 ALSOas(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)