LD(1,C) AIX Commands Reference LD(1,C)
-------------------------------------------------------------------------------
ld
PURPOSE
Links object files.
SYNTAX
+---------------------------+ +-- -o a.out ---+
ld ---| +-------------------+ |---| |--->
+---| -d -elabel -qtarg |---+ +--- -o name ---+
^ | -i -Bnum -Qfile | | ^ |
| | -K -Dnum -Ysym | | +-----------+
| | -m -Hnum -Zstr | |
| | -n -Ldir -usym1 | |
| | -r -Tnum -xa | |
| | -s -ss | |
| | -x -Vnum | |
| +-------------------+ |
+-----------------------+
+------------+ +----------+
>---| |---| |---|
+--- file ---+ +- -l key -+
^ |
+--------+
-----------------
1 You must put a blank between these items.
DESCRIPTION
The ld command (also called the linkage editor) combines the specified object
files into one file, 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 command. In the latter case, you must use the -r flag to
preserve the relocation bits. The ld command places its output in a file named
a.out. It makes this file executable if no errors occur during the link and if
the -r flag is not specified.
The ld command 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.
Processed November 8, 1990 LD(1,C) 1
LD(1,C) AIX Commands Reference LD(1,C)
Unless you use the -e flag to specify another entry point, the first byte of
the first non-null text segment (or the first byte of the data segment if all
text segments are null) becomes the entry point of the output file.
The reserved 370 symbols etext, edata and end are set to 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 the ld command 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. The ld command recognizes that
architecture automatically from the input modules and modifies its action
accordingly. You can use some of its flags to alter the default behavior of
the ld command for a particular architecture.
Notes:
1. On AIX/370, it is possible to convert a non-XA load module into an XA load
module with the following command:
ld -xa -o xamodule module
2. Use the -ss option to force segments aligned on 64-Kb boundaries (the
default is 1 Mb). Without using -ss, you have a maximum of 5 Mb available
to be allocated by the sbrk system call and malloc subroutine. Using -ss,
you can have more than 7 Mb available.
3. If you are using malloc to allocate large amounts of memory, use the
lmalloc option to include the alternate library libmalloc.a. The default
malloc subroutine rounds requests to the next higher power of two bytes
long, and may allocate more memory than you request. For instance, a
request for 4.5 Mb is rounded to 8 Mb and then fails.
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.
-Qfile Writes library dependency information, suitable for inclusion to
make, to file "file".
-qtarg By default the -Q option uses the loadmodule name specified by the
-Q flag as the target name. If specified, targ is used for the
dependency target in the library dependency file.
The following flags may be specified on AIX PS/2:
Processed November 8, 1990 LD(1,C) 2
LD(1,C) AIX Commands Reference LD(1,C)
-Bnum Makes num the starting address for the uninitialized 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 specified the -r flag.
-Dnum Makes num the starting address for the initialized data segment of
the output file. The default starting address begins at location 0
(if the -i flag is in effect), at the first storage unit after the
end of the text segment, or, if the -n flag is in effect, at the
next page or segment boundary.
-elabel Makes label the entry point of the executable output file.
Note: The cc command on AIX/370 prepends an underscore to symbol
names, while AIX PS/2 does not.
-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 0 unless set with the -D flag. If the
architecture does not support separate instruction and data space,
this flag is treated as if it were the -n flag. (This option cannot
be used with the -K flag.) The -i flag is useful primarily when you
are linking executables (cross-compiling) on different machines.
-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
filesystem so that they can be demand paged on systems that support
paging. This flag provides mapped file support for the text and
data segments.
Note: This flag is required for programs to execute on the PS/2 and
is normally set by the cc command.
-n Makes the text segment read-only-if the architecture supports
read-only memory-and shared among all users running the file. The
data segment starts at the first segment boundary following the end
of the text unless set with the -D flag. 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. (This option cannot
be used with the -i flag.)
Processed November 8, 1990 LD(1,C) 3
LD(1,C) AIX Commands Reference LD(1,C)
-Tnum Makes num the starting address for the text segment of the output
file. If not specified, the text segment begins at location zero.
-Zstr Prefixes with str the names specified by the -l key. For example,
with -Z/test and -lxyz, the ld command looks for the file
/test/lib/llbxyz.a or, if that file does not exist,
/test/usr/lib/libxyz.a. The ordinary directories are not searched.
This flag is most useful when cross-compiling.
The following flags may be specified on AIX/370:
-f fill Sets the default fill pattern for holes within the output section as
well as initialized DSS sections. fill is a 2-byte constant.
-lkey Searches the specified library file, where key selects the file
libkey.a. The ld command searches for this file in the directory
specified by an -L flag, and then in the directories /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 key. If it does not find the
file in dir, the ld command searches the standard directories.
-m Lists on standard output the names of all files and archive members
used to create the output file along with a memory map.
-N Makes the text writeable.
-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 suppresses the
"undefined symbol" diagnostic messages.
-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.
-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 optional file
header; num must be in the range 0 to 32767. (This option is -VS on
the 370.)
-x Does not enter local symbols in the output symbol table; enters only
external and static symbols.
Processed November 8, 1990 LD(1,C) 4
LD(1,C) AIX Commands Reference LD(1,C)
-Y[LU],dir Looks in dir to find libraries. If the L flag is specified, the ld
command replaces the first default directory with dir. If the U
flag is specified, the ld command replaces the second default
directory with dir. (-L is the only AIX/370 option.)
-xa Generates an 370/XA executable module.
-ss Generates executables aligned on a 64-Kb segment boundary (default
is 1 Mb).
Note: The default is for text to be read-only and shared.
EXAMPLES
1. To link several object files and produce an a.out file to run under the
AIX Operating System on a PS/2.
ld 0x00400000 -K /lib/crt0.o pgm.o subs1.o subs2.o -lc /lib/crtn.o
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 command 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 command links the object modules "pgm.o", "subs1.o", and "subs2.o"
unconditionally. It then links the subroutines from "mylib.a" that are
used by the preceding modules. (This is often called conditional linking.)
Then the ld command conditionally links subroutines from the library
specified by "-ltools". (This means "/lib/libtools.a", if it exists. If
the ld command does not find this file, it looks for
"/usr/lib/libtools.a".)
Note: Always list libraries and -l flags at the end of the ld or cc
command lines.
4. To generate library dependencies to file "depsfile":
Processed November 8, 1990 LD(1,C) 5
LD(1,C) AIX Commands Reference LD(1,C)
cc -o pgm pgm.c -W1,-Qdepsfile
This generates dependencies in the form:
pgm.o: /lib/libc.a(printf.o)
5. To generate library dependencies with a different target name:
cc -o pgm pgm.c -W1,-Qdepsfile -W1,-qpgm
This generates dependencies in the form:
pgm: /lib/libc.a(printf.o)
This facilitates make scripts in generating the correct dependencies.
pgm: $@.c
cc -o $@ $@.c -W1,-Qdepsfile -W1,-q$@
FILES
/lib/lib*.a Libraries.
/usr/lib/lib*.a Libraries.
a.out Output file.
RELATED INFORMATION
See the following commands: "ar," "as," "cc," and "shlib2."
See the a.out file in AIX Operating System Technical Reference.
See the discussion of the ld in AIX Operating System Programming Tools and
Interfaces.
Processed November 8, 1990 LD(1,C) 6