invokes the link editor
ld [options] filename [[options] filename]
command combines several object files
into one, performs relocation, resolves external symbols,
and supports symbol table information for symbolic debugging.
Both ELF and COFF file
formats are supported (see ``Generating COFF vs. ELF
binaries'') and ld
can operate in either static or dynamic modes (see -d).
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
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
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.
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
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
When ld is called, it scans all object files
and library files (if any) given
through filename arguments
on the command line.
It determines whether an object file
is in COFF or ELF format and executes the appropriate
binaries in each case.
The file format of a library is treated as the same as the
file format of the first module in that library file.
ld defaults to ELF format
if none of the user specified object files are in ELF
or COFF format.
If at least one of the user specified object files is in
ELF format, all COFF modules
in the group will be converted to ELF
and the resulting binary will be in ELF format.
If none of the user specified object files are in
ELF format and there is at least one user specified
COFF object, then the
resulting binary will be in COFF format.
To force the resulting binary to a particular format, use, for example,
the option -b elf or -b coff.
Since this utility relies on
the files in /usr/ccs/bin/coff, /usr/ccs/lib/coff,
/usr/ccs/bin/elf and /usr/ccs/lib/elf,
changing or moving any files in
those directories results in an error.
Only the first module in an archive library is scanned for its
file format and this file format is used
as the file format for all modules in that archive library.
Mixing ELF and COFF modules in the same
archive library causes ld to fail.
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.
``Link editor command language''
``COFF link editor'' in the Programming Tools Guide
``Mapfile option'' in Developer's Topics
for further details.
The following options are recognized by ld,
and are common to producing both COFF and ELF binaries.
Some options listed here (for example, -a or -r),
although common to both formats, have slightly different meanings
depending on the format of the object files being linked.
Refer to the sections ``Linking COFF binaries'' and
``Linking ELF binaries'' for format-specific options.
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.
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
is specified, ld will not scan the object files.
The file format is that requested through the option:
Invoke /usr/ccs/bin/coff/ld to produce an COFF binary.
Invoke /usr/ccs/bin/elf/ld to produce an ELF binary.
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.
Set the default entry point address for the output file
to be the address of epsym.
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
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
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
By default, libraries are located in LIBDIR
Change the algorithm of searching for
libx.a (and libx.so
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.
Produce a memory map of the input/output sections and send the map to standard
For COFF objects, the memory map can also be saved to the file
Set the output filename to name
instead of a.out.
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.
Set runtime-behavior characteristics.
The option accepts a comma-separated list of arguments. Note
that there is no space between -R and its arguments.
is one of the accepted values for the -a, -b, or
-X flags of
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
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
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.
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.
Output a message giving information about the version of
ld being used.
Change the default standard directories used for finding libraries.
Do not combine either -YL or -YU
Replace the first default directory
which ld searches, LIBDIR,
Replace the second default directory
which ld searches, LLIBDIR,
Replace the default standard directories which ld searches
by the colon-separated
directory list, dir.
Linking COFF binaries
The following options are also available for linking COFF binaries:
Set the default fill pattern for ``holes'' within an
output section as well as initialized
The argument fill is a two-byte constant.
Output a message for each multiply-defined external definition.
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.
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
Turn off the warning about multiply-defined symbols that are not the same size.
Use num as a decimal version stamp identifying the
a.out file that is produced.
The version stamp is stored in the optional header.
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.
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
The following options are also available for linking ELF binaries:
where arg can be any one of the following:
dynstat can be either
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,
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
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
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.
All uninitialized global variables within a module will be assigned contiguous
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.
uses static linking only when yn is
otherwise, by default, or when yn is
uses dynamic linking.
In dynamic mode only, produce a shared object.
Undefined symbols are allowed unless the
option is specified.
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.
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,
Either case may be overridden by -I.
will load this interpreter
when it loads the
and will pass control to the interpreter rather than
to the a.out directly.
In static mode only, read mapfile as a text file
of directives to
Because these directives change the shape of the output file
created by ld, use of this option is strongly discouraged.
If yn is
an identification string is added
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
command. If yn is n
(the default), the version information is suppressed.
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.
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.
In dynamic mode
only, force a fatal error if any relocations against
non-writable, allocatable sections remain.
There are two environment variables that can be used to
specify alternate library search directories when ELF objects
One is LD_LIBRARY_PATH and the other is
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:
Thus, if ld is called with the following occurrences of -L:
ld . . . -Lpath1 . . . -Lpathn . . . -lx
then the search path ordering for the library
(libx.so or libx.a)
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
via data stored in the output object file.
Upon successful completion,
the exit status of ld is 0,
otherwise the exit status is non-zero.
default output file
language-specific message file (See
LANG on the
Through its options and input directives, the common link
editor gives users great flexibility; however, those who use
the input directives must assume some added responsibilities.
Input directives and options should insure the following
properties for programs:
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
a startup routine is linked with the user's program.
This routine calls exit( ) (see
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
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.
``COFF link editor'' in the Programming Tools Guide,
``Mapfile option'' in Developer's Topics
ld is not part of any
currently supported standard;
it was developed by UNIX System Laboratories, Inc. and
is used by permission.
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003