LD(1) RISC/os Reference Manual LD(1)
NAME
ld - MIPS link editor
uld - ucode link editor
SYNOPSIS
ld [ option ] ... file ...
uld [ option ] ... file ...
DESCRIPTION
ld, the MIPS link editor, runs on MIPS machines under
RICS/os. 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, builds tables
and relocation information for run-time linkage in case of
doing shared link, 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 a dynamic
executable if no errors occurred during 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. There are
two kinds of libraries, archives and dynamic shared objects.
Archives are used if the output is to be static. In that
case, only those routines defining an unresolved external
reference are loaded. Shared objects are normally used if
the output is to be dynamic. In that case, only the name is
used for external resolution, no object is included as part
of the output object file. Note that any symbol remaining
unresolved are not consider an error when the linkage is to
be shared or dynamic. 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.
Printed 11/19/92 Page 1
LD(1) RISC/os Reference Manual LD(1)
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.
When searching for libraries the default directories
searched are /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 target byte ordering
of the objects being loaded.
The symbols `etext', `edata', `end', `_ftext', `_fdata',
`_fbss', `_gp', `.fini`, `.data`, `.text`, `.init`,
`.rdata`, `.sdata`, `.sbss`, `.bss`,
`.lit4`, `.lit8`, `.comment`, `__istart`, `__fstart`,
'data_init_table', `_DYNAMIC`, `_DYNAMIC_LINK`,
`_BASE_ADDRESS`, `_GOT_OFFSET`, `_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 symbols.
-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.{so,a}, where x is a string. A
library, shared object or an archive 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.{so,a} or
libx.b to look in dir before looking in the default
directories. This option is effective only if it pre-
cedes the -l options on the command line.
-L Change the algorithm of searching for libx.{so,a} or
libx.b to never look in the default directories. This
is useful when the default directories for libraries
should not be searched and only the directories
Page 2 Printed 11/19/92
LD(1) RISC/os Reference Manual LD(1)
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.
-K [fpe,mau,sd,sz,PIC]
These options are currently ignored.
-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
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.
Printed 11/19/92 Page 3
LD(1) RISC/os Reference Manual LD(1)
-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. The default
text segment address is 0x00400000 and the default data
segment address is 0x10000000.
-nN 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.
-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.
Page 4 Printed 11/19/92
LD(1) RISC/os Reference Manual LD(1)
-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
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.
Printed 11/19/92 Page 5
LD(1) RISC/os Reference Manual LD(1)
-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
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.
Page 6 Printed 11/19/92
LD(1) RISC/os Reference Manual LD(1)
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.
-elf Produce ELF output object file.
-nonshared
Produce a static executable. The output object created
will not use any shared objects during execution.
-shared
Produce a shared object. This includes creating all of
the tables for run-time linking and resolving refer-
ences to other specified shared objects. The object
created may be used by the linker to make dynamic exe-
cutables.
-callshared
Produce a dynamic executable. The object created may
use shared objects at run-time. This is the defaults.
-hiddensymbol symbol
Used for shared linkage. The linker turns the symbol
following this flag into a local.
-hidden
Turns all external symbols from objects following this
flag into locals. This option is meaningful for shared
linkage only.
-nopreempt
Truns all relocation the objects following this flag
into local relocations. Effectively disallowing
preempting externals in those objects for this ececut-
able or shared object.
Printed 11/19/92 Page 7
LD(1) RISC/os Reference Manual LD(1)
-nopreemptsymbol symbol
Turns all relocations for the symbol following this
flag into local relocations. Effectively disallowing
preemption of this external for this executable or
shared object.
-all Link in all of the objects from the archive following
this flag. This option is used in conjunction with
-shared option to create a shared object.
-none
Turns off B -all
-exclude object
Used in conjunction with -all and -shared. The object
specified will be excluded in making the shared object.
-noarchive
Requires that -l references must resolve to shared
objects. Normally, if the shared object as specified by
the -l is not found, the linker to resolve undefines.
This option disallow using those archives.
-transitivelink
The linker will link in any object that occurs in the
dependency list in addition to those in the link line.
If it cannot find the object from the dependency list,
it will cause a fatal error.
-checkregistrylocation_file
Check the location of this shared object's segments and
make sure they stay out of the way of others in the
location_file. Multiple instances of this option are
allowed. This option is used with -shared.
-updateregistrylocation_file
Register the location of this shared object's segments
and make sure they stay out of the way of others in the
location_file. Location_file is updated if it is writ-
able. This option is used with -shared.
-exactversion
Set the LL_EXACT_MATCH flag in .liblist flags field.
This indicates to rld that this shared object must
match the timestamp and checksum from the .liblist sec-
tion in addition to the interface version.
-ignoreversion
Sets the LL_IGNORE_VERSION flag in the liblist flags
field. For subsequent shared objects in the liblist.
rld will not try to match the interface version as
specified at linktime.
Page 8 Printed 11/19/92
LD(1) RISC/os Reference Manual LD(1)
-nolibraryreplacement
Turns on a flag in the dynamic section so that rld does
not allow exectime or tuntime changing of the path
(except for super user) to find the shared objects.
Typically, used for security purposes on system utili-
ties.
-rpath
Sets the rpath (see the generic abi ) to the specified
string. Menaingful only for shared linkage.
-sonameshared_object_name
Sets DT_SONAME for a shared object. Use in conjunction
with -shared option. The name may be a single component
name (e.g. libc.a), a full (starting with a slash), or
relcative pathname (containing a slash). Single com-
ponent name use rpath, LD_LIBRARY_PATH and the default
paths to resolve their locations.
-init symbol
Add a call to function name in the .init section
-fini symbol
Add a call to function name in the .fini section
-ROMaddress
This option is for embedded systems applications. Ld
will generate a table of entries of the form: from
address, to address and number of bytes (totalling 3
words per entry). A predefined symbol data_init_table
will be set by ld to point to the beginning of this
table. The last entry of this table is a negative value
and should be interpreted as the start address of bss
segment, size of bss segment and initial value of gp.
To use this option properly, user code must exist to
copy data from ROM to RAM upon program start.zed) is
defined in place of the default SYSTYPESYSV.
FILES
/lib/lib*.{so, a}
/usr/lib/lib*.{so, a}
/usr/local/lib/lib*.{so, a}
libraries
a.out output file
SEE ALSO
as(1), ar(1), cc(1), cobol(1), f77(1), pc(1), pl1(1).
NOTES
Any of the three types of objects can be run on RISC/os sys-
tems. The segments must not overlap and all addresses must
be less than 0x80000000. The stack starts below 0x80000000
Printed 11/19/92 Page 9
LD(1) RISC/os Reference Manual LD(1)
and grows through lower addresses so space should be left
for it. For ZMAGIC and NMAGIC files the default text seg-
ment 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 follow-
ing 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.
Page 10 Printed 11/19/92