LD(1) User Commands LD(1)

NAME

ld - link-editor for object files

SYNOPSIS

ld [-32 | -64] [-a | -r] [-b] [-B direct | -B nodirect]
[-B dynamic | -B static] [-B eliminate] [-B group] [-B local]
[-B reduce] [-B symbolic] [-c name] [-C] [-d y | -d 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 | -Q n] [-R path]
[-s] [-S supportlib] [-t] [-u symname] [-V] [-Y P,dirlist]
[-z absexec] [-z allextract | -z defaultextract | -z weakextract]
[-z altexec64] [-z aslr[=state]] [-z assert-deflib]
[-z assert-deflib=libname] [-z combreloc | -z nocombreloc]
[-z defs | -z nodefs] [-z direct | -z nodirect] [-z endfiltee]
[-z fatal-warnings | -z nofatal-warnings] [-z finiarray=function]
[-z globalaudit] [-z groupperm | nogroupperm] [-z guidance[=id,...]]
[-z help] [-z ignore | -z record] [-z initarray=function]
[-z initfirst] [-z interpose] [-z lazyload | -z nolazyload]
[-z ld32=arg,...] [-z ld64=arg,...] [-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] [-z rescan-now]
[-z rescan-start ... -z rescan-end] [-z symbolcap]
[-z target=sparc|x86] [-z text | -z textwarn | -z textoff]
[-z type=exec|kmod|reloc|shared] [-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
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, -d y, 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, -d n, 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 illumos. 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.

Static Executables

The creation of static executables is discouraged. Since 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.

On illumos, system archive libraries (such as libc.a) have never been
provided. Without these libraries, the creation of static executables
is not achievable without specialized system knowledge. However, the
capability of ld to process static linking options, and the processing
of archive libraries, remains.

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. See The
32-bit link-editor and 64-bit link-editor in Linker and Libraries
Guide.

Note that for compatibility with existing Makefiles and scripts,
these options may be given multiple times and may be mixed in the
same invocation: the last instance wins, so that, for example,
`ld -64 -32 -64 ...' gives 64-bit output.

-a 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

-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.

-B direct | -B 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.

-B dynamic | -B 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 and
-B reduce options. 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 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 and -B reduce
options. 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. -c name 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 | -d n
When -d y, the default, is specified, ld uses dynamic linking.
When -d n is specified, ld uses static linking. See Static
Executables and -B dynamic | -B 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 cannot 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 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
directory specified in the library search path for a libx.so or
libx.a. The directory search stops at the first directory
containing either. ld chooses the file ending in .so if -l x
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 environment. See LD_LIBRARY_PATH under ENVIRONMENT.

-m 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 -d y 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 and -z globalaudit options. See Runtime Linker Auditing
Interface in Linker and Libraries Guide.

-Q y | -Q 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(1) 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.

-s
--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
driver's -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 | -z defaultextract | -z 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.

-z combreloc | -z 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
-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 | -z 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.

-z direct | -z 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 | -z 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).

-z groupperm | -z 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[=id,...]
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

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

Global data in shared libraries built with mapfiles have size
assertions
Suggests that any global data in a library built with a
mapfile asserts the size of that global data for ABI
stability purposes. Can be disabled with -z
guidance=noasserts

-z help
--help
Print a summary of the command line options on the standard
output and exit.

-z ignore | -z 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.

-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
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 | -z nolazyload
Enables or disables the marking of dynamic dependencies to be
lazily loaded. Dynamic dependencies which are marked Cm 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=arg,...
-z ld64=arg,...
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 ld32 | -z ld64 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
ld32 | -z ld64 processing.

-z loadfltr
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(3C), or as any form of dependency
required by the object specified by the dlopen(3C). 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.

-z nopartial
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
driver's -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-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 occurs in which no new members are extracted. Archive
rescan groups cannot be nested.

-z symbolcap
Specifies that a relocatable object that defines object
capabilities should have those converted to symbol capabilities.
A relocatable object that does not have any object capabilities
will ignore this option.

Symbol capabilities provide a means for multiple implementations
of a function to co-exist and have one picked at runtime based
upon the hardware capabilities of the system. When -z symbolcap
is invoked, all global functions are converted into local
functions that have the corresponding capability name appended to
them and an undefined symbol with the original name left in the
resulting relocatable object. At runtime, the global symbol will
be bound to the corresponding implementation that is appropriate
based on the capabilities of the system.

-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.

Note that for compatibility with existing Makefiles and scripts,
these options may be given multiple times and may be mixed in the
same invocation: the last instance wins, so that, for example,
`ld -z target=sparc -z target=x86 ...' gives a machine type of
`x86'.

-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

-z verbose
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.

-z wrap=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.

ENVIRONMENT

LD_ALTEXEC
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.

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 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 ...

LD_RUN_PATH
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).

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 /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.

ATTRIBUTES

The command line interface of ld is Committed. The output of ld is
Committed.

SEE ALSO

as(1), crle(1), gprof(1), ld.so.1(1), ldd(1), mcs(1), pvs(1), strip(1),
exec(2), stat(2), dladdr(3C), dldump(3C), dlopen(3C), malloc(3C),
elf(3ELF), ar.h(3HEAD), a.out(5), attributes(7)

Linker and Libraries Guide.

NOTES

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.

illumos January 15, 2024 illumos