ld - link-editor for object files
ld [-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 token,...] [-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 aslr[=state]] [-z assert-deflib] [ -z assert-deflib=libname]
[ -z combreloc | nocombreloc ] [-z defs | nodefs]
[ -z direct | nodirect] [-z endfiltee]
[ -z fatal-warnings | nofatal-warnings ] [-z finiarray=function]
[ -z globalaudit] [-z groupperm | nogroupperm]
[ -z guidance[=id1,id2...] [-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 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 recan] [-z rescan-start ... -z rescan-end]]
[ -z target=sparc|x86] [-z text | textwarn | textoff]
[ -z type=exec|kmod|reloc|shared]
[ -z verbose] [-z wrap=symbol] filename...
The link-editor,
ld, combines relocatable object files by resolving
symbol references to symbol definitions, together with performing relocations.
ld operates in two modes, static or dynamic, as governed by the
-d option. In all cases, the output of
ld is left in the file
a.out by default. See NOTES.
In dynamic mode,
-dy, the default, relocatable object files that are
provided as arguments are combined to produce an executable object file. This
file is linked at execution with any shared object files that are provided as
arguments. If the
-G option is specified, relocatable object files are
combined to produce a shared object. Without the
-G option, a dynamic
executable 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.
Dynamic linking is the most common model for combining relocatable objects, and
the eventual creation of processes within Solaris. 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 technologies 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
archive 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 definitions, or the use of
one of the
-z rescan options. See
Archive Processing 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.
The creation of static executables has been discouraged for many releases. In
fact, 64-bit system archive libraries have never been provided. 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 updates 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 provided. 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.
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.
This
-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. See
The 32-bit link-editor and
64-bit link-editor in
Linker and Libraries Guide.
In static mode only, produces an executable object 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 relocations 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.
|
nodirect
These options govern direct binding.
-B
direct establishes direct binding information by recording the
relationship between each symbol reference together with the dependency that
provides the definition. 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 binding 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
interfaces 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 Appendix D,
Direct Bindings, in
Linker
and Libraries Guide.
|
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 relocatable 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.
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
visible 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 symbolic information defined by any version definitions. Version
definitions 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 definitions 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 references 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 available. This model allows
definitions of the same symbol in an executable or other shared object to
override the object's own definition.
ld issues warnings for undefined
symbols unless
-z defs overrides.
The
-B symbolic option is intended for specialized dynamic objects
and is not recommended for general use. To reduce the runtime relocation
processing that is required an object, the creation of a version definition is
recommended.
Records the configuration file name for use at
runtime. Configuration files can be employed to alter default search paths,
provide a directory cache, together with providing alternative object
dependencies. 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 token,...
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 symbol 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 combined 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 symbol 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 overridden 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
lib x.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 directory 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
lib x.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 environment. See
LD_LIBRARY_PATH under ENVIRONMENT VARIABLES.
Produces a memory map or listing of the input/output
sections, together with any non-fatal multiply-defined symbols, on the
standard 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 processed. See Chapter 9, Mapfile Option, 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
identified as requiring auditing with the -p option, has this
requirement inherited by any object that specifies the shared object as a
dependency. See the -P option. See Runtime Linker Auditing
Interface 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 identification 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 object files 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 Appendix C,
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.
--strip-all
Strips symbolic information from the output file. Any
debugging information, that is, .line, .debug*, and
.stab* sections, and their associated relocation entries are removed.
Except for relocatable files, a symbol table SHT_SYMTAB and its
associated string table section are not created in the output object file. The
elimination of a SHT_SYMTAB symbol table can reduce the .stab*
debugging information that is generated using the compiler drivers -g
option. See the -z redlocsym and -z noldynsym
options.
-S supportlib
The shared object supportlib is loaded with
ld and given information 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 different 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
loading of the first routine. The placement of this option on the command 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 references to external absolute symbols should be resolved immediately
instead of being left for resolution at runtime. In very specialized
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
undefined 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. The creation of very large
32-bit objects can exhaust the virtual memory that is available to the 32-bit
ld. The -z altexec64 option can be used to force the use
of the associated 64-bit ld. The 64-bit ld provides a larger
virtual address space for building 32-bit objects. See The 32-bit
link-editor and 64-bit link-editor in Linker and Libraries
Guide.
-z aslr[=state]
Specify whether the executable's address space should be
randomized on execution. If
state is "enabled" randomization
will always occur when this executable is run (regardless of inherited
settings). If
state is "disabled" randomization will never
occur when this executable is run. If
state is omitted, ASLR is
enabled.
An executable that should simply use the settings inherited from its environment
should not use this flag at all.
|
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 maintained
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 multiple
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 assert-deflib=libname
Enables warnings that check the location of where
libraries passed in with -l are found. If the link-editor finds a
library on its default search path it will emit a warning. This warning can be
made fatal in conjunction with the option -z fatal-warnings. Passing
libname white lists a library from this check. The library must be the
full name of the library, e.g. libc.so. To white list multiple
libraries, the -z assert-deflib=libname option can be
repeated multiple times. This option is useful when trying to build
self-contained objects where a referenced library might exist in the default
system library path and in alternate paths specified by -L, but you
only want the alternate paths to be used.
-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 reasons, 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
reasons, 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
recommended.
|
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 reference and an associated definition within the object being created.
Lazy loading is not enabled.
-z endfiltee
Marks a filtee so that when processed by a filter, the
filtee terminates 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
Controls the behavior of warnings emitted from the
link-editor. Setting -z fatal-warnings promotes warnings emitted
by the link-editor to fatal errors that will cause the link-editor to fail
before linking. -z nofatal-warnings instead demotes these
warnings such that they will not cause the link-editor to exit
prematurely.
-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
Initialization 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 auditing of the
immediate dependencies of the object. The
-z globalaudit
promotes the auditor to a global auditor, thus allowing the auditing 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).
|
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[=
id1,
id2...]
Give messages suggesting link-editor features that could
improve the resulting dynamic object.
Specific classes of suggestion can be silenced by specifying an optional comma
separated list of guidance identifiers.
The current classes of suggestion provided are:
Enable use of direct binding
Suggests that
-z direct or
-B direct be
present prior to any specified dependency. This allows predictable symbol
binding at runtime.
Can be disabled with
-z guidance=nodirect
Enable lazy dependency loading
Suggests that
-z lazyload be present prior to any
specified dependency. This allows the dynamic object to be loaded more
quickly.
Can be disabled with
-z guidance=nolazyload.
Shared objects should define all their dependencies.
Suggests that
-z defs be specified on the
link-editor command line. Shared objects that explicitly state all their
dependencies behave more predictably when used.
Can be be disabled with
-z guidance=nodefs
Version 2 mapfile syntax
Suggests that any specified mapfiles use the more
readable version 2 syntax.
Can be disabled with
-z guidance=nomapfile.
Read-only text segment
Should any runtime relocations within the text segment
exist, suggests that the object be compiled with position independent code
(PIC). Keeping large allocatable sections read-only allows them to be shared
between processes using a given shared object.
Can be disabled with
-z guidance=notext
No unused dependencies
Suggests that any dependency not referenced by the
resulting dynamic object be removed from the link-editor command line.
Can be disabled with
-z guidance=nounused.
--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 conditions are true. The
eliminated section must contribute to an allocatable segment. The eliminated
section must provide no global symbols. No other section from any object that
contributes to the link-edit, must reference an eliminated section.
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
Initialization 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 finalization 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 identified 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 interposition 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 bindings 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
operating 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-editor.
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 ...
The class of link-editor that is invoked is determined from the
ELF class
of the first relocatable file that is seen on the command line. This
determination is carried out
prior to any
-z
ld[
32|
64] processing.
Marks a filter to indicate that filtees must be processed
immediately 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 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 dynamic executables or sharable libraries. 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
symbol 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 provides 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. See the
-s and
-z redlocsym options.
Partially initialized symbols, that are defined within
relocatable object files, 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 runtime. 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 .preinitarray section of
the object being built. If no .preinitarray section is present, a
section is created. The new entry is initialized to point to function.
See Initialization 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 symbols are updated to refer to the corresponding SECT symbol.
This option allows specialized objects to greatly reduce their symbol table
sizes. Eliminated local symbols can reduce the .stab* debugging
information that is generated using the compiler drivers -g option. See
the -s and -z noldynsym options.
-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 relaxreloc 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 multiple times to satisfy their own
interdependencies can be necessary.
-z rescan-now is a positional option, and is processed by the
link-editor immediately when encountered on the command line. All archives
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 command line, and
then initiates a final rescan operation over all archives seen on the command
line. The
-z rescan operation can interact incorrectly with
objects that contain initialization (.init) or finalization (.fini) sections,
preventing the code in those sections from running. For this reason,
-z
rescan is deprecated, and use of
-z rescan-now is
advised.
...
-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 occurs in which no new members are extracted.
Archive rescan groups cannot be nested.
-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 specified, the machine type
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 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. See The 32-bit
link-editor and 64-bit link-editor in Linker and Libraries
Guide.
-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 Position-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 type=exec|kmod|reloc|shared
Specifies the type of object to create.
exec
Dynamic executable
reloc
Relocatable object
shared
Dynamic shared object
kmod
illumos kernel module
This option provides additional warning diagnostics
during a link-edit. Presently, this option conveys suspicious use of
displacement relocations. This option also conveys the restricted use of
static TLS relocations when building shared objects. In 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 function. This wrapper function can call
__real_ symbol in order to reference the actual function being
wrapped.
The following is an example of a wrapper for the
malloc(3C) function:
void *
__wrap_malloc(size_t c)
{
(void) printf("malloc called with %zu\n", c);
return (__real_malloc(c));
}
If you link other code with this file using
-z wrap=malloc to
compile all the objects, then all calls to
malloc will call the
function
__wrap_malloc instead. The call to
__real_malloc will
call 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.
An alternative link-editor path name. ld executes,
and passes control 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 specified 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 suffix. 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.
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 file 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, immediately following the name used to invoke
ld, as in:
ld $LD_OPTIONS ... other-arguments ...
An alternative mechanism for specifying a runpath to the
link-editor. 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, respectively, 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).
libx.so
shared object libraries.
libx.a
archive libraries.
a.out
default output file.
LIBPATH
For 32-bit libraries, the default search path is
/usr/ccs/lib, followed by /lib, and finally /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.
See
attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE |
ATTRIBUTE VALUE |
|
| Interface Stability |
Committed |
as(1),
crle(1),
gprof(1),
ld.so.1(1),
ldd(1),
mcs(1),
pvs(1),
exec(2),
stat(2),
dlopen(3C),
dldump(3C),
elf(3ELF),
ar.h(3HEAD),
a.out(4),
attributes(5)
Linker and Libraries Guide
Default options applied by
ld are maintained for historic reasons. In
today's programming environment, where dynamic objects dominate, alternative
defaults would often make more sense. However, historic defaults must be
maintained to ensure compatibility with existing program development
environments. Historic defaults are called out wherever possible in this
manual. For a description of the current recommended options, see Appendix A,
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 specified 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
SXCE build
43. In older versions, the existing file was
rewritten in place, an approach with the potential to corrupt any running
processes that is using the file. This change has an implication for output
files that have multiple hard links in the file system. Previously, 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.