ld(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT VARIABLES | SUMMARY OF TRUSTED SOLARIS CHANGES | FILES | ATTRIBUTES | SEE ALSO

NAME

ld- link-editor for object files

SYNOPSIS

/usr/ccs/bin/ld [-64] [-a| -r] [-b] [-c name] [-G] [-i] [-m] [-s] [-t] [-V] [-B direct] [-B dynamic| static] [-B group] [-B local] [-B eliminate] [-B reduce] [-B symbolic] [-d y| n] [-D token] [-e epsym] [-F name| -f name] [-h name] [-I name] [-L path] [-l x] [-M mapfile] [-N string] [-o outfile] [-p auditlib] [-P auditlib] [-Q y| n] [-R path] [-S supportlib] [-u symname] [-Y P,dirlist] [-z allextract | defaultextract | weakextract ] [-z combreloc] [-z defs| nodefs] [-z endfiltee] [-z ignore| record] [-z lazyload| nolazyload] [-z initfirst] [-z interpose] [-z loadfltr] [-z muldefs] [-z nodelete] [-z nodefaultlib] [-z nodlopen] [-z nodump] [-z nopartial] [-z noversion] [-z now] [-z origin] [-z redlocsym] [-z text| textwarn| textoff] filename...

DESCRIPTION

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 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. In all cases, the output of ld is left in a.out by default.

If any argument is a library, ld searches exactly once at the point it encounters the library in the argument list. The library may be either a relocatable archive 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. See ar(3HEAD). Thus, the order of members in the library is functionally unimportant, unless multiple library members exist that define the same external symbol.

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.

There is no specific option that tells ld to link 64-bit objects; the class of the first object that gets processed by ld determines whether it is to perform a 32-bit or a 64-bit link edit.

OPTIONS

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

-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, when creating an executable, does not do 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 the executable by the runtime linker.

The -b option is intended for specialized applications and is not recommended for general use. Its use suppresses all specialized processing required to insure an application's shareability, and may even prevent the relocation of 64-bit applications. An application's shareability can always be guaranteed by building it with the use of position-independent code.

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

-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,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 executables that are linked with this object rather than the object's UNIX System file 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 as well as mapfiles for linking 64-bit programs above or below 4 gigabytes. 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.

-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 in dynamic mode or with -a.

-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 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. Reduces overhead when objects are loaded into memory.

-z defs

Forces a fatal error if any undefined symbols remain at the end of the link. This is the default when an executable is built. It is also useful when building a shared object to assure that the object is self-contained, that is, that all its symbolic references are resolved internally.

-z endfiltee

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

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

Allows undefined symbols. This is the default when a shared object is built. When used with executables, the behavior of references to such undefined symbols is unspecified.

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

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

In dynamic mode only, forces a fatal error if any relocations against non-writable, allocatable sections remain.

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

ENVIRONMENT VARIABLES

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.

Note: When running a privileged program, set-user-ID or set-group-ID program, the runtime linker will only search for libraries in any full pathname specified within the executable as a result of a runpath being specified when the executable was constructed, or in a trusted directory (see crle(1)).

LD_LIBRARY_PATH_64

Similar to the LD_LIBRARY_PATH environment variable. Overrides LD_LIBRARY_PATH when searching for 64-bit dependencies.

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

SUMMARY OF TRUSTED SOLARIS CHANGES

For a privileged program, all runtime dependencies must resolve to trusted directories (see crle(1)).

FILES

libx.so

libraries

libx.a

libraries

a.out

output file

LIBPATH

usually /usr/lib or /usr/lib/sparcv9 for 64-bit SPARCV9 libraries.

/usr/lib/ld/map.default

mapfile showing default layout of 32-bit programs

/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

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtoo

SEE ALSO

Trusted Solaris 8 4/01 Reference Manual

crle(1), exec(2), stat(2)

SunOS 5.8 Reference Manual

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

Linker and Libraries Guide, Binary Compatibility Guide

Trusted Solaris 8 4/01  Last Revised 1 Feb 2001

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT VARIABLES | SUMMARY OF TRUSTED SOLARIS CHANGES | FILES | ATTRIBUTES | SEE ALSO