The ld command combines relocatable object files, performs relocation, and resolves external symbols. ld operates in two modes, static or dynamic, as governed by the -d option. In all cases, the output of ld is left in a.out by default (see NOTES).

In static mode, -dn, relocatable object files given as arguments are combined to produce an executable object file. If the -r option is specified, relocatable object files are combined to produce one relocatable object file.

In dynamic mode, -dy, the default, relocatable object files given as arguments are combined to produce an executable object file that will be linked at execution with any shared object files given as arguments. If the -G option is specified, relocatable object files are combined to produce a shared object.

If any argument is a library, ld by default searches it exactly once at the point it encounters the library in the argument list. The library may be either a relocatable archive (see ar(3HEAD)) or a shared object.

For an archive library, ld loads only those routines that define an unresolved external reference. ld searches the archive library symbol table sequentially with as many passes as are necessary to resolve external references that can be satisfied by library members. 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 may require multiple command-line definitions, or use of the -z rescan option.

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.

No command-line option is required to distinguish 32-bit or 64-bit objects. The link-editor uses the ELF class of the first input relocatable object file it sees on the command line to govern the mode in which it will operate. Intermixing 32-bit and 64-bit objects is not permitted. See also the -64 option and the LD_NOEXEC_64 environment variable.

The following options are supported:

-64

Creates a 64-bit object. By default, the class of the object being generated is determined from the first ELF object processed from the command line. This option is useful when creating an object directly with ld whose input is solely from a mapfile (see the -M option) or an archive library.

-a

In static mode only, produces an executable object file; gives errors for undefined references. This is the default behavior for static mode. -a may not be used with the -r option.

-b

In dynamic mode only, does no special processing for relocations that reference symbols in shared objects. Without the -b option, the link-editor creates special position-independent relocations for references to functions defined in shared objects and arranges for data objects defined in shared objects to be copied into the memory image of an executable by the runtime linker.

The -b option is intended for specialized dynamic objects and is not recommended for general use. Its use suppresses all specialized processing required to insure an object's shareability, and may even prevent the relocation of 64-bit executables.

-B direct

Establishes direct binding information by recording the relationship between each symbol reference and the dependency that provides the definition. The runtime linker uses this information to search directly for the symbol in the associated object rather than to carry out its 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.

-B dynamic | static

Options governing library inclusion. -B dynamic is valid in dynamic mode only. These options may be specified any number of times on the command line as toggles: if the -B static option is given, no shared objects will be accepted until -B dynamic is seen. See also the -l option.

-B eliminate

Causes any global symbols not assigned to a version definition to be eliminated from the symbol table. This option achieves the same symbol elimination as the auto-elimination directive available as part of a mapfile version definition.

-B group

Establishes a shared object and its dependencies as a group. Objects within the group will be bound to other members of the group at runtime. The runtime processing of an object containing this flag mimics that which occurs if the object is added to a process using dlopen(3DL) with the RTLD_GROUP mode. An object that has an explicit dependency on a object identified as a group, will itself become 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 via a mapfile and indicate the global symbols that should remain visible in the generated object. This option achieves the same symbol reduction as the auto-reduction directive available as part of a mapfile version definition and may be useful when combining versioned and non-versioned relocatable objects.

-B reduce

When generating a relocatable object, causes the reduction of symbolic information defined by any version definitions. Version definitions can be supplied via a mapfile to indicate the global symbols that should remain visible in the generated object. When a relocatable object is generated, by default version definitions are only recorded in the output image. The actual reduction of symbolic information will be carried out when the object itself is used in the construction of a dynamic executable or shared object. This option is applied automatically when 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, so that definitions of the same symbol in an executable or other shared object can override the object's own definition. ld will issue 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 overhead of an object, the creation of a version definition is recommended.

-c name

Records the configuration file name for use at runtime. Configuration files may be employed to alter default search paths, provide a directory cache and provide alternative object dependencies. See crle(1).

-C

Demangles C++ symbol names displayed in diagnostic messages.

-d y | n

