xref: /illumos-gate/usr/src/man/man1/ld.1 (revision 63f6f57b9c12b68feed7eb52a4d31b7afb0c0906)

.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 2019 Joyent, Inc.
.\" Copyright 2023 Oxide Computer Company
.\" Copyright 2024 OmniOS Community Edition (OmniOSce) Association.
.\"
.Dd January 15, 2024
.Dt LD 1
.Os
.Sh NAME
.Nm ld
.Nd link-editor for object files
.Sh SYNOPSIS
.Nm
.Op Fl 32 | 64
.Op Fl a | r
.Op Fl b
.Op Fl B Cm direct | Fl B Cm nodirect
.Op Fl B Cm dynamic | Fl B Cm static
.Op Fl B Cm eliminate
.Op Fl B Cm group
.Op Fl B Cm local
.Op Fl B Cm reduce
.Op Fl B Cm symbolic
.Op Fl c Ar name
.Op Fl C
.Op Fl d Cm y | Fl d Cm n
.Op Fl D Ar token Ns No ,...
.Op Fl e Ar epsym
.Op Fl f Ar name | Fl F Ar name
.Op Fl G
.Op Fl h Ar name
.Op Fl i
.Op Fl I Ar name
.Op Fl l Ar x
.Op Fl L Ar path
.Op Fl m
.Op Fl M Ar mapfile
.Op Fl N Ar string
.Op Fl o Ar outfile
.Op Fl p Ar auditlib
.Op Fl P Ar auditlib
.Op Fl Q Cm y | Fl Q Cm n
.Op Fl R Ar path
.Op Fl s
.Op Fl S Ar supportlib
.Op Fl t
.Op Fl u Ar symname
.Op Fl V
.Op Fl Y Cm P Ns \&, Ns Ar dirlist
.Op Fl z Cm absexec
.Op Fl z Cm allextract | Fl z Cm defaultextract | Fl z Cm weakextract
.Op Fl z Cm altexec64
.Op Fl z Cm aslr Ns Op Cm \&= Ns Ar state
.Op Fl z Cm assert-deflib
.Op Fl z Cm assert-deflib= Ns Ar libname
.Op Fl z Cm combreloc | Fl z Cm nocombreloc
.Op Fl z Cm defs | Fl z Cm nodefs
.Op Fl z Cm direct | Fl z Cm nodirect
.Op Fl z Cm endfiltee
.Op Fl z Cm fatal-warnings | Fl z Cm nofatal-warnings
.Op Fl z Cm finiarray= Ns Ar function
.Op Fl z Cm globalaudit
.Op Fl z Cm groupperm | nogroupperm
.Op Fl z Cm guidance Ns Op Cm \&= Ns Ar id Ns No \&,...
.Op Fl z Cm help
.Op Fl z Cm ignore | Fl z Cm record
.Op Fl z Cm initarray= Ns Ar function
.Op Fl z Cm initfirst
.Op Fl z Cm interpose
.Op Fl z Cm lazyload | Fl z Cm nolazyload
.Op Fl z Cm ld32= Ns Ar arg Ns No \&,...
.Op Fl z Cm ld64= Ns Ar arg Ns No \&,...
.Op Fl z Cm loadfltr
.Op Fl z Cm muldefs
.Op Fl z Cm nocompstrtab
.Op Fl z Cm nodefaultlib
.Op Fl z Cm nodelete
.Op Fl z Cm nodlopen
.Op Fl z Cm nodump
.Op Fl z Cm noldynsym
.Op Fl z Cm nopartial
.Op Fl z Cm noversion
.Op Fl z Cm now
.Op Fl z Cm origin
.Op Fl z Cm preinitarray= Ns Ar function
.Op Fl z Cm redlocsym
.Op Fl z Cm relaxreloc
.Op Fl z Cm rescan
.Op Fl z Cm rescan-now
.Op Fl z Cm rescan-start \&... Fl z Cm rescan-end
.Op Fl z Cm symbolcap
.Op Fl z Cm target= Ns Cm sparc Ns | Ns Cm x86
.Op Fl z Cm text | Fl z Cm textwarn | Fl z Cm textoff
.Sm off
.Op Fl z\~ Cm type= Cm exec | kmod | reloc | shared
.Sm on
.Op Fl z Cm verbose
.Op Fl z Cm wrap= Ns Ar symbol
.Ar filename Ns No \&...
.Sh DESCRIPTION
The link-editor,
.Nm ,
combines relocatable object files by resolving symbol references to symbol
definitions, together with performing relocations.
.Nm
operates in two modes, static or dynamic, as governed by the
.Fl d
option.
In all cases, the output of
.Nm
is left in the file
.Pa a.out
by default.
See
.Sx NOTES .
.Pp
In dynamic mode,
.Fl d Cm 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
.Fl G
option is specified, relocatable object files are combined to produce a shared
object.
Without the
.Fl G
option, a dynamic executable is created.
.Pp
In static mode,
.Fl d Cm n ,
relocatable object files that are provided as arguments are combined to produce
a static executable file.
If the
.Fl r
option is specified, relocatable object files are combined to produce one
relocatable object file.
See
.Sx Static Executables .
.Pp
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,
.Xr ld.so.1 1 .
Both of these utilities, together with their related technologies and
utilities, are extensively documented in the
.%T Linker and Libraries Guide .
.Pp
If any argument is a library,
.Nm
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
.Xr ar.h 3HEAD .
.Pp
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,
.Em Shared Objects ,
in
.%T Linker and Libraries Guide .
.Pp
For an archive library,
.Nm
loads only those routines that define an unresolved external reference.
.Nm
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
.Fl z Cm rescan
options.
See
.Em Archive Processing
in
.%T Linker and Libraries Guide .
.Pp
.Nm
is a cross link-editor, able to link 32-bit objects or 64-bit objects, for
Sparc or x86 targets.
.Nm
uses the
.Sy 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
.Fl 32 ,
.Fl 64
and
.Fl z Cm target
options, and the
.Ev LD_NOEXEC_64
environment variable.
.Ss 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.
.Bl -bullet -offset 4n
.It
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.
.It
The ability of the executable to run on future releases can be compromised.
.It
The duplication of system implementation details negatively affects system
performance.
.El
.Pp
On illumos, system archive libraries
.Po
such as
.Pa libc.a
.Pc
have never been provided.
Without these libraries, the creation of static executables is not achievable
without specialized system knowledge.
However, the capability of
.Nm
to process static linking options, and the processing of archive libraries,
remains.
.Sh OPTIONS
The following options are supported.
.Pp
.Bl -tag -width 4n -compact
.It Fl 32 | 64
Creates a 32-bit, or 64-bit object.
.Pp
By default, the class of the object being generated is determined from the
first
.Sy 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.
.Pp
The
.Fl 64
option is required to create a 64-bit object solely from a mapfile.
.Pp
The
.Fl 32
or
.Fl 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
.Fl 32
or
.Fl 64
option can be used to direct the link-editor.
See
.Em The 32-bit link-editor and 64-bit link-editor
in
.%T Linker and Libraries Guide .
.Pp
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,
.Ql ld -64 -32 -64 \&...
gives 64-bit output.
.Pp
.It Fl 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
.Fl a
option can not be used with the
.Fl r
option.
See
.Sx Static Executables
.Pp
.It Fl b
In dynamic mode only, provides no special processing for dynamic executable
relocations that reference symbols in shared objects.
Without the
.Fl 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.
.Pp
The
.Fl 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.
.Pp
.It Fl B Cm direct | Fl B Cm nodirect
These options govern direct binding.
.Fl B Cm 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.
.Pp
Direct binding information can only be established to dependencies specified
with the link-edit.
Thus, you should use the
.Fl z Cm defs
option.
Objects that wish to interpose on symbols in a direct binding environment
should identify themselves as interposers with the
.Fl z Cm interpose
option.
The use of
.Fl B Cm direct
enables
.Fl z Cm lazyload
for all dependencies.
.Pp
The
.Fl B Cm 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
.Fl z Cm direct
option.
See Appendix D,
.Em Direct Bindings ,
in
.%T Linker and Libraries Guide .
.Pp
.It Fl B Cm dynamic | Fl B Cm static
Options governing library inclusion.
.Fl B Cm dynamic
is valid in dynamic mode only.
These options can be specified any number of times on the command line as
toggles: if the
.Fl B Cm static
option is given, no shared objects are accepted until
.Fl B Cm dynamic
is seen.
See the
.Fl l
option.
.Pp
.It Fl B Cm 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
.Sy mapfile
to indicate the global symbols that should remain visible in the generated
object.
This option achieves the same symbol elimination as the
.Em 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
.Fl B Cm local
and
.Fl B Cm reduce
options.
See
.Em Defining Additional Symbols with a mapfile
in
.%T Linker and Libraries Guide .
.Pp
.It Fl B Cm 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
.Xr dlopen 3C
with the
.Dv RTLD_GROUP
mode.
An object that has an explicit dependency on a object identified as a group,
becomes a member of the group.
.Pp
As the group must be self contained, use of the
.Fl B Cm group
option also asserts the
.Fl z Cm defs
option.
.Pp
.It Fl B Cm 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
.Sy mapfile
to indicate the global symbols that should remain visible in the generated
object.
This option achieves the same symbol reduction as the
.Ar 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
.Fl B Cm eliminate
and
.Fl B Cm reduce
options.
See
.Em Defining Additional Symbols with a mapfile
in
.%T Linker and Libraries Guide .
.Pp
.It Fl B Cm 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
.Sy 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
.Fl B Cm reduce
option is applied automatically when a dynamic executable or shared object is
created.
.Pp
.It Fl B Cm 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.
.Nm
issues warnings for undefined symbols unless
.Fl z Cm defs
overrides.
.Pp
The
.Fl B Cm 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.
.Fl c Ar name
records the configuration file
.Ar 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
.Xr crle 1 .
.Pp
.It Fl C
Demangles C++ symbol names displayed in diagnostic messages.
.Pp
.It Fl d Cm y | Fl d Cm n
When
.Fl d Cm y ,
the default, is specified,
.Nm
uses dynamic linking.
When
.Fl d Cm n
is specified,
.Nm
uses static linking.
See
.Sx Static Executables
and
.Fl B Cm dynamic | Fl B Cm static .
.Pp
.It Fl D Ar token Ns \&,...
Prints debugging information as specified by each
.Ar token
to the standard error.
The special token
.Cm help
indicates the full list of tokens available.
See
.Em Debugging Aids
in
.%T Linker and Libraries Guide .
.Pp
.It Fl e Ar epsym
.It Fl \&-entry Ar epsym
Sets the entry point address for the output file to be the symbol
.Ar epsym .
.Pp
.It Fl f Ar name
.It Fl \&-auxiliary Ar 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
.Ar name .
Multiple instances of this option are allowed.
This option can not be combined with the
.Fl F
option.
See
.Em Generating Auxiliary Filters
in
.%T Linker and Libraries Guide .
.Pp
.It Fl F Ar name
.It Fl \&-filter Ar 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
.Ar name .
Multiple instances of this option are allowed.
This option cannot be combined with the
.Fl f
option.
See
.Em Generating Standard Filters
in
.%T Linker and Libraries Guide .
.Pp
.It Fl G
.It Fl shared
In dynamic mode only, produces a shared object.
Undefined symbols are allowed.
See Chapter 4,
.Em Shared Objects ,
in
.%T Linker and Libraries Guide .
.Pp
.It Fl h Ar name
.It Fl soname Ar name
In dynamic mode only, when building a shared object, records
.Ar name
in the object's dynamic section.
.Ar name
is recorded in any dynamic objects that are linked with this object rather than
the object's file system name.
Accordingly,
.Ar name
is used by the runtime linker as the name of the shared object to search for at
runtime.
See
.Em Recording a Shared Object Name
in
.%T Linker and Libraries Guide .
.Pp
.It Fl i
Ignores
.Ev LD_LIBRARY_PATH .
This option is useful when an
.Ev LD_LIBRARY_PATH
setting is in effect to influence the runtime library search, which would
interfere with the link-editing being performed.
.Pp
.It Fl I Ar name
.It Fl \&-dynamic-linker Ar name
When building an executable, uses
.Ar 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,
.Xr ld.so.1 1 .
Either case can be overridden by
.Fl I Ar name .
.Xr exec 2
loads this interpreter when the
.Pa a.out
is loaded, and passes control to the interpreter rather than to the
.Pa a.out
directly.
.Pp
.It Fl l Ar x
.It Fl \&-library Ar x
Searches a library
.Sy lib Ns Ar x Ns Sy .so
or
.Sy lib Ns Ar x Ns Sy .a ,
the conventional names for shared object and archive libraries, respectively.
In dynamic mode, unless the
.Fl B Cm static
option is in effect,
.Nm
searches each directory specified in the library search path for a
.Sy lib Ns Ar x Ns Sy .so
or
.Sy lib Ns Ar x Ns Sy \&.a .
The directory search stops at the first directory containing either.
.Nm
chooses the file ending in
.Sy .so
if
.Fl l Ar x
expands to two files with names of the form
.Sy lib Ns Ar x Ns Sy .so
and
.Sy lib Ns Ar x Ns Sy .a .
If no
.Sy lib Ns Ar x Ns Sy .so
is found, then
.Nm
accepts
.Sy lib Ns Ar x Ns Sy .a .
In static mode, or when the
.Fl B Cm static
option is in effect,
.Nm
selects only the file ending in
.Sy .a .
.Nm
searches a library when the library is encountered, so the placement of
.Fl l
is significant.
See
.Em Linking With Additional Libraries
in
.%T Linker and Libraries Guide .
.Pp
.It Fl L Ar path
.It Fl \&-library-path Ar path
Adds
.Ar path
to the library search directories.
.Nm
searches for libraries first in any directories specified by the
.Fl L
options and then in the standard directories.
This option is useful only if the option precedes the
.Fl l
options to which the
.Fl L
option applies.
See
.Em Directories Searched by the Link-Editor
in
.%T Linker and Libraries Guide .
.Pp
The environment variable
.Ev LD_LIBRARY_PATH
can be used to supplement the library search path, however the
.Fl L
option is recommended, as the environment variable is also interpreted by the
runtime environment.
See
.Ev LD_LIBRARY_PATH
under
.Sx ENVIRONMENT .
.Pp
.It Fl m
Produces a memory map or listing of the input/output sections, together with
any non-fatal multiply-defined symbols, on the standard output.
.Pp
.It Fl M Ar mapfile
Reads
.Ar mapfile
as a text file of directives to
.Nm .
This option can be specified multiple times.
If
.Ar mapfile
is a directory, then all regular files, as defined by
.Xr stat 2 ,
within the directory are processed.
See Chapter 9,
.Em Mapfile Option ,
in
.%T Linker and Libraries Guide .
Example mapfiles are provided in
.Pa /usr/lib/ld .
See
.Sx FILES .
.Pp
.It Fl N Ar string
This option causes a
.Dv DT_NEEDED
entry to be added to the
.Sy .dynamic
section of the object being built.
The value of the
.Dv DT_NEEDED
string is the
.Ar string
that is specified on the command line.
This option is position dependent, and the
.Dv DT_NEEDED
.Sy .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
.Fl d Cm y
and
.Fl r
options.
.Pp
.It Fl o Ar outfile
.It Fl \&-output Ar outfile
Produces an output object file that is named
.Ar outfile .
The name of the default object file is
.Pa a.out .
.Pp
.It Fl p Ar auditlib
Identifies an audit library,
.Ar auditlib .
This audit library is used to audit the object being created at runtime.
A shared object identified as requiring auditing with the
.Fl p
option, has this requirement inherited by any object that specifies the shared
object as a dependency.
See the
.Fl P
option.
See
.Em Runtime Linker Auditing Interface
in
.%T Linker and Libraries Guide .
.Pp
.It Fl P Ar auditlib
Identifies an audit library,
.Ar 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
.Fl p
and
.Fl z Cm globalaudit
options.
See
.Em Runtime Linker Auditing Interface
in
.%T Linker and Libraries Guide .
.Pp
.It Fl Q Cm y | Fl Q Cm n
Under
.Fl Q Cm y ,
an
.Sy ident
string is added to the
.Sy .comment
section of the output file.
This string identifies the version of the
.Nm
used to create the file.
This results in multiple
.Nm
idents when there have been multiple linking steps, such as when using
.Nm Fl r .
This identification is identical with the default action of the
.Xr cc 1
command.
.Fl Q Cm n
suppresses version identification.
.Sy .comment
sections can be manipulated by the
.Xr mcs 1
utility.
.Pp
.It Fl r
.It Fl \&-relocatable
Combines relocatable object files to produce one relocatable object file.
.Nm
does not complain about unresolved references.
This option cannot be used with the
.Fl a
option.
.Pp
.It Fl R Ar path
.It Fl rpath Ar 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
.Ar path
separated by a colon.
See
.Em Directories Searched by the Runtime Linker
in
.%T Linker and Libraries Guide .
.Pp
The use of a runpath within an associated object is preferable to setting
global search paths such as through the
.Ev LD_LIBRARY_PATH
environment variable.
Only the runpaths that are necessary to find the objects dependencies should be
recorded.
.Xr ldd 1
can also be used to discover unused runpaths in dynamic objects, when used with
the
.Fl U
option.
.Pp
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,
.Em Establishing Dependencies with Dynamic String Tokens ,
in
.%T Linker and Libraries Guide .
The
.Sy $ORIGIN
token is especially useful in allowing dynamic objects to be relocated to
different locations in the file system.
.Pp
.It Fl s
.It Fl \&-strip-all
Strips symbolic information from the output file.
Any debugging information,
that is,
.Sy .line ,
.Sy .debug* ,
and
.Sy .stab*
sections, and their associated relocation entries are removed.
Except for relocatable files, a symbol table
.Dv SHT_SYMTAB
and its associated string table section are not created in the output object
file.
The elimination of a
.Dv SHT_SYMTAB
symbol table can reduce the .stab* debugging information that is generated
using the compiler driver's
.Fl g
option.
See the
.Fl z Cm redlocsym
and
.Fl z Cm noldynsym
options.
.Pp
.It Fl S Ar supportlib
The shared object
.Ar supportlib
is loaded with
.Nm
and given information regarding the linking process.
Shared objects that are defined by using the
.Fl S
option can also be supplied using the
.Ev SGS_SUPPORT
environment variable.
See
.Em Link-Editor Support Interface
in
.%T Linker and Libraries Guide .
.Pp
.It Fl t
Turns off the warning for multiply-defined symbols that have different sizes or
different alignments.
.Pp
.It Fl u Ar symname
.It Fl \&-undefined Ar symname
Enters
.Ar 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
.Em Defining Additional Symbols with the u option
in
.%T Linker and Libraries Guide .
.Pp
.It Fl V
.It Fl \&-version
Outputs a message giving information about the version of
.Nm
being used.
.Pp
.It Fl Y Cm P\&, Ns Ar dirlist
Changes the default directories used for finding libraries.
.Ar dirlist
is a colon-separated path list.
.Pp
.It Fl z Cm 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.
.Pp
.It Fl z Cm allextract | Fl z Cm defaultextract | Fl z Cm weakextract
.It Fl \&-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
.Fl z Cm allextract
or
.Fl \&-whole-archive
options, all archive members are extracted from the archive.
Under
.Fl z Cm weakextract ,
weak references trigger archive extraction.
The
.Fl z Cm defaultextract
or
.Fl \&-no-whole-archive
options provide a means of returning to the default following use of the former
extract options.
See
.Em Archive Processing
in
.%T Linker and Libraries Guide .
.Pp
.It Fl z Cm altexec64
Execute the 64-bit
.Nm .
The creation of very large 32-bit objects can exhaust the virtual memory that
is available to the 32-bit
.Nm .
The
.Fl z Cm altexec64
option can be used to force the use of the associated 64-bit
.Nm .
The 64-bit
.Nm
provides a larger virtual address space for building 32-bit objects.
See
.Em The 32-bit link-editor and 64-bit link-editor
in
.%T Linker and Libraries Guide .
.Pp
.It Fl z Cm aslr Ns Op Cm \&= Ns Ar state
Specify whether the executable's address space should be randomized on
execution.
If
.Ar state
is
.Cm enabled ,
randomization will always occur when this executable is run
.Pq regardless of inherited settings .
If
.Ar state
is
.Cm disabled ,
randomization will never occur when this executable is run.
If
.Ar 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.
.Pp
.It Fl z Cm combreloc | Fl z Cm nocombreloc
By default,
.Nm
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
.Fl z Cm nocombreloc
option disables this merging of relocation sections, and preserves the
one-to-one relationship found in the original relocatable objects.
.Pp
.Nm
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.
.Pp
Historically, the individual relocation sections were carried over to any
executable or shared object, and the
.Fl z Cm combreloc
option was required to enable the relocation section merging previously
described.
Relocation section merging is now the default.
The
.Fl z Cm combreloc
option is still accepted for the benefit of old build environments, but the
option is unnecessary, and has no effect.
.Pp
.It Fl z Cm assert-deflib
.It Fl z Cm assert-deflib= Ns Ar libname
Enables warnings that check the location of where libraries passed in with
.Fl 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
.Fl z Cm fatal-warnings .
Passing
.Ar libname
white lists a library from this check.
The library must be the full name of the library, e.g.
.Pa libc.so .
To white list multiple libraries, the
.Fl z Cm assert-deflib= Ns Ar 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
.Fl L ,
but you only want the alternate paths to be used.
.Pp
.It Fl z Cm defs | Fl z Cm nodefs
.It Fl \&-no-undefined
The
.Fl z Cm defs
option and the
.Fl \&-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
.Em not
the default when building a shared object.
Use of the
.Fl z Cm 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.
.Pp
The
.Fl z Cm 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
.Fl z Cm nodefs
option is not recommended.
.Pp
.It Fl z Cm direct | Fl z Cm 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
.Fl B Cm direct .
The
.Fl z Cm direct
option also differs from the
.Fl B Cm 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.
.Pp
.It Fl z Cm endfiltee
Marks a filtee so that when processed by a filter, the filtee terminates any
further filtee searches by the filter.
See
.Em Reducing Filtee Searches
in
.%T Linker and Libraries Guide .
.Pp
.It Fl z Cm fatal-warnings | Fl z Cm nofatal-warnings
.It Fl \&-fatal-warnings | \&-no-fatal-warnings
Controls the behavior of warnings emitted from the link-editor.
Setting
.Fl z Cm fatal-warnings
promotes warnings emitted by the link-editor to fatal errors that will cause
the link-editor to fail before linking.
.Fl z Cm nofatal-warnings
instead demotes these warnings such that they will not cause the link-editor to
exit prematurely.
.Pp
.It Fl z Cm finiarray= Ns Ar function
Appends an entry to the
.Sy .fini_array
section of the object being built.
If no
.Sy .fini_array
section is present, a section is created.
The new entry is initialized to point to
.Ar function .
See
.Em Initialization and Termination Sections
in
.%T Linker and Libraries Guide .
.Pp
.It Fl z Cm globalaudit
This option supplements an audit library definition that has been recorded with
the
.Fl P
option.
This option is only meaningful when building a dynamic executable.
Audit libraries that are defined within an object with the
.Fl P
option typically allow for the auditing of the immediate dependencies of the
object.
The
.Fl z Cm globalaudit
promotes the auditor to a global auditor, thus allowing the auditing of all
dependencies.
See
.Em Invoking the Auditing Interface
in
.%T Linker and Libraries Guide .
.Pp
An auditor established with the
.Fl P
option and the
.Fl z Cm globalaudit
option, is equivalent to the auditor being established with the
.Ev LD_AUDIT
environment variable.
See
.Xr ld.so.1 1 .
.Pp
.It Fl z Cm groupperm | Fl z Cm 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
.Fl B Cm group
option.
.Pp
.It Fl z Cm guidance Ns Op Cm \&= Ns Ar id Ns No ,...
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:
.Bl -tag -width 4n
.It Enable use of direct binding
Suggests that
.Fl z Cm direct
or
.Fl B Cm direct
be present prior to any specified dependency.
This allows predictable symbol binding at runtime.
Can be disabled with
.Fl z Cm guidance=nodirect
.It Enable lazy dependency loading
Suggests that
.Fl z Cm lazyload
be present prior to any specified dependency.
This allows the dynamic object to be loaded more quickly.
Can be disabled with
.Fl z Cm guidance=nolazyload
.It Shared objects should define all their dependencies.
Suggests that
.Fl z Cm 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
.Fl z Cm guidance=nodefs
.It Version 2 mapfile syntax
Suggests that any specified mapfiles use the more readable version 2 syntax.
Can be disabled with
.Fl z Cm guidance=nomapfile
.It Read-only text segment
Should any runtime relocations within the text segment exist, suggests that
the object be compiled with position independent code
.Pq PIC .
Keeping large allocatable sections read-only allows them to be shared between
processes using a given shared object.
Can be disabled with
.Fl z Cm guidance=notext
.It 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
.Fl z Cm guidance=nounused
.It 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
.Fl z Cm guidance=noasserts
.El
.Pp
.It Fl z Cm help
.It Fl \&-help
Print a summary of the command line options on the standard output and exit.
.Pp
.It Fl z Cm ignore | Fl z Cm record
Ignores, or records, dynamic dependencies that are not referenced as part of
the link-edit.
Ignores, or records, unreferenced
.Sy ELF
sections from the relocatable objects
that are read as part of the link-edit.
By default,
.Fl z Cm record
is in effect.
.Pp
If an
.Sy 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.
.Pp
.It Fl z Cm initarray= Ns Ar function
Appends an entry to the
.Sy .init_array
section of the object being built.
If no
.Sy .init_array
section is present, a section is created.
The new entry is initialized to point to
.Ar function .
See
.Em Initialization and Termination Sections
in
.%T Linker and Libraries Guide .
.Pp
.It Fl z Cm 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.
.Pp
.It Fl z Cm 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
.Fl z Cm interpose
option.
An explicit interposer is also established when an object is loaded using the
.Ev 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.
.Pp
.It Fl z Cm lazyload | Fl z Cm 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
.Em Lazy Loading of Dynamic Dependencies
in
.%T Linker and Libraries Guide .
.Pp
.It Fl z Cm ld32= Ns Ar arg Ns No ,...
.It Fl z Cm ld64= Ns Ar arg Ns No ,...
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
.Fl z Cm ld32 | Fl z Cm 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.
.Pp
For example, support libraries are class specific, so the correct class of
support library can be ensured using:
.Pp
.Dl ld ... -z ld32=-Saudit32.so.1 -z ld64=-Saudit64.so.1 ...
.Pp
The class of link-editor that is invoked is determined from the
.Sy ELF
class of the first relocatable file that is seen on the command line.
This determination is carried out
.Em prior
to any
.Fl z Cm ld32 | Fl z Cm ld64
processing.
.Pp
.It Fl z Cm 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
.Ev LD_LOADFLTR
environment variable is in effect.
See the
.Xr ld.so.1 1 .
.Pp
.It Fl z Cm muldefs
.It Fl \&-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.
.Pp
.It Fl z Cm nocompstrtab
Disables the compression of
.Sy ELF
string tables.
By default, string compression is applied to
.Dv SHT_STRTAB
sections, and to
.Dv SHT_PROGBITS
sections that have their
.Dv SHF_MERGE
and
.Dv SHF_STRINGS
section flags set.
.Pp
.It Fl z Cm nodefaultlib
Marks the object so that the runtime default library search path, used after
any
.Ev LD_LIBRARY_PATH
or runpaths, is ignored.
This option implies that all dependencies of the object can be satisfied from
its runpath.
.Pp
.It Fl z Cm nodelete
Marks the object as non-deletable at runtime.
This mode is similar to adding the object to the process by using
.Xr dlopen 3C
with the
.Dv RTLD_NODELETE
mode.
.Pp
.It Fl z Cm nodlopen
Marks the object as not available to
.Xr dlopen 3C ,
either as the object specified by the
.Xr dlopen 3C ,
or as any form of dependency required by the object specified by the
.Xr dlopen 3C .
This option is only meaningful when building a shared object.
.Pp
.It Fl z Cm nodump
Marks the object as not available to
.Xr dldump 3C .
.Pp
.It Fl z Cm noldynsym
Prevents the inclusion of a
.Sy .SUNW_ldynsym
section in dynamic executables or sharable libraries.
The
.Sy .SUNW_ldynsym
section augments the
.Sy .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,
.Xr dladdr 3C
is able to supply more accurate results.
.Pp
The
.Fl z Cm noldynsym
option also prevents the inclusion of the two symbol sort sections that are
related to the
.Sy .SUNW_ldynsym
section.
The
.Sy .SUNW_dynsymsort
section provides sorted access to regular function and variable symbols.
The
.Sy .SUNW_dyntlssort
section provides sorted access to thread local storage
.Pq TLS
variable symbols.
.Pp
The
.Sy .SUNW_ldynsym ,
.Sy .SUNW_dynsymsort ,
and
.Sy .SUNW_dyntlssort
sections, which becomes part of the allocable text segment of the resulting
file, cannot be removed by
.Xr strip 1 .
Therefore, the
.Fl z Cm noldynsym
option is the only way to prevent their inclusion.
See the
.Fl s
and
.Fl z Cm redlocsym
options.
.Pp
.It Fl z Cm nopartial
Partially initialized symbols, that are defined within relocatable object
files, are expanded in the output file being generated.
.Pp
.It Fl z Cm noversion
Does not record any versioning sections.
Any version sections or associated
.Sy .dynamic
section entries are not generated in the output image.
.Pp
.It Fl z Cm now
Marks the object as requiring non-lazy runtime binding.
This mode is similar to adding the object to the process by using
.Xr dlopen 3C
with the
.Dv RTLD_NOW
mode.
This mode is also similar to having the
.Ev LD_BIND_NOW
environment variable in effect.
See
.Xr ld.so.1 1 .
.Pp
.It Fl z Cm origin
Marks the object as requiring immediate
.Sy $ORIGIN
processing at runtime.
This option is only maintained for historic compatibility, as the runtime
analysis of objects to provide for
.Sy $ORIGIN
processing is now default.
.Pp
.It Fl z Cm preinitarray= Ns Ar function
Appends an entry to the
.Sy .preinitarray
section of the object being built.
If no
.Sy .preinitarray
section is present, a section is created.
The new entry is initialized to point to
.Ar function .
See
.Em Initialization and Termination Sections
in
.%T Linker and Libraries Guide .
.Pp
.It Fl z Cm redlocsym
Eliminates all local symbols except for the
.Sy SECT
symbols from the symbol
table
.Dv SHT_SYMTAB .
All relocations that refer to local symbols are updated to refer to the
corresponding
.Sy SECT
symbol.
This option allows specialized objects to greatly reduce their symbol table
sizes.
Eliminated local symbols can reduce the
.Sy .stab
debugging information that is generated using the compiler driver's
.Fl g
option.
See the
.Fl s
and
.Fl z Cm noldynsym
options.
.Pp
.It Fl z Cm relaxreloc
.Nm
normally issues a fatal error upon encountering a relocation using a
symbol that references an eliminated COMDAT section.
If
.Fl z Cm relaxreloc
is enabled,
.Nm
instead redirects such relocations to the equivalent symbol in the COMDAT
section that was kept.
.Fl z Cm relaxreloc
is a specialized option, mainly of interest to compiler authors, and is not
intended for general use.
.Pp
.It Fl z Cm rescan-now
.It Fl z Cm 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.
.Pp
.Fl z Cm 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.
.Pp
.Fl z Cm 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
.Fl z Cm rescan
operation can interact incorrectly with objects that contain initialization
.Pq .init
or finalization
.Pq .fini
sections, preventing the code in those sections from running.
For this reason,
.Fl z Cm rescan
is deprecated, and use of
.Fl z Cm rescan-now
is
advised.
.Pp
.It Fl z Cm rescan-start No \&... Fl z Cm rescan-end
.It Fl \&-start-group No \&... Fl \&-end-group
.It Fl \&( No \&... Fl \&)
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.
.Pp
.It Fl z Cm 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.
.Pp
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
.Fl z Cm 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.
.Pp
.It Fl z Cm target= Ns Cm sparc Ns | Ns Cm x86
Specifies the machine type for the output object.
Supported targets are
.Cm sparc
and
.Cm x86 .
The 32-bit machine type for the specified target is used unless the
.Fl 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
.Sy 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
.Nm
whose input is solely from a
.Sy mapfile .
See the
.Fl 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
.Em The 32-bit link-editor and 64-bit link-editor
in
.%T Linker and Libraries Guide .
.Pp
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,
.Ql ld -z target=sparc -z target=x86 \&...
gives a machine type of
.Sq x86 .
.Pp
.It Fl z Cm 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
.Em Position-Independent Code
in
.%T Linker and Libraries Guide .
.Pp
.It Fl z Cm 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.
.Pp
.It Fl z Cm 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.
.Pp
.It Xo
.Sm off
.Fl z\~ Cm type= Cm exec | kmod | reloc | shared
.Sm on
.Xc
Specifies the type of object to create.
.Bl -tag -width shared
.It exec
Dynamic executable
.It reloc
Relocatable object
.It shared
Dynamic shared object
.It kmod
illumos kernel module
.El
.Pp
.It Fl z Cm 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.
.Pp
.It Fl z Cm wrap= Ns Ar symbol
.It Fl wrap Ns Cm \&= Ns Ar symbol
.It Fl \&-wrap Ns Cm \&= Ns Ar symbol
Rename undefined references to
.Ar symbol
in order to allow wrapper code to be linked into the output object without
having to modify source code.
When
.Fl z Cm wrap
is specified, all undefined references to
.Ar symbol
are modified to reference
.Sy __wrap_ Ns Ar symbol ,
and all references to
.Sy __real_ Ns Ar symbol
are modified to reference
.Ar symbol .
The user is expected to provide an object containing the
.Sy __wrap_ Ns Ar symbol
function.
This wrapper function can call
.Sy __real_ Ns Ar symbol
in order to reference the actual function being wrapped.
.Pp
The following is an example of a wrapper for the
.Xr malloc 3C
function:
.Bd -literal -offset 4n
void *
__wrap_malloc(size_t c)
{
    (void) printf("malloc called with %zu\en", c);
    return (__real_malloc(c));
}
.Ed
.Pp
If you link other code with this file using
.Fl z Cm wrap= Ns Ar malloc
to compile all the objects, then all calls to
.Sy malloc
will call the function
.Sy __wrap_malloc
instead.
The call to
.Sy __real_malloc
will call the real
.Sy malloc
function.
.Pp
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.
.El
.Sh ENVIRONMENT
.Bl -tag -width 4n
.It Ev LD_ALTEXEC
An alternative link-editor path name.
.Nm
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
.Fl z Cm altexec64
option.
.It Ev LD_LIBRARY_PATH
A list of directories in which to search for the libraries specified using the
.Fl 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:
.Pp
.D1 Ar dirlist1 Ns Cm \&; Ns Ar dirlist2
.Pp
If
.Nm
is called with any number of occurrences of
.Fl L ,
as in:
.Pp
.D1 Nm No ... Fl L Ns Ar path1 No ... Fl L Ns Ar pathn No ...
.Pp
then the search path ordering is:
.Pp
.D1 Ar dirlist1 Ar path1 No ... Ar pathn Ar dirlist2 Ev LIBPATH
.Pp
When the list of directories does not contain a semicolon, the list is
interpreted as
.Ar dirlist2 .
.Pp
The
.Ev LD_LIBRARY_PATH
environment variable also affects the runtime linkers search for dynamic
dependencies.
.Pp
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.
.It Ev 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
.Sy 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.
.It Ev LD_OPTIONS
A default set of options to
.Nm .
.Ev LD_OPTIONS
is interpreted by
.Nm
just as though its value had been placed on the command line, immediately
following the name used to invoke
.Nm ,
as in:
.Pp
.D1 Nm Ev $LD_OPTIONS No ... Ar other-arguments No ...
.It Ev LD_RUN_PATH
An alternative mechanism for specifying a runpath to the link-editor.
See the
.Fl R
option.
If both
.Ev LD_RUN_PATH
and the
.Fl R
option are specified,
.Fl R
supersedes.
.It Ev 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
.Nm
and overrides any non-suffixed version of the environment variable that is in
effect.
See the
.Fl S
option.
.El
.Pp
Notice that environment variable-names that begin with the characters
.Sq LD_
are reserved for possible future enhancements to
.Nm
and
.Xr ld.so.1 1 .
.Sh FILES
.Bl -tag -width 4n
.It lib Ns Ar x Ns No .so
shared object libraries.
.It lib Ns Ar x Ns No .a
archive libraries.
.It Pa a.out
default output file.
.It Ev LIBPATH
For 32-bit libraries, the default search path is
.Pa /usr/ccs/lib ,
followed by
.Pa /lib ,
and finally
.Pa /usr/lib .
For 64-bit libraries, the default search path is
.Pa /lib/64 ,
followed by
.Pa /usr/lib/64 .
.It Pa /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.
.El
.Sh ATTRIBUTES
The command line interface of
.Nm
is
.Sy Committed .
The output of
.Nm
is
.Sy Committed .
.Sh SEE ALSO
.Xr as 1 ,
.Xr crle 1 ,
.Xr gprof 1 ,
.Xr ld.so.1 1 ,
.Xr ldd 1 ,
.Xr mcs 1 ,
.Xr pvs 1 ,
.Xr strip 1 ,
.Xr exec 2 ,
.Xr stat 2 ,
.Xr dladdr 3C ,
.Xr dldump 3C ,
.Xr dlopen 3C ,
.Xr malloc 3C ,
.Xr elf 3ELF ,
.Xr ar.h 3HEAD ,
.Xr a.out 5 ,
.Xr attributes 7
.Rs
.%B Linker and Libraries Guide
.Re
.Sh NOTES
Default options applied by
.Nm
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,
.Em Link-Editor Quick Reference ,
in
.%T Linker and Libraries Guide .
.Pp
If the file being created by
.Nm
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
.Nm
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.
.Pp
The behavior of
.Nm
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
.Nm
behavior
.Em 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.