ld(1) USER COMMANDS ld(1)
NAME
ld, uld - MIPS link editor/ucode link editor
SYNOPSIS
ld [ option ] ... file ...
uld [ option ] ... file ...
DESCRIPTION
Ld, the MIPS link editor, runs on MIPS machines under the
UNIX system 4.3bsd and System V. It links MIPS extended
coff object files. The archive format understood by ld is
the one created by the MIPS archiver ar(1).
The ld command combines several object files into one, pre-
forms relocation, resolves external symbols, and supports
symbol table information for symbolic debugging. In the
simplest case, the names of several object files are given.
Ld combines them, producing an object module that can be
executed or used as input for a subsequent ld run. (In the
latter case, the -r option must be given to preserve the
relocation entries.) The output of ld is left in a.out. By
default, this file is executable if no errors occurred dur-
ing the load.
The argument object files are concatenated in the order
specified. The entry point of the output is the beginning
of the text segment (unless the -e option is specified).
The uld command combines several ucode object files and
libraries into one ucode object file. It ``hides'' external
symbols for better optimizations by subsequent compiler
passes. The symbol tables of coff object files loaded with
ucode object files are used to determine what external sym-
bols not to ``hide'' along with files specified by the user
that contain lists of symbol names.
If any argument is a library, it is searched exactly once at
the point it is encountered in the argument list. Only
those routines defining an unresolved external reference are
loaded. The library (archive) symbol table (see ar(1)) is a
hash table and is searched to resolved external references
that can be satisfied by library members. The ordering of
library members is unimportant.
The following options are recognized by both ld and uld .
Those options used by one and not the other are ignored.
Any option can be preceded by a `k' (for example -ko out-
file) and except for -klx have the same meaning with or
without the preceding `k'. This is done so that these
options can be passed to both link editors through compiler
drivers.
1
ld(1) USER COMMANDS ld(1)
When searching for libraries the default directories
searched are /usr/ccs/lib, /lib/, /usr/lib/cmplrs/cc,
/usr/lib/ and /usr/local/lib/ . If the target byte ordering
of the object files being loaded is of the opposite byte
ordering of the machine the link editor is running on then
the default search directories for libraries are changed.
The change is to replace the last name of the directories
from ``lib/'' to ``libeb/'' or ``libel/'' to match the tar-
get byte ordering of the objects being loaded.
The symbols `etext', `edata', `end', `_ftext', `_fdata',
`_fbss', `_gp', `_procedure_table', `_procedure_table_size'
and `_procedure_string_table' are reserved. These loader
defined symbols if referred to, are set their values as
described in end(3). It is erroneous to define these sym-
bols.
-o outfile
Produce an output object file by the name outfile. The
name of the default object file is a.out.
-lx Search a library libx.a, where x is a string. A
library is searched when its name is encountered, so
the placement of a -l is significant.
-klx Search a library libx.b, where x is a string. These
libraries are intended to be ucode object libraries.
In all other ways, this option is like the -lx option.
-Ldir
Change the algorithm of searching for libx.a or libx.b
to look in dir before looking in the default direc-
tories. This option is effective only if it precedes
the -l options on the command line.
-L Change the algorithm of searching for libx.a or libx.b
to never look in the default directories. This is use-
ful when the default directories for libraries should
not be searched and only the directories specified by
-Ldir are to be searched.
-Kdir
Change the default directories to the single directory
dir. This option is only intended to be used by the
compiler driver. Users should use the -L and -Ldir
options to get the effect they desire.
-Bstring
Append string to the library names created for the -lx
and -klx when searching for library names. For each
directory to be searched the name is first created with
the string and if it is not found it is created without
2
ld(1) USER COMMANDS ld(1)
the string.
-p file
Preserve (don't ``hide'') the symbol names listed in
file when loading ucode object files. The symbol names
in the file are separated by blanks, tabs, or newlines.
-s Strip the symbolic information from the output object
file.
-x Do not preserve local (non-.globl) symbols in the out-
put symbol table; enter external and static symbols
only. This option saves some space in the output file.
-r Retain relocation entries in the output file. Reloca-
tion entries must be saved if the output file is to
become an input file in a subsequent ld run. This
option also prevents final definitions from being given
to common symbols, and suppresses the `undefined sym-
bol' diagnostics.
-d Force definition of common storage and define loader
defined symbols even if -r is present.
-u symname
Enter symname as an undefined in the symbol table.
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.
-F or -z
Arrange for the process to be loaded on demand from the
resulting executable file (413 format) rather than
preloaded, a ZMAGIC file. This is the default.
-n Arrange (by giving the output file a 0410 "magic
number") that when the output file is executed, the
text portion will be read-only and shared among all
users executing the file, an NMAGIC file. This
involves moving the data areas up to the first possible
pagesize byte boundary following the end of the text.
-N Place the data section immediately after the text and
do not make the text portion read only or sharable, an
OMAGIC file. (Use "magic number" 0407.)
-T num
Set the text segment origin. The argument num is a
hexadecimal number. See the notes section for restric-
tions.
3
ld(1) USER COMMANDS ld(1)
-D num
Set the data segment origin. The argument num is a
hexadecimal number. See the notes section for restric-
tions.
-B num
Set the bss segment origin. The argument num is a hex-
adecimal number. This option can be used only if the
final object is an OMAGIC file.
-e epsym
Set the default entry point address for the output file
to be that of the symbol epsym.
-m Produce a map or listing of the input/output sections
on the standard output (UNIX system V-like map).
-M Produce a primitive load map, listing the names of the
files that will be loaded (UNIX 4.3bsd-like map).
-S Set silent mode and suppress non-fatal errors.
-v Set verbose mode. Print the name of each file as it is
processed.
-ysym
Indicate each file in which sym appears, sym's type and
whether the file defines or references sym. Many such
options may be given to trace many symbols.
-V Print a message giving information about the version of
ld being used.
-VS num
Use num as the decimal version stamp to identify the
a.out file that is produced. The version stamp is
stored in the optional and symbolic headers.
-f fill
Set the fill pattern for ``holes'' within an output
section. The argument fill is a four-byte hexadecimal
constant.
-G num
The argument num is taken to be a decimal number that
is the largest size in bytes of a .comm item or literal
that is to be allocated in the small bss section for
reference off the global pointer. The default is 8
bytes.
-bestGnum
Calculate the best -G num to use when compiling and
4
ld(1) USER COMMANDS ld(1)
linking the files which produced the objects being
linked. Using too large a number with the -G num
option may cause the gp (global-pointer) data area to
overflow; using too small a number may reduce your
program's execution speed.
-count, -nocount, -countall
These options control which objects are counted as
recompilable for the best -G num calculation. By
default, the -bestGnum option assumes you can recompile
everything with a different -G num option. If you can-
not recompile certain object files or libraries
(because, for example, you have no sources for them),
use these options to tell the link editor to take this
into account in calculating the best -G num value.
-nocount says that object files appearing after it on
the command line cannot be recompiled; -count says that
object files appearing after it on the command line can
be recompiled; you can alternate the use of -nocount
and -count. -countall overrides any -nocount options
appearing after it on the command line.
-b Do not merge the symbolic information entries for the
same file into one entry for that file. This is only
needed when the symbolic information from the same file
appears differently in any of the objects to be linked.
This can occur when object files are compiled, by means
of conditional compilation, with an apparently dif-
ferent version of an include file.
-jmpopt and -nojmpopt
Fill or don't fill the delay slots of jump instructions
with the target of the jump and adjust the jump offset
to jump past that instruction. This allways is dis-
abled for debugging (when the -g1, -g2 or -g flag is
present). When this option is enabled it requires that
all of the loaded program's text be in memory and could
cause the loader to run out of memory. The default is
-nojmpopt.
-g or -g[0123]
These options are accepted and except for -g1, -g2 or
-g disabling the -jmpopt have no other effect.
-A file
This option specifies incremental loading, i.e. link-
ing is to be done in a manner so that the resulting
object may be read into an already executing program.
The next argument, file, is the name of a file whose
symbol table will be taken as a basis on which to
define additional symbols. Only newly linked material
will be entered into the text and data portions of
5
ld(1) USER COMMANDS ld(1)
a.out, but the new symbol table will reflect every sym-
bol defined before and after the incremental load.
This argument must appear before any other object file
in the argument list. The -T option may be used as
well, and will be taken to mean that the newly linked
segment will commence at the corresponding address
(which must be a correct multiple for the resulting
object type). The default resulting object type is an
OMAGIC file and the default starting address of the
text is the old value of end rounded to SCNROUND as
defined in the include file <scnhdr.h>. Using the
defaults, when this file is read into an already exe-
cuting program the intial value of the break must also
be rounded. All other objects except the argument to
the -A option must be compiled -G 0 and this sets -G 0
for linking.
The following options are used by the command mkshlib(1) and
are not intended for general use.
-c Create a target shared library object file. This is a
LIBMAGIC file (443 format). The objects linked must be
compiled with -G 0 and this sets -G 0 for linking.
This file is demand paged and the headers are part of
the text but on there own page so real text starts on
the next page where the text is loaded.
-i file
The .text section of file is moved into the .init sec-
tion of the resulting object file.
Ld and uld accept object files targeted for either byte ord-
ering with their headers and symbolic tables in any byte
ordering; however ld and uld are faster if the headers and
symbolic tables have the byte ordering of the machine that
they are running on. The default byte ordering of the
headers and symbolic tables is the target byte ordering of
the output object file. For non-relocatable object files
the default byte ordering of the headers and symbolic tables
can't be changed.
-EB Produce the output object file with big-endian byte
ordered headers and symbolic information tables.
-EL Produce the output object file with little-endian byte
ordered headers and symbolic information tables.
The option described below is primarily used to provide UNIX
compilation environments other than the native compilation
environment.
-systype name
6
ld(1) USER COMMANDS ld(1)
Use the named compilation environment name. This has
the effect of changing the standard directory for
`#include' files, the runtime libraries and where run-
time libraries are searched for. The new items are
located in their usual paths but with /name prepended
to their paths. Also a preprocessor macro of the form
SYSTYPENAME (with name capitalized) is defined in
place of the default SYSTYPESYSV.
FILES
/lib/lib*.a
/usr/lib/lib*.a
/usr/local/lib/lib*.a libraries
a.out output file
SEE ALSO
cc(1), pc(1), f77(1), as(1), ar(1)
NOTES
The segments must not overlap and all addresses must be less
than 0x80000000. The stack starts below 0x80000000 and
grows through lower addresses so space should be left for
it. For ZMAGIC and NMAGIC files the default text segment
address is 0x00400000 and the default data segment address
is 0x10000000. For OMAGIG files the default text segment
address is 0x10000000 with the data segment following the
text segment. The default for all types of files is that
the bss segment follows the data segment.
For OMAGIC files to be run under the operating system the -B
flag should not be used because the bss segment must follow
the data segment which is the default.
7