NAME

ld − link editor for object files

SYNOPSIS

ld [options] files . . . 

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. 

The following options are recognized by ld:

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

−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 will create special position-independent relocations for references to functions defined in shared objects and will arrange 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. 

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

−e epsym Set the entry point address for the output file to be that of the symbol epsym.

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

−lx 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 Produce a memory map or listing of the input/output sections on the standard output. 

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

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

−s Strip symbolic information from the output file.  The debug and line 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. 

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

−z defs Force a fatal error if any undefined symbols remain at the end of the link.  This is the default when building an executable.  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 nodefs
Allow undefined symbols. This is the default when building a shared object. It may be used when building an executable in dynamic mode and linking with a shared object that has unresolved references in routines not used by that executable. This option should be used with caution.

−z text In dynamic mode only, force a fatal error if any relocations against non-writable, allocatable sections remain. 

−z sysinuser
Allow system segments in user space, i.e. below address 0x80000000. This option applies to MC88000 based systems only.

−z lowzeros
Allow NULL pointer dereferences.

−z fillholes
Assign virtual addresses to output segments in such a way as to fill in memory holes which were created by use of a mapfile.

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

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

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

−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/libc.so.1.  Either case may be overridden by −I.  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 with −L options, then in the standard directories.  This option is effective only if it precedes the −l option on the command line. 

−M mapfile
In static mode only, read mapfile as a text file of directives to ld.  Because these directives change the shape of the output file created by ld, use of this option is strongly discouraged. 

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

−V Output a message giving information about the version of ld being used. 

−YP, dirlist
Change the default directories used for finding libraries. dirlist is a colon-separated path list. 

The environment variable LD_LIBRARY_PATH may be used to specify library search directories.  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

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. 

The environment variable LD_RUN_PATH, containing a directory list, may also be used to specify library search directories to the dynamic linker.  If present and not null, it is passed to the dynamic linker by ld via data stored in the output object file. 

FILES

libx.so libraries

libx.a libraries

a.out output file

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

SEE ALSO

as(1), cc(1), exec(2), exit(2), end(3C), a.out(4), ar(4). 

NOTES

Through its options, the link editor gives users great flexibility; however, those who use the −M mapfile option must assume some added responsibilities.  Use of this feature is strongly discouraged. 

  —  C Development Set