ld(1)

Synopsis

   ld [options] file . . . 

Description

If any argument is a library, it is searched only 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 object file members 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 typically 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 yn

ld uses static linking only when yn is n; otherwise, by default, or when yn is y, ld uses dynamic linking.

-e epsym

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

-f arg

where arg is a processor -specific linking option:

udk

The system uses certain heuristics in distinguishing between binaries compiled for SCO OpenServer using the SCO OpenServer application binary interface and binaries compiled for SCO UnixWare 2.X or UnixWare 7 using the binary interface specified by the "System V Application Binary Interface Intel386 Processor Supplement." These heuristics can fail in rare cases. The udk flag can be used in cases when the heuristcs break down. It instructs the linker to add a special mark to a binary object to positively identify it as a binary compiled by the UnixWare 7 compiler and intended to be able to run on UnixWare 7, SCO OpenServer and SCO UnixWare 2.X.

osr5

iabi

By default, object files compiled for SCO OpenServer cannot be linked with object files compiled for SCO UnixWare 2.X or for UnixWare 7. If the linker detects an attempt to mix such objects, it will issue a fatal error. The osr5 flag instructs the linker to accept mixed SCO OpenServer, SCO UnixWare 2.X and UnixWare 7 objects and to create an output file that appears to the system as if targeted for SCO OpenServer. The iabi flag instructs the linker to accept mixed SCO OpenServer, SCO UnixWare 2.X and UnixWare 7 objects but to create an output file that appears to the system as if targeted for SCO UnixWare 2.X or UnixWare 7. The osr5 flag cannot be combined with the udk flag.

-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 shared object's pathname. Accordingly, name will be used by the dynamic linker as the pathname 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 order of the -l, -B and -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.

-x

Remove local symbols and debugging information from a shared object or static or dynamic executable.

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

-B arg

where arg can be any one of the following:

dynstat

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

symbolic [=list | :filename]

where list is a comma separated sequence of symbol names. filename contains a list of symbol names, one symbol name per line. Any line beginning with a ``#'' character and blank lines are ignored. When building a shared object, if a definition for a named symbol exists, bind all references to the named symbol to that definition. If no list of symbols is provided, bind all references to symbols to definitions that are available; ld will issue warnings for undefined symbols unless -z defs overrides. 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.

bind_now

In dynamic mode only, this option adds a DT_BIND_NOW entry to the ``.dynamic'' section of the output file. This entry instructs the dynamic linker to process all relocations for the object containing this entry before transferring control to the program. The presence of DT_BIND_NOW takes precedence over a directive to use lazy binding for this object when specified through the environment or via dlopen.

export[=list | :filename]

hide [=list | :filename]

where list is a comma separated sequence of symbol names. filename contains a list of symbol names, one symbol name per line. Any line beginning with a # character and blank lines are ignored.

Normally, when building a shared object or relocatable object, ld makes all global and weak names defined in the shared object visible outside of the object itself (exported). When building an executable, it makes visible only those names used by the shared objects with which the executable is linked. All other names are hidden. This behavior can be modified with -Bhide and -Bexport.

When building a shared object or relocatable object -Bexport is the default. All global and weak definitions are exported. -Bexport with a set of symbol names instructs ld to hide all global and weak definitions, except those in the specified set. -Bhide means to hide all global and weak definitions. -Bhide with a set of symbol names means to export all global and weak definitions, except for those in the set of names.

When building an executable, -Bhide is the default. Only those names referenced by the shared objects with which the executable is linked are exported. -Bhide with a set of symbol names instructs ld to export all global and weak definitions, except those in the specified set. Names in a -Bhide list that are referenced by the shared objects with which the executable is linked, are ignored, that is, they are exported. -Bexport means to export all global and weak definitions. -Bexport with a set of symbol names means to hide all global and weak definitions except those in the set of names and those referenced by the shared objects with which the executable is linked.

If -Bhide and -Bexport are used together, one of the options must contain a set of symbol names and the other must not. In this case, the option without the symbol set is ignored. -Bhide and -Bexport may be used when creating a dynamically-linked executable, shared object or relocatable object. Neither may be used when creating a statically linked executable.

sortbss

All uninitialized global variables within a module will be assigned contiguous addresses. This is the way these variables were assigned by the COFF version of the link editor.

-G

In dynamic mode only, produce a shared object. Undefined symbols are allowed unless the -z defs option is specified.

-I name

When building an executable, use name as the pathname 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 (in order), and then in the standard directories (see the -YP option). This option is effective only if it precedes a -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 yn

If yn is y, an identification 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 instances of such when there have been multiple linking steps, such as when using ld -r. This is identical with the default action of the cc command. If yn is n (the default), the version information is suppressed.

-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 

Thus, if ld is called with the following occurrences of -L:

   ld . . . -Lpath1 . . . -Lpathn . . . -lx 

then the search path ordering for the library x (libx.so or libx.a) 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 it names before its default directory for shared objects to be linked with the program at execution.

Additionally, the environment variable LD_RUN_PATH (which also contains a directory list) may be used to specify library search directories to the dynamic linker. If present and not empty, 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

/usr/lib/local/locale/LC_MESSAGES/uxcds

language-specific message file [See LANG on environ(5).]

References

Notices

ld should be invoked directly only if -r is used to create a relocatable object to be used in a later link. Creation of an executable or shared object should be done through the CC or cc command. The CC command must be used if any input object files contain C++ code.

ld's error messages sometimes include messages generated by the object file processing library, libelf. The most common of these messages are

   libelf error: Memory error: vm stats 
   libelf error: Memory error: output write