When -d y, the default, is specified, ld uses dynamic linking; when -d n is specified, ld uses static linking. See also -B dynamic|static.

-D token,...

Prints debugging information, as specified by each token, to the standard error. The special token help indicates the full list of tokens available.

-e epsym

Sets the entry point address for the output file to be that of the symbol epsym.

-f 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 may not be combined with the -F option.

-F 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 may not be combined with the -f option.

-G

In dynamic mode only, produces a shared object. Undefined symbols are allowed.

-h name

In dynamic mode only, when building a shared object, records name in the object's dynamic section. name will be recorded in dynamic objects that are linked with this object rather than the object's file system name. Accordingly, name will be used by the runtime linker as the name of the shared object to search for at runtime.

-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

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 may be overridden by -I name. exec(2) will load this interpreter when it loads a.out and will pass control to the interpreter rather than to a.out directly.

-l 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 file. The directory search stops at the first directory containing either. ld chooses the file ending in .so if -lx expands to two files with names of the form libx.so and libx.a. If no libx.so is found, then ld accepts libx.a. In static mode, or when the -B static option is in effect, ld selects only the file ending in .a. ld searches a library when it encounters its name, so the placement of -l is significant.

-L 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 it precedes the -l options to which it applies on the command line. The environment variable LD_LIBRARY_PATH may be used to supplement the library search path (see LD_LIBRARY_PATH below).

-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 may be specified multiple times. If mapfile is a directory, then all regular files, as defined by stat(2), within the directory will be processed. See Linker and Libraries Guide for a description of mapfiles. There are mapfiles in /usr/lib/ld that show the default layout of programs, mapfiles for linking 64-bit programs above or below 4 gigabytes, and a mapfile for establishing a non-executable stack within an application. See the FILES section below.

-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 will be the string specified on the command line. This option is position dependent, and the DT_NEEDED .dynamic entry will be relative to the other dynamic dependencies discovered on the link-edit line. This option is useful for specifying dependencies within device driver relocatable objects when combined with the -dy and -r options.

-o outfile

Produces an output object file named outfile. The name of the default object file is a.out.

-p auditlib

Identifies an audit library, auditlib, that is used to audit this object at runtime. Any shared object identified as requiring auditing of itself has this requirement inherited by any object specifying this shared object as a dependency (see -P option).

-P auditlib

Identifies an audit library, auditlib, that is used to audit this object's dependencies at runtime. Dependency auditing can also be inherited from dependencies identified as requiring auditing (see -p option).

-Q y | n

Under -Q y, an ident string is added to the .comment section of the output file to identify the version of the link-editor 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 is identical with the default action of the cc command. -Q n suppresses version identification.

-r

Combines relocatable object files to produce one relocatable object file. ld will not complain about unresolved references. This option cannot be used with the -a option.

-R path

A colon-separated list of directories used to specify library search directories to the runtime linker. If present and not NULL, it 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.

-s

Strips symbolic information from the output file. Any debugging information, that is .debug, .line, and .stab sections, and their associated relocation entries will be removed. Except for relocatable files or shared objects, the symbol table and string table sections will also be removed from the output object file.

-S supportlib

The shared object supportlib is loaded with the link-editor and given information regarding the linking process. Support shared objects may also be supplied using the SGS_SUPPORT environment variable. See Linker and Libraries Guide for more details.

-t

Turns off the warning for multiply-defined symbols that have different sizes or alignments.

-u symname

Enters symname as an undefined symbol in the symbol table. This is useful for loading entirely from an archive library, since initially the symbol table is empty, and an unresolved reference is needed to force the loading of the first routine. The placement of this option on the command line is significant; it must be placed before the library that will define the symbol.

-V

Outputs a message giving information about the version of ld being used.

-Y P,dirlist

Changes the default directories used for finding libraries. dirlist is a colon-separated path list.

-z absexec

Useful only when building a dynamic executable. Specifies that references to external absolute symbols should be resolved immediately instead of being left for resolution at runtime. In very specialized circumstances, this option removes text relocations that can result in excessive swap space demands by an executable.

