ld(1)

Synopsis

   ld [options] file . . .

Description

ld will combine object files compiled for either the Intel IA-64 architecture or the Intel IA-32 architecure (also known as x86 or Pentium^®). For IA-64, ld accepts objects compiled for either the LP64 or ILP32 programming models. The first object given to ld on its command line determines what kind of file ld will produce (IA-64 LP64, IA-64 ILP32 or IA-32). All subsequent objects must match the model of the first object.

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

(For IA-32 objects only.) 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

(For IA-32 objects only.) 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

(For IA-32 objects only.) 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.

elf64

(For IA-64 LP64 objects only). Only when producing a relocatable object (-r). IA-64 relocatable objects that use the LP64 programming model may still use a 32-bit ELF container if all file offsets can be represented in 32 bits. Using a 32-bit ELF object instead of a 64-bit object saves disk space. By default, ld will attempt to create a 32-bit ELF relocatable when the input objects use the LP64 model. This option forces ld to create a 64-bit object.

-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

ld normally warns if two common symbols with the same name or a common symbol and an initialized definition with the same name have different sizes. -t turns off this warning.

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

-v

Turn on verbose tracing. ld will print the name of each symbol that causes an object to be extracted from an archive file, along with the name of the object.

-y symbol

Print the names of all files that reference or define the named 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 multidefs

ld will allow multiple defintions of the same global symbol within the same output object. Only the first definition is used in symbol resolution.

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

Creates a DT_ORIGIN entry in the object's dynamic section array. This signals to the dynamic linker that this object will use a $ORIGIN directive in a pathname specified to dlopen(3C); the dynamic linker will calculate the originating path for this object.

-z text

In dynamic mode only, force a fatal error if any relocations against non-writable, allocatable sections remain. This is the default for IA-64 objects.

-z warn_common

ld will issue a warning when a definition for a symbol from a shared object overrides a common definition for the same symbol coming from a relocatable object file.

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

import:symfile]

Import files provide a specification for the symbols that are provided by a shared object. They permit you to check that symbol definitions referenced by the objects you are linking together are actually provided by another shared object, without actually having that object in hand to link against.

symfile contains a list of symbols specifications and directives, one per line. Blank lines are ignored. A ``#'' character introduces a comment: the ``#'' and anything following it on the same line are ignored. A directive is introduced by a directive name, all of which begin with a ``%''. The directive name is followed on the same line by a string containing no white-space, or a string enclosed in double-quotes (").

Each symbol specification has the following form: name [tag [number]] where tag may be one of: function, object, syscall and number is a decimal, octal or hexadecimal number. The tag and number are optional. For symbols with the tags function and object, the optional number represents the symbol's size. The syscall tag is used by kernel extensions that define their own system calls. For symbols with the syscall tag, the optional number represents the system call number (this is typically used only by the implementation and should be ommitted for kernel extensions).

The -Bimport directive is processed as it is seen on the command line. Each symbol specified is processed as if it were defined in a shared object that has been specified on the ld command line. Normal symbol resolution rules apply. Symbols with the special syscall tag result in the creation of a special symbol defined against the SHN_MONTEREY_SYSCALL section. The value of such symbols is either 0 or the optional system call number supplied.

If the import file contains a %soname directive, the string provided by the directive is used to create a DT_NEEDED entry in the object's dynamic section array. This creates an explicit dependency on the object specified.

When building an IA-64 shared object only, the import file may also contain a %iversion directive. This directive supplies an interface name and version for use by kernel extensions. It specifies the name and version of the interface for the symbols specified in the import file. The interface name and version are supplied within a single string and are separated by a colon (for example: %iversion my_version_name:123). ld creates a DT_IMP_IVERSION entry with the given string in the object's dynamic section array. Only one %iversion directive may be given in a single import file. If multiple import files are specified on the command line and more than one references the same interface name, they must all reference the same version of that interface.

symbolic [=list | :symfile]

where list is a comma separated sequence of symbol names. symfile is a symbol file as described under -Bimport. -Bsymbolic does not recognize any symbol file directives. The optional tag and number fields in symbol specifications 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 | :symfile]

hide [=list | :symfile]

where list is a comma separated sequence of symbol names. symfile is a symbol file as described under -Bimport. -Bhide does not recognize any symbol file directives. For -Bhide, the optional tag and number fields in symbol specifications 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.

In symbol specifications for -Bexport, the optional tag syscall may be used by kernel extensions if they define their own system calls. The symbol table entries for such symbols will be marked specially so they can be recognized by the kernel loader. The function and object tags and the optional number field are ignored for -Bexport.

When building an IA-64 object shared object only, -Bexport recognizes a single symbol file directive: %iversion. This directive is used to specify an interface name and version number for kernel extensions. The interface name and version number are supplied within a single string and are separated by a colon (for example, %iversion my_version_name:323). This directive causes ld to produce a DT_MONTEREY_EXP_IVERSION member in the output object's dynamic section array. A single export file may contain only one %iversion directive, but a shared object may export symbols to multiple interfaces or multiple versions of the same interface by specifying multiple export files.

init

Specify the name of the routine whose address is used as the value of the DT_INIT dynamic section array entry (_init, by default).

fini

Specify the name of the routine whose address is used as the value of the DT_FINI dynamic section array entry (_fini, by default).

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.

-R path

Create a DT_RUNPATH entry in the object's dynamic section array. Path is a colon-separated list of pathnames. The dynamic linker will search this path to find this object's immediate dependencies at run-time. The path supplied by DT_RUNPATH is searched before the default search directory and after paths supplied by the environment variable LD_LIBRARY_PATH.

-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. LD_RUN_PATH is ignored if building a shared object. The paths it specifies are searched by the dynamic linker before those specified by LD_LIBRARY_PATH. LD_RUN_PATH is obsolete. Its use is discouraged in favor of the -R option to ld. If -R is specified, LD_RUN_PATH is ignored.

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.