LD(M) UNIX System V
Name
ld - invokes the link editor
Syntax
ld [options] filename
Description
The ld command combines several object files into one,
performs relocation, resolves external symbols, and supports
symbol table information for symbolic debugging. It creates
an executable program by combining one or more object files
and copying the executable result to the file a.out. The
filename must name an object or library file. By convention
these names have the ``.o'' (for 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 text file containing link
editor directives. By default, the file a.out is excutable
if no errors occurred during the load. If errors occur
while linking, ld displays an error message; 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 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(F)) 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 exist multiple
library members defining the same external symbol. The
library may be either a relocatable archive library or a
shared library. 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 should be invoked using the cc(CP) command instead of
invoking it 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. x.out Binaries
When ld is called, it scans all the object files that are to
be linked. If they are all COFF objects, then the resulting
binary will be in COFF format. If any of the object files to
be linked are in x.out format, any COFF modules in the group
will be converted to x.out and the resulting binary will be
in x.out format.
Common Options
The following options are recognized by ld, and are common
to producing both COFF and x.out binaries. Refer to the
sections ``Linking COFF Binaries'' and ``Linking x.out
Binaries'' for options specific to producing these binaries.
-o name
Sets the executable program filename to name instead of
a.out.
-r XENIX VERSION: Invokes the incremental linker,
/lib/ldr, with the arguments passed to ld to produce a
relocatable output file.
AT&T VERSION: Retains relocation entries in the output
object file. Relocation entries must be saved if the output
file is to become an input file in a subsequent ld run. The
link editor will not complain about unresolved references,
and the output file will not be executable.
-s Strips line number entries and symbol table information
from the output object file.
-u symbol
Designates the specified symbol as undefined. This is
useful for loading entirely from a 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 will define the symbol.
-V Outputs a message giving information about the version
of ld being used.
Linking COFF Binaries
The following options are recognized by ld for linking COFF
binaries:
-e epsym
Set the default entry point address for the output file
to be that of the symbol epsym.
-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.
-lx Search a library libx.a, where x is up to nine
characters. A library is searched when its name is
encountered, so the placement of a -l is significant.
By default, libraries are located in LIBDIR or LLIBDIR.
-m Produce a map or listing of the input/output sections
on the standard output.
-a Create an absolute file. This is the default if the -r
option is not used. Used with the -r option, -a
allocates memory for common symbols.
-t Turn off the warning about multiply-defined symbols
that are not the same size.
-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.
-L dir
Change the algorithm of searching for libx.a to look in
dir before looking in LIBDIR and LLIBDIR. This option
is effective only if it precedes the -l option on the
command line.
-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.
-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.
-Y[LU],dir
Change the default directory used for finding
libraries. If L is specified, the first default
directory which ld searches, LIBDIR, is replaced by
dir. If U is specified and ld has been built with a
second default directory, LLIBDIR, then that directory
is replaced by dir. If ld was built with only one
default directory and U is specified a warning is
printed and the option is ignored.
Linking x.out Binaries
The user must make sure that the most recent library
versions have been processed with ranlib(CP) before linking.
Library files for x.out format binaries must be in
ranlib(CP) format, that is, the first member must be named
__.SYMDEF, which is a dictionary for the library. ld
compares the modification dates of the library and the
__.SYMDEF entry, so if object files have been added to the
library since __.SYMDEF was created, the link may result in
an ``invalid object module'' that cannot run.
The following options are recognized by ld for linking x.out
binaries:
-A num
Creates a standalone program whose expected load
address (in hexadecimal) is num. This option sets the
absolute flag in the header of the a.out file. Such
program files can only be executed as standalone
programs. Options -A and -F are mutually exclusive.
-B num
Sets the text selector bias to the specified
hexadecimal number.
-c num
Alters the default target CPU in the x.out header. num
can be 0, 1, 2, or 3 indicating 8086, 80186, 80286 and
80386 processors, respectively. The default on
8086/80286 systems is 0. The default on 80386 systems
is 3. Note that this option only alters the default;
if object modules containing code for a higher numbered
processor are linked, then that will take precedence
over the default.
-C
Causes the link editor to ignore the case of symbols.
-D num
Sets the data selector bias to the specified
hexadecimal number.
-F num
Sets the size of the program stack to num bytes where
num is a hexadecimal number. This option is ignored for
80386 programs which have a variable sized stack. By
default 8086 programs have a variable stack located at
the top of the first data segment, and 80286 programs
have a fixed size 4096 byte stack. The -F option is
incompatible with the -A option that cannot be opened
by more than one user at the same time.
-g Includes symbolic information for sdb.
-i Creates separate instruction and data spaces for small
model programs. When the output file is executed, the
program text and data areas are allocated separate
physical segments. The text portion will be read-only
and shared by all users executing the file.
-La
Sets advisory file locking. Advisory locking is used on
files with access modes that do not require mandatory
locking.
-Lm
Sets mandatory file locking. Mandatory file locking is
used on files that cannot be opened by more than one
process at a time.
-m name
Creates a link map file named name that includes public
symbols.
-Mx Specifies the memory model. x can have the following
values:
s small
m middle
l large
h huge
e mixed
-n num
Truncates symbols to the length specified by num.
-N num
Sets the pagesize to hex-num (which should be a
multiple of 512) - the default is 1024 for 80386
programs. 8086/80186/80286 programs do not normally
have page-aligned x.out files and the default for these
is 0.
-P
Disables packing of segments
-R Ensures that the relocation table is of non-zero size.
Important for 8086 compatibility.
-Rd num
Specify the data segment relocation offset (80386
only). num is hexadecimal.
-Rt num
Specify the text segment relocation offset (80386 only)
num is hexadecimal.
-S num
Sets the maximum number of segments to num. If no
argument is given, the default is 128.
Files
/bin/ld
LIBDIR/libx.a libraries
LLIBDIR/libx.a libraries
a.out output file
LIBDIR usually /lib
LLIBDIR usually /usr/lib
See Also
as(CP), cc(CP), masm(CP), mkshlib(CP), ranlib(CP), exit(S),
end(S), a.out(F), ar(F).
Notes
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 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.
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.
If you are using XENIX binaries, please refer to the manual
entry for this utility in the XENIX Development Guide for
information on the appropriate usage with XENIX binaries.
Standards Conformance
ld is conformant with:
AT&T SVID Issue 2, Select Code 307-127;
and The X/Open Portability Guide II of January 1987.
(printed 2/15/90) LD(M)