ld(CP)

Syntax

Description

In general, the filename must name an object file or a library file. By convention these names have the .o (for object), .so (for shared object), or .a (for archive library) extensions. If more than one name is given, the names must be separated by one or more spaces. If any input file filename is not an object file, ld assumes it is either an archive library or a shared object. When linking COFF files, the filename can also name a text file containing link editor directives (``ifile'') and ld assumes an input file to be an ``ifile'' if it is not an object file, not an archive library and not a shared object. By default, the output file a.out is executable if no errors occurred during the load. If errors occur while linking, ld displays an error message and the resulting a.out file is unexecutable.

ld concatenates the contents of the given object files in the order given in the command line. Library files in the command line are examined only if there are unresolved external references encountered from previous object files. 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. 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 library is searched iteratively to satisfy as many references as possible and only those routines that define unresolved external references are concatenated. The library (archive) symbol table (see ar(FP)) is searched sequentially with as many passes as are necessary to resolve external references which can be satisfied by library members. Thus, the ordering of library members is functionally unimportant, unless there are multiple library members defining the same external symbol. However, object and library files are processed at the point they are encountered in the argument list, so the order of files in the command line is important. In general, all object files should be given before library files. ld sets the entry point of the resulting program to the beginning of the first routine.

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 (the default when linking ELF files), 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.

ld should be invoked using the cc(CP) command instead of directly. cc invokes ld as the last step of compilation, providing all the necessary C language support routines. Invoking ld directly is not recommended since failure to give command line arguments in the correct order can result in errors.

Generating COFF vs. ELF binaries

Archive libraries given on the command line through -l option are not scanned for their file formats. If any of these libraries are in ELF format and ld uses COFF format, determined either through option -b or through scanning, ld fails and no executable will be produced. Always specify option -b elf if ELF and COFF files might be mixed.

ifile vs. mapfile

If object files are linked statically, link editor command language directives can be passed to ld in a file named on the command line. This file is known as ``ifile'' when linking COFF files and ``mapfile'' when linking ELF files.

Unfortunately, the directives for ELF and COFF file formats are not the same. In other words, ``ifile''s created for linking COFF files cannot be used directly for linking ELF files, and ``mapfile'' cannot be used directly for linking COFF files. Furthermore, an ``ifile'' is passed to ld directly while a ``mapfile'' must be passed to ld as the argument of option -M. See ``Link editor command language'' in ``COFF link editor'' in the Programming Tools Guide and ``Mapfile option'' in Developer's Topics for further details.

Common options

-a

Create an absolute (executable) file and give errors for undefined references. For COFF objects, this is the default except when the -r option is also used. If -r is used, then -a allocates memory for common symbols. For ELF objects, this option is available in static mode only and is the default. This option can not be combined with -r when the ELF objects are linked.

-b [elf|coff|ibcs2]

The default is to invoke /bin/ld and scan the object files to be linked in order to determine the file format for the resulting binary. See ``Generating COFF vs. ELF binaries.'' If any one of the option arguments, elf, coff and ibcs2, is specified, ld will not scan the object files. The file format is that requested through the option:

-b coff

Invoke /usr/ccs/bin/coff/ld to produce an COFF binary.

-b elf

Invoke /usr/ccs/bin/elf/ld to produce an ELF binary.

-b ibcs2

Invoke /usr/ccs/bin/coff/ld to produce an COFF binary.

When linking ELF object files in dynamic mode this option can also be used without an option argument in addition to -belf -dy. A -b option without an argument instructs ld not to do special processing for relocations that reference symbols in shared objects when creating an executable. 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.

-e epsym

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

-lx

Search a library libx.a (and also libx.so if any user specified objects are in ELF format), where x is up to nine characters. When COFF objects are linked, or when the -Bstatic option is in effect, ld searches each directory specified in the library search path for a file libx.a. The directory search stops at the first directory containing libx.a. In dynamic mode, that is, when ELF objects are linked and the -Bstatic option is not in effect, ld searches for both libx.so and libx.a and chooses libx.so if both libx.so and libx.a are found. If no libx.so is found, then ld accepts libx.a. A library is searched when its name is encountered, so the order of the -l, -B and -L is significant. By default, libraries are located in LIBDIR or LLIBDIR.

-L dir

Change the algorithm of searching for libx.a (and libx.so when applicable). Search libraries in directories dir (in order) first before the standard directories LIBDIR and LLIBDIR (see the -YP option) are searched. This option is effective only if it precedes the -l option on the command line.

-m [mem_map]

Produce a memory map of the input/output sections and send the map to standard output. For COFF objects, the memory map can also be saved to the file mem_map.