-z allextract | defaultextract | weakextract

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 -z allextract, all archive members are extracted from the archive. Under -z weakextract, weak references trigger archive extraction. -z defaultextract provides a means of returning to the default following use of the former extract options.

-z combreloc

Combines multiple relocation sections. Historically, relocation sections are maintained in a one-to-one relationship with the sections to which the relocations will be applied. When building an executable or shared object, ld sorts the entries of data relocation sections by their symbol reference so as to reduce runtime symbol lookup. Combining multiple data relocation sections allows optimal sorting and hence the least relocation overhead when objects are loaded into memory.

-z defs | nodefs

The -z defs option forces a fatal error if any undefined symbols remain at the end of the link. This is the default when an executable is built, but for historic reasons is not the default when building a shared object. Use of the -z defs option is recommended, as it assures the object being built is self-contained, that is, that all its symbolic references are resolved internally or to the object's immediate dependencies.

The -z nodefs option allows undefined symbols. For historic reasons, this 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 endfiltee

Marks a filtee so that when processed by a filter it terminates any further filtee searches by the filter.

-z finiarray=function

Appends an entry to the .finiarray section of the object being built. If no .finiarray section is present, one is created. The new entry is initialized to point to function. See Linker and Libraries Guide for more details.

-z groupperm | nogroupperm

Assigns, or deassigns each dependency that follows to a unique group. Assigning a dependency to a group has the same effect as if the dependency had been built using the -B group option.

-z ignore | record

Ignores, or records, dynamic dependencies that are not referenced as part of the link-edit. By default, -z record is in effect.

-z initarray=function

Appends an entry to the .initarray section of the object being built. If no .initarray section is present, one is created. The new entry is initialized to point to function. See Linker and Libraries Guide for more details.

-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 will occur 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. When direct bindings are in effect (see -B direct), the runtime linker will search for symbols in any interposers before the object associated to the direct binding.

-z lazyload | nolazyload

Enables or disables the marking of dynamic dependencies to be lazily loaded. Dynamic dependencies which are marked lazyload will not be loaded at initial process start-up, but instead will be delayed until the first binding to the object is made.

-z ld32=arg1,arg2,...

-z ld64=arg1,arg2,...

The class of the link-editor is affected by the class of the output file being created and by the capabilities of the underlying operating system. This option provides a means of defining any link-editor argument, such that it will only be interpreted, respectively, by the 32- or 64-bit class of the link-editor.

For example, support libraries are class specific, so the correct class of support library can be insured using:

ld ... -z ld32=-Saudit32.so.1 -z ld64=-Saudit64.so.1 ...

Note: The class of link-editor invoked is in part determined from the ELF class of the first input relocatable file seen on the command line. This determination is carried out prior to any -z ld[32|64] processing.

-z loadfltr

Marks the object to require that when building a filter, its filtees 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 ld.so.1(1).

-z muldefs

Allows multiple symbol definitions. By default, multiple symbol definitions that occur between relocatable objects will result in a fatal error condition. This option suppresses the error condition and allows the first symbol definition to be taken.

-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. The runtime processing of an object that contains this flag mimics that which occurs if the object is added to a process using dlopen(3DL) with the RTLD_NODELETE mode.

-z nodlopen

Marks the object as not available to dlopen(3DL), either as the object specified by the dlopen(), or as any form of dependency required by the object specified by the dlopen(). This option is only meaningful when building a shared object.

-z nodump

Marks the object as not available to dldump(3DL).

-z nopartial

If there are any partially initialized symbols in the input relocatable object files, the partially initialized symbols are expanded when the output file is generated.

-z noversion

Does not record any versioning sections. Any version sections or associated .dynamic section entries will not be generated in the output image.

-z now

Marks the object to override the runtime linker's default mode and require non-lazy runtime binding. This is similar to adding the object to the process by using dlopen(3DL) with the RTLD_NOW mode, or setting 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, one is created. The new entry is initialized to point to function. See Linker and Libraries Guide for more details.

