ld(1) User Commands ld(1)NAMEld - link-editor for object files
SYNOPSISld [-32 | -64] [-a | -r] [-b] [-Bdirect | nodirect]
[-B dynamic | static] [-B eliminate] [-B group] [-B local]
[-B reduce] [-B symbolic] [-c name] [-C] [-d y | n]
[-D [!]token1,[!]token2,...] [-e epsym] [-f name | -F name] [-G]
[-h name] [-i] [-I name] [-l x] [-L path] [-m] [-M mapfile]
[-N string] [-o outfile] [-p auditlib] [-P auditlib]
[-Q y | n] [-R path] [-s] [-S supportlib] [-t]
[-u symname] [-V] [-Y P,dirlist] [-z absexec]
[-z allextract | defaultextract | weakextract ]
[-z altexec64] [-z assert-deflib[=libname]]
[-z combreloc | nocombreloc ] [-z deferred | nodeferred]
[-z defs | nodefs] [-z direct | nodirect] [-z endfiltee]
[-z fatal-warnings | nofatal-warnings] [-z finiarray=function]
[-z globalaudit] [-z groupperm | nogroupperm]
[-z guidance[=item1,item2,...]] [-z help ]
[-z ignore | record] [-z initarray=function] [-z initfirst]
[-z interpose] [-z lazyload | nolazyload]
[-z ld32=arg1,arg2,...] [-z ld64=arg1,arg2,...]
[-z loadfltr] [-z mapfile-add=name] [-z muldefs]
[-z nocompstrtab] [-z nodefaultlib] [-z nodelete]
[-z nodlopen] [-z nodump] [-z noldynsym] [-z nopartial]
[-z noversion] [-z now] [-z origin] [-z preinitarray=function]
[-z redlocsym] [-z relaxreloc] [-z rescan-now] [-z rescan]
[-z rescan-start ... -z rescan-end]
[-z strip-class=[!]class1,[!]class2,...]
[-z stub] [-z symbolcap] [-z target=sparc|x86]
[-z text | textwarn | textoff] [-z verbose] [-z wrap=symbol]
filename ...
DESCRIPTION
The link-editor, ld, combines relocatable object files by resolving
symbol references to symbol definitions, together with performing relo‐
cations. ld operates in two modes, static or dynamic, as governed by
the -d option. In all cases, the default output of ld is left in the
file a.out. See NOTES.
In dynamic mode, -dy, the default, relocatable object files that are
provided as arguments are combined to produce a dynamic executable
file. This file is combined at runtime with any shared object files
that are provided as arguments. If the -G option is specified, relocat‐
able object files are combined to produce a shared object file. Without
the -G option, a dynamic executable file is created.
In static mode, -dn, relocatable object files that are provided as
arguments are combined to produce a static executable file. If the -r
option is specified, relocatable object files are combined to produce
one relocatable object file. See Static Executables.
The Solaris environment uses dynamic linking to combine relocatable
objects into dynamic executables and shared objects. This environment
tightly couples the work of the link-editor and the runtime linker,
ld.so.1(1). Both of these utilities, together with their related tech‐
nologies and utilities, are extensively documented in the Linker and
Libraries Guide.
If any argument is a library, ld by default searches the library
exactly once at the point the library is encountered on the argument
list. The library can be either a shared object or relocatable archive.
See ar.h(3HEAD)).
A shared object consists of an indivisible, whole unit that has been
generated by a previous link-edit of one or more input files. When the
link-editor processes a shared object, the entire contents of the
shared object become a logical part of the resulting output file image.
The shared object is not physically copied during the link-edit as its
actual inclusion is deferred until process execution. This logical
inclusion means that all symbol entries defined in the shared object
are made available to the link-editing process. See Chapter 4, Shared
Objects, in Linker and Libraries Guide.
For an archive library, ld loads only those routines that define an
unresolved external reference. ld searches the symbol table of the ar‐
chive library sequentially to resolve external references that can be
satisfied by library members. This search is repeated until no external
references can be resolved by the archive. Thus, the order of members
in the library is functionally unimportant, unless multiple library
members exist that define the same external symbol. Archive libraries
that have interdependencies can require multiple command line defini‐
tions, or the use of one of the -z rescan options. See Archive Process‐
ing in Linker and Libraries Guide.
ld is a cross link-editor, able to link 32-bit objects or 64-bit
objects, for SPARC or x86 targets. ld uses the ELF class and machine
type of the first relocatable object on the command line to govern the
mode in which to operate. The mixing of 32-bit objects and 64-bit
objects is not permitted. Similarly, only objects of a single machine
type are allowed. See the -32, -64 and -z target options, and the
LD_NOEXEC_64 environment variable.
Static Executables
The creation of static executables has been discouraged for many
releases. In fact, 64-bit system archive libraries have never been pro‐
vided. Because a static executable is built against system archive
libraries, the executable contains system implementation details. This
self-containment has a number of drawbacks.
o The executable is immune to the benefits of system patches
delivered as shared objects. The executable therefore, must
be rebuilt to take advantage of many system improvements.
o The ability of the executable to run on future releases can
be compromised.
o The duplication of system implementation details negatively
affects system performance.
With Solaris 10, 32-bit system archive libraries are no longer pro‐
vided. Without these libraries, specifically libc.a, the creation of
static executables is no longer achievable without specialized system
knowledge. However, the capability of ld to process static linking
options, and the processing of archive libraries, remains unchanged.
OPTIONS
The following options are supported.
-32 | -64
Creates a 32-bit, or 64-bit object.
By default, the class of the object being generated is determined
from the first ELF object processed from the command line. If no
objects are specified, the class is determined by the first object
encountered within the first archive processed from the command
line. If there are no objects or archives, the link-editor creates
a 32-bit object.
The -64 option is required to create a 64-bit object solely from a
mapfile.
The -32 or -64 options can also be used in the rare case of linking
entirely from an archive that contains a mixture of 32 and 64-bit
objects. If the first object in the archive is not the class of the
object that is required to be created, then the -32 or -64 option
can be used to direct the link-editor.
-a
In static mode only, produces a static executable file. Undefined
references are not permitted. This option is the default behavior
for static mode. The -a option can not be used with the -r option.
See Static Executables under DESCRIPTION.
-b
In dynamic mode only, provides no special processing for dynamic
executable relocations that reference symbols in shared objects.
Without the -b option, the link-editor applies techniques within a
dynamic executable so that the text segment can remain read-only.
One technique is the creation of special position-independent relo‐
cations for references to functions that are defined in shared
objects. Another technique arranges for data objects that are
defined in shared objects to be copied into the memory image of an
executable at runtime.
The -b option is intended for specialized dynamic objects and is
not recommended for general use. Its use suppresses all specialized
processing required to ensure an object's shareability, and can
even prevent the relocation of 64-bit executables.
-B direct | nodirect
These options govern direct binding. -B direct establishes direct
binding information by recording the relationship between each sym‐
bol reference together with the dependency that provides the defi‐
nition. In addition, direct binding information is established
between each symbol reference and an associated definition within
the object being created. The runtime linker uses this information
to search directly for a symbol in the associated object rather
than to carry out a default symbol search.
Direct binding information can only be established to dependencies
specified with the link-edit. Thus, you should use the -z defs
option. Objects that wish to interpose on symbols in a direct bind‐
ing environment should identify themselves as interposers with the
-z interpose option. The use of -B direct enables -z lazyload for
all dependencies.
The -B nodirect option prevents any direct binding to the inter‐
faces offered by the object being created. The object being created
can continue to directly bind to external interfaces by specifying
the -z direct option. See Chapter 9, Direct Bindings, in Linker and
Libraries Guide.
-B dynamic | static
Options governing library inclusion. -B dynamic is valid in dynamic
mode only. These options can be specified any number of times on
the command line as toggles: if the -B static option is given, no
shared objects are accepted until -B dynamic is seen. See the -l
option.
-B eliminate
Causes any global symbols, not assigned to a version definition, to
be eliminated from the symbol table. Version definitions can be
supplied by means of a mapfile to indicate the global symbols that
should remain visible in the generated object. This option achieves
the same symbol elimination as the auto-elimination directive that
is available as part of a mapfile version definition. This option
can be useful when combining versioned and non-versioned relocat‐
able objects. See also the -B local option and the -B reduce
option. See Defining Additional Symbols with a mapfile in Linker
and Libraries Guide.
-B group
Establishes a shared object and its dependencies as a group.
Objects within the group are bound to other members of the group at
runtime. This mode is similar to adding the object to the process
by using dlopen(3C) with the RTLD_GROUP mode. An object that has an
explicit dependency on a object identified as a group, becomes a
member of the group.
As the group must be self contained, use of the -B group option
also asserts the -z defs option.
-B local
Causes any global symbols, not assigned to a version definition, to
be reduced to local. Version definitions can be supplied by means
of a mapfile to indicate the global symbols that should remain vis‐
ible in the generated object. This option achieves the same symbol
reduction as the auto-reduction directive that is available as part
of a mapfile version definition. This option can be useful when
combining versioned and non-versioned relocatable objects. See also
the -B eliminate option and the -B reduce option. See Defining
Additional Symbols with a mapfile in Linker and Libraries Guide.
-B reduce
When generating a relocatable object, causes the reduction of sym‐
bolic information defined by any version definitions. Version defi‐
nitions can be supplied by means of a mapfile to indicate the
global symbols that should remain visible in the generated object.
By default, when a relocatable object is generated, version defini‐
tions are only recorded in the output image. The actual reduction
of symbolic information is carried out when the object is used in
the construction of a dynamic executable or shared object. The -B
reduce option is applied automatically when a dynamic executable or
shared object is created.
-B symbolic
In dynamic mode only. When building a shared object, binds refer‐
ences to global symbols to their definitions, if available, within
the object. Normally, references to global symbols within shared
objects are not bound until runtime, even if definitions are avail‐
able. This model allows definitions of the same symbol in an exe‐
cutable or other shared object to override the object's own defini‐
tion. ld issues warnings for undefined symbols unless -z defs over‐
rides.
The -B symbolic option is intended for specialized dynamic objects
and is not recommended for general use. To reduce the runtime relo‐
cation processing that is required an object, the creation of a
version definition is recommended.
-c name
Records the configuration file name for use at runtime. Configura‐
tion files can be employed to alter default search paths, provide a
directory cache, together with providing alternative object depen‐
dencies. See crle(1).
-C
Demangles C++ symbol names displayed in diagnostic messages.
-d y | n
When -d y, the default, is specified, ld uses dynamic linking. When
-d n is specified, ld uses static linking. See Static Executables
under DESCRIPTION, and -B dynamic|static.
-D [!]token1,[!]token2,...
Prints debugging information as specified by each token, to the
standard error. The special token help indicates the full list of
tokens available. See Debugging Aids in Linker and Libraries Guide.
-e epsym
--entry epsym
Sets the entry point address for the output file to be the symbol
epsym.
-f name
--auxiliary name
Useful only when building a shared object. Specifies that the sym‐
bol table of the shared object is used as an auxiliary filter on
the symbol table of the shared object specified by name. Multiple
instances of this option are allowed. This option can not be com‐
bined with the -F option. See Generating Auxiliary Filters in
Linker and Libraries Guide.
-F name
--filter name
Useful only when building a shared object. Specifies that the sym‐
bol table of the shared object is used as a filter on the symbol
table of the shared object specified by name. Multiple instances of
this option are allowed. This option can not be combined with the
-f option. See Generating Standard Filters in Linker and Libraries
Guide.
-G
-shared
In dynamic mode only, produces a shared object. Undefined symbols
are allowed. See Chapter 4, Shared Objects, in Linker and Libraries
Guide.
-h name
--soname name
In dynamic mode only, when building a shared object, records name
in the object's dynamic section. name is recorded in any dynamic
objects that are linked with this object rather than the object's
file system name. Accordingly, name is used by the runtime linker
as the name of the shared object to search for at runtime. See
Recording a Shared Object Name in Linker and Libraries Guide.
-i
Ignores LD_LIBRARY_PATH. This option is useful when an
LD_LIBRARY_PATH setting is in effect to influence the runtime
library search, which would interfere with the link-editing being
performed.
-I name
--dynamic-linker name
When building an executable, uses name as the path name of the
interpreter to be written into the program header. The default in
static mode is no interpreter. In dynamic mode, the default is the
name of the runtime linker, ld.so.1(1). Either case can be overrid‐
den by -I name. exec(2) loads this interpreter when the a.out is
loaded, and passes control to the interpreter rather than to the
a.out directly.
-l x
--library x
Searches a library libx.so or libx.a, the conventional names for
shared object and archive libraries, respectively. In dynamic mode,
unless the -B static option is in effect, ld searches each direc‐
tory specified in the library search path for a libx.so or libx.a
file. The directory search stops at the first directory containing
either. ld chooses the file ending in .so if -lx expands to two
files with names 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 -B
static option is in effect, ld selects only the file ending in .a.
ld searches a library when the library is encountered, so the
placement of -l is significant. See Linking With Additional
Libraries in Linker and Libraries Guide.
-L path
--library-path path
Adds path to the library search directories. ld searches for
libraries first in any directories specified by the -L options and
then in the standard directories. This option is useful only if the
option precedes the -l options to which the -L option applies. See
Directories Searched by the Link-Editor in Linker and Libraries
Guide.
The environment variable LD_LIBRARY_PATH can be used to supplement
the library search path, however the -L option is recommended, as
the environment variable is also interpreted by the runtime envi‐
ronment. See LD_LIBRARY_PATH under ENVIRONMENT VARIABLES.
-m
Produces a memory map or listing of the input/output sections,
together with any non-fatal multiply-defined symbols, on the stan‐
dard output.
-M mapfile
Reads mapfile as a text file of directives to ld. This option can
be specified multiple times. If mapfile is a directory, then all
regular files, as defined by stat(2), within the directory are pro‐
cessed. See Chapter 10, Mapfiles, in Linker and Libraries Guide.
Example mapfiles are provided in /usr/lib/ld. See FILES.
-N string
This option causes a DT_NEEDED entry to be added to the .dynamic
section of the object being built. The value of the DT_NEEDED
string is the string that is specified on the command line. This
option is position dependent, and the DT_NEEDED .dynamic entry is
relative to the other dynamic dependencies discovered on the link-
edit line. This option is useful for specifying dependencies within
device driver relocatable objects when combined with the -dy and -r
options.
-o outfile
--output outfile
Produces an output object file that is named outfile. The name of
the default object file is a.out.
-p auditlib
Identifies an audit library, auditlib. This audit library is used
to audit the object being created at runtime. A shared object iden‐
tified as requiring auditing with the -p option, has this require‐
ment inherited by any object that specifies the shared object as a
dependency. See the -P option. See Runtime Linker Auditing Inter‐
face in Linker and Libraries Guide.
-P auditlib
Identifies an audit library, auditlib. This audit library is used
to audit the dependencies of the object being created at runtime.
Dependency auditing can also be inherited from dependencies that
are identified as requiring auditing. See the -p option, and the -z
globalaudit option. See Runtime Linker Auditing Interface in Linker
and Libraries Guide.
-Q y | n
Under -Q y, an ident string is added to the .comment section of the
output file. This string identifies the version of the ld used to
create the file. This results in multiple ld idents when there have
been multiple linking steps, such as when using ld-r. This identi‐
fication is identical with the default action of the cc command. -Q
n suppresses version identification. .comment sections can be
manipulated by the mcs(1) utility.
-r
--relocatable
Combines relocatable objects to produce one relocatable object
file. ld does not complain about unresolved references. This option
cannot be used with the -a option.
-R path
-rpath path
A colon-separated list of directories used to specify library
search directories to the runtime linker. If present and not NULL,
the path is recorded in the output object file and passed to the
runtime linker. Multiple instances of this option are concatenated
together with each path separated by a colon. See Directories
Searched by the Runtime Linker in Linker and Libraries Guide.
The use of a runpath within an associated object is preferable to
setting global search paths such as through the LD_LIBRARY_PATH
environment variable. Only the runpaths that are necessary to find
the objects dependencies should be recorded. ldd(1) can also be
used to discover unused runpaths in dynamic objects, when used with
the -U option.
Various tokens can also be supplied with a runpath that provide a
flexible means of identifying system capabilities or an objects
location. See Chapter 6, Establishing Dependencies with Dynamic
String Tokens, in Linker and Libraries Guide. The $ORIGIN token is
especially useful in allowing dynamic objects to be relocated to
different locations in the file system.
-s
--strip-all
Strip any symbolic information from the output file. These options
are equivalent to using the -z strip-class option with the debug
and symbol class identifiers. See also the -z redlocsym and -z nol‐
dynsym options.
-S supportlib
The shared object supportlib is loaded with ld and given informa‐
tion regarding the linking process. Shared objects that are defined
by using the -S option can also be supplied using the SGS_SUPPORT
environment variable. See Link-Editor Support Interface in Linker
and Libraries Guide.
-t
Turns off the warning for multiply-defined symbols that have dif‐
ferent sizes or different alignments.
-u symname
--undefined symname
Enters symname as an undefined symbol in the symbol table. This
option is useful for loading entirely from an archive library. In
this instance, an unresolved reference is needed to force the load‐
ing of the first routine. The placement of this option on the com‐
mand line is significant. This option must be placed before the
library that defines the symbol. See Defining Additional Symbols
with the u option in Linker and Libraries Guide.
-V
--version
Outputs a message giving information about the version of ld being
used.
-Y P,dirlist
Changes the default directories used for finding libraries. dirlist
is a colon-separated path list.
-z absexec
Useful only when building a dynamic executable. Specifies that ref‐
erences to external absolute symbols should be resolved immediately
instead of being left for resolution at runtime. In very special‐
ized circumstances, this option removes text relocations that can
result in excessive swap space demands by an executable.
-z allextract | defaultextract | weakextract
--whole-archive | --no-whole-archive
Alters the extraction criteria of objects from any archives that
follow. By default, archive members are extracted to satisfy unde‐
fined references and to promote tentative definitions with data
definitions. Weak symbol references do not trigger extraction.
Under the -z allextract or --whole-archive options, all archive
members are extracted from the archive. Under -z weakextract, weak
references trigger archive extraction. The -z defaultextract or
--no-whole-archive options provide a means of returning to the
default following use of the former extract options. See Archive
Processing in Linker and Libraries Guide.
-z altexec64
Execute the 64-bit ld. Historically, the class of link-editor that
was executed was determined by the class of ELF object being cre‐
ated. Now, the class of the link-editor that is executed is deter‐
mined by the class of the underlying system. Typically this is
64-bit. This option is maintained for backward compatibility.
-z assert-deflib=[libname]
Enables warning messages for libraries specified with the -l com‐
mand line option that are found by examining the default search
paths provided by the link-editor. If a libname value is provided,
the default library warning feature is enabled, and the specified
library is added to a list of libraries for which no warnings will
be issued. Multiple -z assert-deflib options can be specified in
order to specify multiple libraries for which warnings should not
be issued.
The libname value should be the name of the library file, as found
by the link-editor, without any path components. For example, the
following enables default library warnings, and excludes the stan‐
dard C library.
ld ... -z assert-deflib=libc.so ...
-z assert-deflib is a specialized option, primarily of interest in
build environments where multiple objects with the same name exist
and tight control over the library used is required. If is not
intended for general use.
-z combreloc | nocombreloc
By default, ld combines multiple relocation sections when building
executables or shared objects. This section combination differs
from relocatable objects, in which relocation sections are main‐
tained in a one-to-one relationship with the sections to which the
relocations must be applied. The -z nocombreloc option disables
this merging of relocation sections, and preserves the one-to-one
relationship found in the original relocatable objects.
ld sorts the entries of data relocation sections by their symbol
reference. This sorting reduces runtime symbol lookup. When multi‐
ple relocation sections are combined, this sorting produces the
least possible relocation overhead when objects are loaded into
memory, and speeds the runtime loading of dynamic objects.
Historically, the individual relocation sections were carried over
to any executable or shared object, and the -z combreloc option was
required to enable the relocation section merging previously
described. Relocation section merging is now the default. The -z
combreloc option is still accepted for the benefit of old build
environments, but the option is unnecessary, and has no effect.
-z deferred | nodeferred
Enables or disables the marking of dynamic dependencies as
deferred. Dynamic dependencies which are marked deferred, are also
marked as lazy loadable, and are not loaded at initial process
start-up. The loading of deferred dependencies is delayed until
process execution, when the first binding to a deferred reference
is made. Unlike basic lazy loadable dependencies, deferred depen‐
dencies are not processed as part of LD_BIND_NOW processing, or
through dlopen(3C) with the RTLD_NOW flag. See Testing for Func‐
tionality in Linker and Libraries Guide.
The use of deferred dependencies, together with dlsym(3C) and the
RTLD_PROBE handle, provides a flexible mechanism, and natural cod‐
ing style, for testing for functionality.
-z defs | nodefs
--no-undefined
The -z defs option and the --no-undefined option force a fatal
error if any undefined symbols remain at the end of the link. This
mode is the default when an executable is built. For historic rea‐
sons, this mode is not the default when building a shared object.
Use of the -z defs option is recommended, as this mode assures the
object being built is self-contained. A self-contained object has
all symbolic references resolved internally, or to the object's
immediate dependencies.
The -z nodefs option allows undefined symbols. For historic rea‐
sons, this mode is the default when a shared object is built. When
used with executables, the behavior of references to such undefined
symbols is unspecified. Use of the -z nodefs option is not recom‐
mended.
-z direct | nodirect
Enables or disables direct binding to any dependencies that follow
on the command line. These options allow finer control over direct
binding than the global counterpart -B direct. The -z direct option
also differs from the -B direct option in the following areas.
Direct binding information is not established between a symbol ref‐
erence and an associated definition within the object being cre‐
ated. Lazy loading is not enabled.
-z endfiltee
Marks a filtee so that when processed by a filter, the filtee ter‐
minates any further filtee searches by the filter. See Reducing
Filtee Searches in Linker and Libraries Guide.
-z fatal-warnings | nofatal-warnings
--fatal-warnings | --no-fatal-warnings
The -z fatal-warnings and the --fatal-warnings option cause the
link-editor to treat warnings as fatal errors.
The -z nofatal-warnings and the --no-fatal-warnings option cause
the link-editor to treat warnings as non-fatal. This is the default
behavior.
-z finiarray=function
Appends an entry to the .fini_array section of the object being
built. If no .fini_array section is present, a section is created.
The new entry is initialized to point to function. See Initializa‐
tion and Termination Sections in Linker and Libraries Guide.
-z globalaudit
This option supplements an audit library definition that has been
recorded with the -P option. This option is only meaningful when
building a dynamic executable. Audit libraries that are defined
within an object with the -P option typically allow for the audit‐
ing of the immediate dependencies of the object. The -z globalaudit
promotes the auditor to a global auditor, thus allowing the audit‐
ing of all dependencies. See Invoking the Auditing Interface in
Linker and Libraries Guide.
An auditor established with the -P option and the -z globalaudit
option, is equivalent to the auditor being established with the
LD_AUDIT environment variable. See ld.so.1(1).
-z groupperm | nogroupperm
Assigns, or deassigns each dependency that follows to a unique
group. The assignment of a dependency to a group has the same
effect as if the dependency had been built using the -B group
option.
-z guidance[=item1,item2,...]
Provide guidance messages to suggest ld options that can improve
the quality of the resulting object, or which are otherwise consid‐
ered to be beneficial. The specific guidance offered is subject to
change over time as the system evolves. Obsolete guidance offered
by older versions of ld may be dropped in new versions. Similarly,
new guidance may be added to new versions of ld. Guidance therefore
always represents current best practices.
It is possible to enable guidance, while preventing specific guid‐
ance messages, by providing a list of item tokens, representing the
class of guidance to be suppressed. In this way, unwanted advice
can be suppressed without losing the benefit of other guidance.
Unrecognized item tokens are quietly ignored by ld, allowing a
given ld command line to be executed on a variety of older or newer
versions of Solaris.
The guidance offered by the current version of ld, and the item
tokens used to disable these messages, are as follows.
Specify Required Dependencies
Dynamic executables and shared objects should explicitly define
all of the dependencies they require. Guidance recommends the
use of the -z defs option, should any symbol references remain
unsatisfied when building dynamic objects. This guidance can be
disabled with -z guidance=nodefs.
Do Not Specify Non-Required Dependencies
Dynamic executables and shared objects should not define any
dependencies that do not satisfy the symbol references made by
the dynamic object. Guidance recommends that unused dependen‐
cies be removed. This guidance can be disabled with -z guid‐
ance=nounused.
Lazy Loading
Dependencies should be identified for lazy loading. Guidance
recommends the use of the -z lazyload option should any depen‐
dency be processed before either a -z lazyload or -z nolazyload
option is encountered. This guidance can be disabled with -z
guidance=nolazyload.
Direct Bindings
Dependencies should be referenced with direct bindings. Guid‐
ance recommends the use of the -B direct, or -z direct options
should any dependency be processed before either of these
options, or the -z nodirect option is encountered. This guid‐
ance can be disabled with -z guidance=nodirect.
Pure Text Segment
Dynamic objects should not contain relocations to non-writable,
allocable sections. Guidance recommends compiling objects with
Position Independent Code (PIC) should any relocations against
the text segment remain, and neither the -z textwarn or -z
textoff options are encountered. This guidance can be disabled
with -z guidance=notext.
Mapfile Syntax
All mapfiles should use the version 2 mapfile syntax. Guidance
recommends the use of the version 2 syntax should any mapfiles
be encountered that use the version 1 syntax. This guidance can
be disabled with -z guidance=nomapfile.
Library Search Path
Inappropriate dependencies that are encountered by ld are qui‐
etly ignored. For example, a 32-bit dependency that is encoun‐
tered when generating a 64-bit object is ignored. These depen‐
dencies can result from incorrect search path settings, such as
supplying an incorrect -L option. Although benign, this depen‐
dency processing is wasteful, and might hide a build problem
that should be solved. Guidance recommends the removal of any
inappropriate dependencies. This guidance can be disabled with
-z guidance=nolibpath.
In addition, -z guidance=noall can be used to entirely disable the
guidance feature. Link-Editor Quick Reference in Linker and
Libraries Guide for more information on guidance and advice for
building better objects.
-z help
--help
Print a summary of the command line options on the standard output
and exit.
-z ignore | record
Ignores, or records, dynamic dependencies that are not referenced
as part of the link-edit. Ignores, or records, unreferenced ELF
sections from the relocatable objects that are read as part of the
link-edit. By default, -z record is in effect.
If an ELF section is ignored, the section is eliminated from the
output file being generated. A section is ignored when three condi‐
tions are true. The eliminated section must contribute to an allo‐
catable segment. The eliminated section must provide no global sym‐
bols. No other section from any object that contributes to the
link-edit, must reference an eliminated section.
-z initarray=function
Appends an entry to the .init_array section of the object being
built. If no .init_array section is present, a section is created.
The new entry is initialized to point to function. See Initializa‐
tion and Termination Sections in Linker and Libraries Guide.
-z initfirst
Marks the object so that its runtime initialization occurs before
the runtime initialization of any other objects brought into the
process at the same time. In addition, the object runtime finaliza‐
tion occurs after the runtime finalization of any other objects
removed from the process at the same time. This option is only
meaningful when building a shared object.
-z interpose
Marks the object as an interposer. At runtime, an object is identi‐
fied as an explicit interposer if the object has been tagged using
the -z interpose option. An explicit interposer is also established
when an object is loaded using the LD_PRELOAD environment variable.
Implicit interposition can occur because of the load order of
objects, however, this implicit interposition is unknown to the
runtime linker. Explicit interposition can ensure that interposi‐
tion takes place regardless of the order in which objects are
loaded. Explicit interposition also ensures that the runtime linker
searches for symbols in any explicit interposers when direct bind‐
ings are in effect.
-z lazyload | nolazyload
Enables or disables the marking of dynamic dependencies to be
lazily loaded. Dynamic dependencies which are marked lazyload are
not loaded at initial process start-up. These dependencies are
delayed until the first binding to the object is made. Note: Lazy
loading requires the correct declaration of dependencies, together
with associated runpaths for each dynamic object used within a
process. See Lazy Loading of Dynamic Dependencies in Linker and
Libraries Guide.
-z ld32=arg1,arg2,...
-z ld64=arg1,arg2,...
The class of the link-editor is affected by the class of the output
file being created and by the capabilities of the underlying oper‐
ating system. The -z ld[32|64] options provide a means of defining
any link-editor argument. The defined argument is only interpreted,
respectively, by the 32-bit class or 64-bit class of the link-edi‐
tor.
For example, support libraries are class specific, so the correct
class of support library can be ensured using:
ld ... -z ld32=-Saudit32.so.1 -z ld64=-Saudit64.so.1 ...
-z loadfltr
Marks a filter to indicate that filtees must be processed immedi‐
ately at runtime. Normally, filter processing is delayed until a
symbol reference is bound to the filter. The runtime processing of
an object that contains this flag mimics that which occurs if the
LD_LOADFLTR environment variable is in effect. See the ld.so.1(1).
-z mapfile-add=name
Adds name to the list of known mapfile conditional input expression
predicates. This option is equivalent to placing the following
lines at the top of the first mapfile read by the link-editor.
$mapfile_version 2
$add name
Names entered via -z mapfile-add can be used with mapfile $if and
$elif directives to conditionally process mapfile input. See Chap‐
ter 10, Mapfiles in Linker and Libraries Guide.
-z muldefs
--allow-multiple-definition
Allows multiple symbol definitions. By default, multiple symbol
definitions that occur between relocatable objects result in a
fatal error condition. This option, suppresses the error condition,
allowing the first symbol definition to be taken.
-z nocompstrtab
Disables the compression of ELF string tables. By default, string
compression is applied to SHT_STRTAB sections, and to SHT_PROGBITS
sections that have their SHF_MERGE and SHF_STRINGS section flags
set.
-z nodefaultlib
Marks the object so that the runtime default library search path,
used after any LD_LIBRARY_PATH or runpaths, is ignored. This option
implies that all dependencies of the object can be satisfied from
its runpath.
-z nodelete
Marks the object as non-deletable at runtime. This mode is similar
to adding the object to the process by using dlopen(3C) with the
RTLD_NODELETE mode.
-z nodlopen
Marks the object as not available to dlopen(3C), either as the
object specified by the dlopen(), or as any form of dependency
required by the object specified by the dlopen(). This option is
only meaningful when building a shared object.
-z nodump
Marks the object as not available to dldump(3C).
-z noldynsym
Prevents the inclusion of a .SUNW_ldynsym section in a dynamic exe‐
cutable or shared object. The .SUNW_ldynsym section augments the
.dynsym section by providing symbols for local functions. Local
function symbols allow debuggers to display local function names in
stack traces from stripped programs. Similarly, dladdr(3C) is able
to supply more accurate results.
The -z noldynsym option also prevents the inclusion of the two sym‐
bol sort sections that are related to the .SUNW_ldynsym section.
The .SUNW_dynsymsort section provides sorted access to regular
function and variable symbols. The .SUNW_dyntlssort section pro‐
vides sorted access to thread local storage (TLS) variable symbols.
The .SUNW_ldynsym, .SUNW_dynsymsort, and .SUNW_dyntlssort sections,
which becomes part of the allocable text segment of the resulting
file, cannot be removed by strip(1). Therefore, the -z noldynsym
option is the only way to prevent their inclusion.
-z nopartial
Partially initialized symbols, that are defined within relocatable
objects, are expanded in the output file being generated.
-z noversion
Does not record any versioning sections. Any version sections or
associated .dynamic section entries are not generated in the output
image.
-z now
Marks the object as requiring non-lazy runtime binding. This mode
is similar to adding the object to the process by using dlopen(3C)
with the RTLD_NOW mode. This mode is also similar to having the
LD_BIND_NOW environment variable in effect. See ld.so.1(1).
-z origin
Marks the object as requiring immediate $ORIGIN processing at run‐
time. This option is only maintained for historic compatibility, as
the runtime analysis of objects to provide for $ORIGIN processing
is now default.
-z preinitarray=function
Appends an entry to the .preinit_array section of the object being
built. If no .preinit_array section is present, a section is cre‐
ated. The new entry is initialized to point to function. See Ini‐
tialization and Termination Sections in Linker and Libraries Guide.
-z redlocsym
Eliminates all local symbols except for the SECT symbols from the
symbol table SHT_SYMTAB. All relocations that refer to local sym‐
bols are updated to refer to the corresponding SECT symbol. This
option allows specialized objects to greatly reduce their symbol
table sizes. See also the -z strip-class and -z noldynsym options.
Although useful for special objects such as those used within the
operating system kernel, the -z redlocsym option is not recommended
for general use. The size of the symbol table SHT_SYMTAB does not
effect runtime behavior, and the elimination of local symbols can
negatively effect process observability. Eliminated local symbols
can reduce the debugging information that is generated using the
compiler drivers -g option. Eliminated local symbols will also
remove the information normally written to the .SUNW_ldynsym sec‐
tion, reducing the effectiveness of debuggers and tools such as
pstack(1) and truss(1).
-z relaxreloc
ld normally issues a fatal error upon encountering a relocation
using a symbol that references an eliminated COMDAT section. If -z
relaxreloc is enabled, ld instead redirects such relocations to the
equivalent symbol in the COMDAT section that was kept. -z relaxre‐
loc is a specialized option, mainly of interest to compiler
authors, and is not intended for general use.
-z rescan-now
-z rescan
These options rescan the archive files that are provided to the
link-edit. By default, archives are processed once as the archives
appear on the command line. Archives are traditionally specified at
the end of the command line so that their symbol definitions
resolve any preceding references. However, specifying archives mul‐
tiple times to satisfy their own interdependencies can be neces‐
sary.
-z rescan-now is a positional option, and is processed by the link-
editor immediately when encountered on the command line. All ar‐
chives seen on the command line up to that point are immediately
reprocessed in an attempt to locate additional archive members that
resolve symbol references. This archive rescanning is repeated
until a pass over the archives occurs in which no new members are
extracted.
-z rescan is a position independent option. The link-editor defers
the rescan operation until after it has processed the entire com‐
mand line, and then initiates a final rescan operation over all ar‐
chives seen on the command line. The -z rescan operation can inter‐
act incorrectly with objects that contain initialization (.init) or
finalization (.fini) sections, preventing the code in those sec‐
tions from running. For this reason, -z rescan is deprecated, and
use of -z rescan-now is advised.
-z rescan-start ... -z rescan-end
--start-group ... --end-group
-( ... -)
Defines an archive rescan group. This is a positional construct,
and is processed by the link-editor immediately upon encountering
the closing delimiter option. Archives found within the group
delimiter options are reprocessed as a group in an attempt to
locate additional archive members that resolve symbol references.
This archive rescanning is repeated until a pass over the archives
On the occurs in which no new members are extracted. Archive rescan
groups cannot be nested.
-z strip-class=[!]class1,[!]class2,...
Strip a specific class of section from any input objects, prevent‐
ing these sections from being added to the output file. This option
provides fine grained control over the sections that can be omitted
from the output file.
The strip classes described below only apply to non-allocatable
sections.
Each class token can be prepended with a '!' to indicate that the
class should not be removed. This definition can be useful when
combined with the nonalloc class. For example, using '-z strip-
class=nonalloc,!comment' removes all non-allocatable sections
except for the comment section.
The following classes of section can be defined.
nonalloc
Strip any non-allocatable section. These sections are identi‐
fied as not including the SHF_ALLOC section flag. This class
can encapsulate many of the other classes, and is often suffi‐
cient by itself to remove any unwanted sections. However, the
symbol class of sections are not captured by this class.
annotate
Strip any annotation section. These sections are identified by
having a SHT_SUNW_ANNOTATE section type.
comment
Strip any comment section. These sections are identified by
having a .comment section name. Alternatively, the mcs(1) com‐
mand is commonly used to manipulate comment sections.
debug
Strip sections commonly used to contain debugging data. These
sections are identified by having a .compcom, .line, .stab*, or
.debug* section name. These sections are also identified by
having a SHT_SUNW_DEBUG* section type.
exclude
Strip any excludable section. These sections are identified by
having a SHF_EXCLUDE section flag. This class can be useful
when creating a relocatable object. By default, such sections
are automatically excluded when a dynamic executable or shared
object is created, and are retained when creating a relocatable
object.
note
Strip any note section. These sections are identified by having
a SHT_NOTE section type.
symbol
Strip any non-allocatable symbol table and string table sec‐
tions, providing the output file is not a relocatable object.
These sections are identified by having a SHT_SYMTAB section
type. Any associated string table is also removed.
-z stub
Produces a stub shared object. A stub object is a shared object,
built entirely from mapfiles, that supplies the same linking inter‐
face as the real object, while containing no code or data. Stub
objects cannot be used at runtime. However, an application can be
built against a stub object, where the stub object provides the
real object name to be used at runtime, and then use the real
object at runtime.
Stub objects can only be produced for shared objects, and a mapfile
defining the global symbols to be exported must be supplied. The -G
and -M options are therefore required when -z stub is used. When
building a stub object, the link-editor ignores any object or
library files specified on the command line, and these files need
not exist in order to build a stub. Since the compilation step can
be omitted, and because the link-editor has relatively little work
to do, stub objects can be built very quickly.
See Stub Objects in Linker and Libraries Guide.
-z symbolcap
Convert a relocatable object that defines object capabilities into
a relocatable object that defines symbol capabilities. See Convert‐
ing Object Capabilities to Symbol Capabilities in Linker and
Libraries Guide.
-z target=sparc|x86
Specifies the machine type for the output object. Supported targets
are SPARC and x86. The 32-bit machine type for the specified target
is used unless the -64 option is also present, in which case the
corresponding 64-bit machine type is used. By default, the machine
type of the object being generated is determined from the first ELF
object processed from the command line. If no objects are speci‐
fied, the machine type is determined by the first object encoun‐
tered within the first archive processed from the command line. If
there are no objects or archives, the link-editor assumes the
native machine. This option is useful when creating an object
directly with ld whose input is solely from a mapfile. See the -M
option. It can also be useful in the rare case of linking entirely
from an archive that contains objects of different machine types
for which the first object is not of the desired machine type.
-z text
In dynamic mode only, forces a fatal error if any relocations
against non-writable, allocatable sections remain. For historic
reasons, this mode is not the default when building an executable
or shared object. However, its use is recommended to ensure that
the text segment of the dynamic object being built is shareable
between multiple running processes. A shared text segment incurs
the least relocation overhead when loaded into memory. See Posi‐
tion-Independent Code in Linker and Libraries Guide.
-z textoff
In dynamic mode only, allows relocations against all allocatable
sections, including non-writable ones. This mode is the default
when building a shared object.
-z textwarn
In dynamic mode only, lists a warning if any relocations against
non-writable, allocatable sections remain. This mode is the default
when building an executable.
-z verbose
This option provides additional warning diagnostics during a link-
edit. Presently, this option enables the following warnings.
o Suspicious use of displacement relocations.
o Restricted use of static TLS relocations when building
shared objects.
o Symbol visibility inconsistencies.
In the future, this option might be enhanced to provide additional
diagnostics that are deemed too noisy to be generated by default.
-zwrap=symbol
-wrap= symbol
--wrap= symbol
Rename undefined references to symbol in order to allow wrapper
code to be linked into the output object without having to modify
source code. When -z wrap is specified, all undefined references to
symbol are modified to reference __wrap_symbol, and all references
to __real_symbol are modified to reference symbol. The user is
expected to provide an object containing the __wrap_symbol func‐
tion. This wrapper function can call __real_symbol in order to ref‐
erence the actual function being wrapped.
The following is an example of a wrapper for the malloc(3C) func‐
tion.
void *
__wrap_malloc(size_t c)
{
(void) printf("malloc called with %zu0, c);
return (__real_malloc(c));
}
If you link other code with this file using -z wrap=malloc to com‐
pile all the objects, then all calls to malloc call the function
__wrap_malloc instead. The call to __real_malloc calls the real
malloc function.
The real and wrapped functions should be maintained in separate
source files. Otherwise, the compiler or assembler may resolve the
call instead of leaving that operation for the link-editor to carry
out, and prevent the wrap from occurring.
ENVIRONMENT VARIABLES
LD_ALTEXEC
An alternative link-editor path name. ld executes, and passes con‐
trol to this alternative link-editor. This environment variable
provides a generic means of overriding the default link-editor that
is called from the various compiler drivers. See the -z altexec64
option.
LD_LIBRARY_PATH
A list of directories in which to search for the libraries speci‐
fied using the -l option. Multiple directories are separated by a
colon. In the most general case, this environment variable contains
two directory lists separated by a semicolon.
dirlist1;dirlist2
If ld is called with any number of occurrences of -L, as in:
ld ... -Lpath1 ... -Lpathn ...
then the search path ordering is:
dirlist1 path1 ... pathn dirlist2 LIBPATH
When the list of directories does not contain a semicolon, the list
is interpreted as dirlist2.
The LD_LIBRARY_PATH environment variable also affects the runtime
linkers search for dynamic dependencies.
This environment variable can be specified with a _32 or _64 suf‐
fix. This makes the environment variable specific, respectively, to
32-bit or 64-bit processes and overrides any non-suffixed version
of the environment variable that is in effect.
LD_NOEXEC_64
Suppresses the automatic execution of the 64-bit link-editor. By
default, the link-editor executes the 64-bit version when the ELF
class of the first relocatable object identifies a 64-bit object.
The 64-bit image that a 32-bit link-editor can create, has some
limitations. However, some link-edits might find the use of the
32-bit link-editor faster.
LD_OPTIONS
A default set of options to ld. LD_OPTIONS is interpreted by ld
just as though its value had been placed on the command line, imme‐
diately following the name used to invoke ld, as in:
ld $LD_OPTIONS ... other-arguments ...
LD_RUN_PATH
An alternative mechanism for specifying a runpath to the link-edi‐
tor. See the -R option. If both LD_RUN_PATH and the -R option are
specified, -R supersedes.
SGS_SUPPORT
Provides a colon-separated list of shared objects that are loaded
with the link-editor and given information regarding the linking
process. This environment variable can be specified with a _32 or
_64 suffix. This makes the environment variable specific, respec‐
tively, to the 32-bit or 64-bit class of ld and overrides any non-
suffixed version of the environment variable that is in effect. See
the -S option.
Notice that environment variable-names that begin with the characters
'LD_' are reserved for possible future enhancements to ld and
ld.so.1(1).
FILES
libx.so shared object libraries.
libx.a archive libraries.
a.out default output file.
LIBPATH For 32-bit libraries, the default search path is /lib,
followed by /usr/lib. For 64-bit libraries, the default
search path is /lib/64, followed by /usr/lib/64.
/usr/lib/ld A directory containing several mapfiles that can be used
during link-editing. These mapfiles provide various
capabilities, such as defining memory layouts, aligning
bss, and defining non-executable stacks.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │system/linker │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Committed │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOas(1), crle(1), gprof(1), ld.so.1(1), ldd(1), mcs(1), pvs(1), strip(1),
exec(2), stat(2), dlopen(3C), dldump(3C), elf(3ELF), ar.h(3HEAD),
a.out(4), attributes(5)
Linker and Libraries Guide
NOTES
Default options applied by ld are maintained for historic reasons. In
today's programming environment, where dynamic objects dominate, alter‐
native defaults would often make more sense. However, historic defaults
must be maintained to ensure compatibility with existing program devel‐
opment environments. Historic defaults are called out wherever possible
in this manual. For a description of the current recommended options,
see Chapter 7, Link-Editor Quick Reference, in Linker and Libraries
Guide.
If the file being created by ld already exists, the file is unlinked
after all input files have been processed. A new file with the speci‐
fied name is then created. This allows ld to create a new version of
the file, while simultaneously allowing existing processes that are
accessing the old file contents to continue running. If the old file
has no other links, the disk space of the removed file is freed when
the last process referencing the file terminates.
The behavior of ld when the file being created already exists was
changed with Solaris 11. In older versions, the existing file was
rewritten in place, an approach with the potential to corrupt any run‐
ning processes that is using the file. This change has an implication
for output files that have multiple hard links in the file system. Pre‐
viously, all links would remain intact, with all links accessing the
new file contents. The new ld behavior breaks such links, with the
result that only the specified output file name references the new
file. All the other links continue to reference the old file. To ensure
consistent behavior, applications that rely on multiple hard links to
linker output files should explicitly remove and relink the other file
names.
SunOS 5.10 13 Jun 2012 ld(1)