-o name

Set the output filename to name instead of a.out.

-r

Retain relocation entries in the output object file and combine relocatable object files to produce one relocatable object file. This option should be used if the output file is to be used as input file in a subsequent ld run. The link editor will not complain about unresolved references, and the output file will not be executable. This option cannot be used in dynamic mode or with -a when ELF objects are linked.

-Rarg[,arg,...]

Set runtime-behavior characteristics. The option accepts a comma-separated list of arguments. Note that there is no space between -R and its arguments. Each argument is one of the accepted values for the -a, -b, or -X flags of cc(CP), and should match the flags used when the objects were compiled. The default is -Rxpg4plus,elf,a for the ELF ld, and -Rxpg4plus,coff,a for the COFF ld. The ELF ld ignores -Rcoff and -Ribcs2; the COFF ld ignores -Relf.

Multiple -R arguments may be given; the last argument of each type (-a, -b, or -X) is the one used. For example, -Ransi,a -Rxpg4,coff is equivalent to -Rxpg4,coff,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.

-u symbol

Designate the specified symbol 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 ld line is significant; it must be placed before the library which defines the symbol.

-V

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

-Y[LPU],dir

Change the default standard directories used for finding libraries. Do not combine either -YL or -YU with -YP.

-YL,dir

Replace the first default directory which ld searches, LIBDIR, by dir.

-YU,dir

Replace the second default directory which ld searches, LLIBDIR, by dir.

-YP,dir

Replace the default standard directories which ld searches by the colon-separated directory list, dir.

Linking COFF binaries

-f fill

Set the default fill pattern for ``holes'' within an output section as well as initialized .bss sections. The argument fill is a two-byte constant.

-M

Output a message for each multiply-defined external definition.

-N

Put the text section at the beginning of the text segment rather than after all header information, and put the data section immediately following text in the core image.

-strict

Suppress the generation of the symbols edata, etext and end which are aliases, used for compatibility with previous releases, to the symbols _edata, _etext and _end. This prevents name space pollution when linking object files compiled in any one of ANSI, POSIX, or X/OPEN environments (see -a ansi, -a posix and -a xpg4 options to the cc(CP) command).

-t

Turn off the warning about multiply-defined symbols that are not the same size.

-VS num

Use num as a decimal version stamp identifying the a.out file that is produced. The version stamp is stored in the optional header.

-x

Do not preserve local symbols in the output symbol table; enter external and static symbols only. This option saves some space in the output file.

-z

Do not bind anything to address zero. This option will allow runtime detection of null pointers. See also -z in ``Linking ELF binaries.''

Linking ELF binaries

-B arg

where arg can be any one of the following:

dynstat

dynstat can be either dynamic or static. These options govern library inclusion. The argument dynamic is valid in dynamic mode only (-belf -dy). 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.

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, 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, -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. Neither -Bhide nor -Bexport may be used with -dn.

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.

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.

-d yn

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

-G

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

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

-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(S) will load this interpreter when it loads the a.out and will pass control to the interpreter rather than to the a.out directly.

-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(CP) command. If yn is n (the default), the version information is suppressed.

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

Environment variables

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.

Exit values

Files

/usr/ccs/bin/coff/ld

/usr/ccs/bin/elf/ld

/bin/ld

LIBDIR

usually /lib

LLIBDIR

usually /usr/lib

LIBPATH

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

LIBDIR/libx.a
LIBDIR/libx.so

libraries

LLIBDIR/libx.a
LLIBDIR/libx.so

libraries

./a.out

default output file

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

language-specific message file (See LANG on the environ(M) man page.)

Notes

-

C defines a zero pointer as null. A pointer to which zero has been assigned must not point to any object. To satisfy this, users must not place any object at virtual address zero in the program's address space.

-

When the link editor is called through cc(CP), a startup routine is linked with the user's program. This routine calls exit( ) (see exit(S)) after execution of the main program. If the user calls the link editor directly, then the user must insure that the program always calls exit( ) rather than falling through the end of the entry routine.

The symbols etext, edata, and end (see end(S)) are reserved and are defined by the link editor. It is incorrect for a user program to redefine them. The following only applies to the linking of COFF binaries. The ``_'' forms are always defined, the non ``_'' forms are also defined in non-strict modes.

If the link editor does not recognize an input file as an object file or an archive file, it will assume that it contains link editor directives and will attempt to parse it. This will occasionally produce an error message complaining about ``syntax errors''.

Arithmetic expressions may only have one forward referenced symbol per expression.

See also

``COFF link editor'' in the Programming Tools Guide, and
``Mapfile option'' in Developer's Topics

Standards conformance