-z redlocsym

Eliminates all local symbols except for the SECT symbols from the symbol table SHT_SYMTAB. All relocations that refer to local symbols will be updated to refer to the corresponding SECT symbol.

-z rescan

Rescans the archive files provided to the link-edit. By default, archives are processed once as they 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, it is often necessary to specify the archives multiple times to satisfy their own interdependencies.

The -z rescan option causes the entire archive list to be reprocessed in an attempt to locate additional archive members that resolve symbol references. This archive rescanning continues until a pass over the archive list occurs in which no new members are extracted.

-z text

In dynamic mode only, forces a fatal error if any relocations against non-writable, allocatable sections remain. For historic reasons, this is not the default when building an executable or shared object. However, its use is recommended to insure that the text segment of the dynamic object being built is shareable between multiple running processes, and that the object incurs the least relocation overhead when loaded into memory.

-z textoff

In dynamic mode only, allows relocations against all allocatable sections, including non-writable ones. This 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 is the default when building an executable.

-z verbose

This option provides additional warning diagnostics during a link-edit. Presently, its implementation conveys suspicious use of displacement relocations, but in future it may be enhanced to provide additional diagnostics deemed too noisy to be generated by default.

LD_LIBRARY_PATH

A list of directories in which to search for libraries specified with the -l option. Multiple directories are separated by a colon. In the most general case, it will contain 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, it is interpreted as dirlist2.

The LD_LIBRARY_PATH environment variable also affects the runtime linkers searching 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 may be in effect.

LD_NOEXEC_64

Suppresses the automatic execution of the 64-bit link-editor. By default, the link-editor will execute its 64-bit version when the ELF class of the first input relocatable file it reads identifies it as a 64-bit object.

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 -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 may be in effect. See also the -S option.

Notice that environment variable-names beginning with the characters 'LD_' are reserved for possible future enhancements to ld and ld.so.1(1).

libx.so

shared object libraries.

libx.a

archive libraries.

a.out

default output file.

LIBPATH

/usr/lib for 32-bit libraries, or /usr/lib/64 for 64-bit libraries.

/usr/lib/ld/map.bssalign

mapfile providing a template for aligning bss.

/usr/lib/ld/map.default

mapfile showing default layout of 32-bit programs.

/usr/lib/ld/map.noexstk

mapfile showing a non-executable stack definition.

/usr/lib/ld/sparcv9/map.default

mapfile showing default layout of 64-bit SPARCV9 programs.

/usr/lib/ld/sparcv9/map.above4G

mapfile showing suggested layout above 4 gigabytes of 64-bit SPARCV9 programs.

/usr/lib/ld/sparcv9/map.below4G

mapfile showing suggested layout below 4 gigabytes of 64-bit SPARCV9 programs.

See attributes(5) for descriptions of the following attributes:

as(1), crle(1), gprof(1), ld.so.1(1), pvs(1), exec(2), stat(2), dlopen(3DL), dldump(3DL), elf(3ELF), ar(3HEAD), a.out(4), attributes(5)

Linker and Libraries Guide

Default options applied by ld are maintained for historic reasons. In today's programming environment, where dynamic objects dominate, alternative defaults would often make more sense. However, historic defaults must be maintained to insure compatibility with existing program development environments. Historic defaults are called out wherever possible in this manual. For a description of current recommended options, see the Link-Editor Quick Reference in the Linker and Libraries Guide.

If the file being created by ld already exists, it will be truncated after all input files have been processed and overridden with the new file contents. ld does not create a temporary file as part of the link-edit, since multiple instances of large output files frequently exhaust system resources. The drawback of overriding an existing file occurs if the file is in use by a running process. In this case, the process may be prematurely terminated as the output files image is created. This situation can be avoided by removing the output file before performing the link-edit. This removal is not detrimental to the running process, as it frees up the file system namespace, not the actual disk space, for the new output file creation. The disk space of a removed file is freed when the last process referencing the file terminates.