ld(1)

NAME

ld − link editor for object files

SYNOPSIS

ld [ −a|−r ] [ −b ] [ −G ] [ −i ] [ −m ] [ −s ] [ −t ] [ −V ] [ −B [ dynamic|static ] ]

[ −B symbolic ] [ −d [ y|n ] ] [ −D token ] [ −e epsym ] [ −F name ] [ −h name ]

[ −I name ] [ −L path ] [ −l x ] [ −M mapfile ] [ −o outfile ] [ −Q [ y|n ] ]

[ −R path ] [ −u symname ] [ −Y P,dirlist ] [ −z [ defs|nodefs ] ] [ −z text ]

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, it is searched exactly once at the point it is encountered in the argument list. The library may be either a relocatable archive or a shared object. For an archive library, only those routines defining an unresolved external reference are loaded. The archive library symbol table (see ar(4)) is searched sequentially with as many passes as are necessary to resolve external references that can be satisfied by library members. Thus, the ordering of members in the library is functionally unimportant, unless there exist multiple library members defining the same external symbol. A shared object consists of a single entity all of whose references must be resolved within the executable being built or within other shared objects with which it is linked.

OPTIONS

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

−r Combine 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.

−b In dynamic mode only, when creating an executable, do 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 dynamic linker at run time. With the −b option, the output code may be more efficient, but it will be less sharable.

−G In dynamic mode only, produce a shared object. Undefined symbols are allowed.

−i Ignore LD_LIBRARY_PATH setting. This option is useful when an LD_LIBRARY_PATH setting is in effect to influence the run time library search, which would interfere with the link editing being performed.

−m Produce a memory map or listing of the input/output sections, together with any non-fatal multiply defined symbols, on the standard output.

−s Strip 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. −t Turn off the warning about multiply defined symbols that are not the same size. −V Output a message giving information about the version of ld being used.

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

−B symbolic
In dynamic mode only, when building a shared object, bind references to global symbols to their definitions within the object, if definitions are available. Normally, references to global symbols within shared objects are not bound until run time, even if definitions are available, so that definitions of the same symbol in an executable or other shared objects can override the object’s own definition. ld will issue warnings for undefined symbols unless −z defs overrides.

−d [y|n] When −dy, the default, is specified, ld uses dynamic linking; when −dn is specified, ld uses static linking. Also see −B [dynamic|static].

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

−e epsym Set 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 a "filter" on the symbol table of the shared object specified by name.

−h name In dynamic mode only, when building a shared object, record 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 dynamic linker as the name of the shared object to search for at run time.

−I name When building an executable, use 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 dynamic linker, /usr/lib/ld.so.1. Either case may be overridden by −Iname. exec will load this interpreter when it loads the a.out and will pass control to the interpreter rather than to the a.out directly.

−L path Add 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).

−l x Search a library libx.so or libx.a, the conventional names for shared object and archive libraries, respectively. In dynamic mode, unless the −Bstatic option is in effect, ld searches each directory specified in the library search path for a file libx.so or libx.a. The directory search stops at the first directory containing either. ld chooses the file ending in .so if −lx expands to two files whose names are 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 −Bstatic option is in effect, ld selects only the file ending in .a. A library is searched when its name is encountered, so the placement of −l is significant.

−M mapfile Read mapfile as a text file of directives to ld. See SunOS 5.3 Linker and Libraries Manual for description of mapfiles.

−o outfile Produce an output object file named outfile. The name of the default object file is a.out.

−Q [y|n] Under −Qy, 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 will result 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. −Qn suppresses version identification.

−R path A colon-separated list of directories used to specify library search directories to the run-time linker. If present and not null, it is recorded in the output object file and passed to the run-time linker. Multiple instances of this option are concatenated together with each path separated by a colon.

−u symname
Enter 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.

ENVIRONMENT

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.

LD_LIBRARY_PATH is also used to specify library search directories to the dynamic linker at run time. That is, if LD_LIBRARY_PATH exists in the environment, the dynamic linker will search the directories named in it, before its default directory, for shared objects to be linked with the program at execution.

Note: When running a set-user-ID or set-group-ID program, the dynamic linker will only search for libraries in /usr/lib and any full pathname specified within the executable as a result of run path being specified when the executable was constructed. Any library dependencies specified as relative pathnames will be silently ignored.

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_PRELOAD
A list of shared objects that are to be interpreted by the dynamic linker at run time. The specified shared objects are linked in after the program being executed and before any other shared objects that the program references.

Note that when running a set-user-ID or set-group-ID program, this option is silently ignored.

LD_RUN_PATH
An alternative mechanism for specifying a run path to the link editor (see -R option). If both LD_RUN_PATH and the -R option are specified, -R supersedes.

LD_DEBUG
Provide a list of tokens that will cause the run-time linker to print debugging information to the standard error. The special token help indicates the full list of tokens available.

Note: Environment variable-names beginning with the characters ‘LD_’ are reserved for possible future enhancements to ld.

NOTES

Options No Longer Supported

The following SunOS 4.x.y options do not have any replacement in this release: −Bnosymbolic (this is now the default if −Bsymbolic is not used), −d, −dc, and −dp, (these are now the default, see −b above to override the default), −M, −S, −t, −x, −X, and −ysym.

The following SunOS 4.x.y options are not supported: −align datum, −A name, −D −p, −T[text] hex, −T datahex. Much of the functionality of these options can be achieved using the −Mmapfile option.

Obsolete Options

The following SunOS 4.x.y options are obsolete in this release: −n, −N and −z.

FILES

libx.so libraries

libx.a libraries

a.out output file

LIBPATH usually /usr/ccs/lib:/usr/lib

Museum

Related Articles