ld
PURPOSE
Links object files.
SYNOPSIS
ld [ -sxrdinmK ] [ -oname ] [ -esymbol ] [ -usymbol ] [ -Qkey ] [ -Rnum ]
[ -Hnum ] [ -Ynum ] [ -Zstring ] [ -Ldir ] [ -Tnum ] [ -Dnum ] [ -Bnum ]
[ -Snum ] [ -Anum ] [ -Vnum ] [ -kkey:path ] [ -j[key:]num ]
file...[ -Nfile...]...[ -G ] [ -lkey ]...
DESCRIPTION
The ld command (the linkage editor) combines the speci-
fied object files into one, resolving external references
and searching libraries. It produces an object module
that can be run or that can become a file parameter in
another call to ld. In the latter case, you must use the
-r flag to preserve the relocation bits. ld places its
output in a file named a.out. It makes this file execut-
able if no errors occur during the link and if the -r
flag is not specified.
The linkage editor links object files and searches object
libraries in the order specified. It links object
modules unconditionally, but links from the library only
those files that define an unresolved external reference.
If a routine from a library calls another routine in that
library, the called routine must follow the calling
routine.
Unless you use the -e flag to specify another entry
point, the first byte of the first nonnull text segment
(or the first byte of the data segment if all text seg-
ments are null) becomes the entry point of the output
file.
The reserved symbols _text, _data, _sdata, _etext,
_edata, and _end (in C text, data, sdata, etext, edata,
and end) are set to the first location of the program,
the first location of the data, the segment number of the
data, the first location above the program, the first
location above initialized data, and the first location
above all data, respectively. You cannot define these
symbols.
Because you can use ld to link modules intended to run on
other machines, some of its action depends upon the
architecture of the computer system on which you intend
to run the module. ld recognizes that architecture auto-
matically from the input modules and modifies its action
accordingly. You can use some of its flags to alter the
default behavior of ld for a particular architecture.
FLAGS
The ld command recognizes several flags. Except for -l
entries, which are really abbreviations for file names,
the order in which you specify flags does not affect the
way they work. You can specify numeric values in either
decimal, octal (with a leading 0), or hexadecimal (with a
leading 0x or 0X) format.
-Anum Stores num in the a_misc field of the output file
header. This field indicates the size of memory,
in bytes, allocated to the process which runs the
file. On many systems, the stand-alone loader or
kernel uses this value to set the base of the
runtime stack pointer.
-Bnum Makes num the starting address for the uninitial-
ized data (bss) segment of the output file. The
default starting address is the first storage
unit after the end of the data segment. Not all
architectures support the separation of data and
bss segments.
-d Defines common storage, even if you have speci-
fied the -r flag.
-Dnum Makes num the starting address for the initial-
ized data segment of the output file. The
default starting address begins at location 0 (if
-i is in effect), at the first storage unit after
the end of the text segment, or, if -n is in
effect, at the next page or segment boundary.
-elabel Makes label the entry point of the executable
output file.
-Hnum Makes num the boundary, usually the page size, to
which the text segment must be padded if it has a
different protection than does the data segment.
Specify this parameter only to override the
default value for the given architecture.
-i Assigns text and data segments to separate
address spaces in memory, with the text segment
read-only--if the architecture supports read-only
memory--and shared among all users. The data
segment starts at location zero unless set with
-D. If the architecture does not support sepa-
rate instruction and data space, this flag is
treated as if it were -n.
-j[key:]num
Assigns the shared library image key to location
num. If you do not specify key, do not use
location num when you assign the runtime location
of the shared library text images. The exact
interpretation of num depends on the target
architecture. On the RT PC, num refers to the
segment register, one of 4 through 13. You can
specify -j once for each shared library image
that has an assigned location.
-kkey:path
Maps any reference to the shared library image
with the shared library key into path. Instead
of adding the shared library key to the runtime
table, add path. You can specify -k once for
each shared library image with a remapped key.
-K Loads the a.out header into the first bytes of
the text segment, followed by the text segments
from the object modules. This flag causes pages
of executable files to be aligned on pages in the
file system so that they can be demand paged on
systems that support paging. This flag provides
mapped file support for the text and data seg-
ments.
-lkey Searches the specified library file, where key
selects the file libkey.a. ld searches for this
file in the directory specified by an -L flag,
then in /lib and /usr/lib. It searches library
files in the order that you list them on the
command line.
-Ldir Looks in dir for files specified by -l keys. If
it does not find the file in dir, ld searches the
standard directories.
-m Lists on standard output the names of all files
and archive members used to create the output
file.
-n Makes the text segment read-only--if the archi-
tecture supports read-only memory--and shared
among all users running the file. The data
segment starts at the first segment boundary fol-
lowing the end of the text unless set with -D.
On architectures which only permit read-only text
with separate text and data spaces, the -n flag
is treated as if it were the -i flag.
-o name Assigns name rather than a.out to the output
file.
-r Writes relocation bits in the output file so that
it can serve as a file parameter in another ld
call. This flag also prevents common symbols
from being assigned final definitions and sup-
presses the "undefined symbol" diagnostic mes-
sages.
-Rnum Makes num bytes the allocation unit for objects
manipulated by ld, such as segments or common
objects. Typically this value ranges from 1 to
8. Specify this parameter only to override the
default value for the given architecture.
-s Strips the symbol table, line number information,
and relocation information from the output. This
saves space but impairs the usefulness of the
debugger. Using the strip command has the same
effect. This flag is turned off if there are any
undefined symbols.
-S num Makes num the maximum size the user stack is
allowed to grow. This value represents the
number of bytes allowed. If you do not specify
this argument, the system assumes a default limit
of 1 MB.
-Tnum Makes num the starting address for the text
segment of the output file. If not specified,
the text segment begins at location zero.
-u sym Enters sym into the symbol table as an undefined
symbol. This is useful when linking from only a
library, since initially the symbol table is
empty and an unresolved reference is needed to
force the linking of the first routine.
-Vnum Stores num in the a_version field of the output
file header; num must be in the range 0 to 32767.
-x Does not enter local symbols in the output symbol
table; enters only external symbols. This flag
saves some space in the output file.
-Ynum In a segmented system, makes num the boundary to
which the text segment should be padded if it has
a protection different from that of the data
segment. If num is zero, the padding is either
that selected by the -H flag or the default value
associated with that flag. Specify this param-
eter only to override the default value for the
given architecture.
-Zstr Prefixes with str the names specified by the -l
key. For example, with -Z/test and -lxyz, ld
looks for the file /test/lib/llbxyz.a or, if that
file does not exist, /test/usr/lib/libxyz.a. The
ordinary directories will not be searched. This
flag is most useful when cross-compiling.
EXAMPLES
1. To link several object files and produce an a.out
file to run under the AIX Operating System without
the Floating-Point Accelerator:
ld -n -t0x10000000 -K /lib/crt0.o pgm.o subs1.o subs2.o -lrts -lc
A simpler way to accomplish this is to use the cc
command to link the files as follows:
cc pgm.o subs1.o subs2.o
Since the cc command automatically uses the link
options and necessary support libraries, you do not
need to specify them on the command line (it gets
this information from the configuration file cc.cfg).
For this reason, you should use cc to link files when
you are producing programs that run under the AIX
Operating System.
2. To specify the name of the output file:
cc -o pgm pgm.o subs1.o subs2.o
This stores the linked output in the file "pgm".
3. To conditionally link library subroutines:
cc pgm.o subs1.o subs2.o mylib.a -ltools
This links the object modules "pgm.o", "subs1.o", and
"subs2.o" unconditionally. It then links the subrou-
tines from "mylib.a" that are used by the preceding
modules. (This is often called conditional linking.)
Then ld conditionally links subroutines from the
library specified by "-ltools". (This means
"/lib/libtools.a", if it exists. If ld does not find
this file, then it looks for "/usr/lib/libtools.a".)
Note: Always list libraries and -l flags at the end
of the ld or cc command lines.
FILES
/lib/lib*.a Libraries.
/usr/lib/lib*.a Libraries.
a.out Output file.
RELATED INFORMATION
The following commands: "ar," "as," "cc," and "shlib."
The a.out file in AIX Operating System Technical Refer-
ence.
The discussion of ld in AIX Operating System Programming
Tools and Interfaces and in Assembler Language Reference.