ld(1) General Commands Manual ld(1)
Name
ld, uld - RISC link editor and ucode link editor
Syntax
ld[ options ] [ filename filename ... ]
uld[ options ] [ filename filename ... ]
Description
The invokes the RISC link editor, which links RISC extended coff object files. The archive format understood by is the one created by the
archiver
The editor combines several object files into one, performs relocation, resolves external symbols, and supports symbol table information
for symbolic debugging. In the simplest case, you specify the names of several object files as arguments to the command. The command com-
bines them, producing an object module that you can execute or use as input to a subsequent command. (In the latter case, you must specify
the -r option to preserve the relocation entries.) The command writes its output to a file named By default, this file is executable if no
errors occurred during the load.
The command concatenates object files in the order in which you specify them. The entry point of the output is the beginning of the text
segment (unless you specify the -e option).
The command combines several ucode object files and libraries into one ucode object file. The command hides external symbols for better
optimizations by subsequent compiler passes. The command uses the symbol tables of coff object files loaded with ucode object files to
determine what external symbols not to hide. You can specify that the command not hide external symbols by creating a file that describes
those symbols.
The link editors and accept object files targeted for either Big Endian or Little Endian byte ordering with their headers and symbolic
tables in any byte ordering. However and 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 cannot be changed.
If you specify that you want to link a library, the and commands search the library exactly once at the point it is encountered in the
argument list. The library (archive) symbol table (see is a hash table that and search to resolve external references. The commands load
only those routines that define unresolved external references. The order of the routines in the library is unimportant.
By default, the and commands search for libraries in the and directories. In some cases, the target byte ordering of the object files or
is loading is the opposite of the byte ordering of the machine on which the link editor is executing. When this case occurs, the link edi-
tor changes the default directories it searches for libraries. If the object file's byte ordering is Big Endian and the machine's byte
ordering is Little Endian (Digital products), the link editor searches the and directories, by default. Conversely, if the object file's
byte ordering is Little Endian and the machine's byte ordering is Big Endian, the editor searches the and directories, by default.
The following symbols are reserved; do not define them: etext, edata, end, _ftext, _fdata, _fbss, _gp, _procedure_table, _procedure_ta-
ble_size, and _procedure_string_table. These loader defined symbols, if referred to, have their values set as described in
Options
You can use the following options on both the and command lines. If you specify an option that the command does not use, the command
ignores that option.
You can specify the options described in this section on the command line. To do so, prepend a k to the option. When you prepend a k , the
command ignores the option and passes it to the link editor. The link editor ignores the prepended k and processes the option normally.
Therefore, the -kA option has the same effect as specifying -A .
-A file Link to allow incremental loading. The link editor performs the link process so that the resulting object can be read into
an already executing program.
The file argument is the name of an object file. The link editor defines additional symbols using the symbol table in that
file. This argument must appear on the command line before any other object file.
During an incremental load, the link editor loads only newly linked material into the text and data portions of a.out. How-
ever, the new symbol table reflects every symbol defined before and after the incremental load.
You can use the -T option to cause the link editor to assume that the newly linked segment starts at the specified address,
which must be a correct multiple for the resulting object type. The default resulting object type is an OMAGIC file. The
default starting address of the text is the value of the end symbol rounded to SCNROUND as defined in the include file By
default, when the newly linked segment is read into an already executing program the initial value of the break must also be
rounded.
All objects except the argument to the -A option must be compiled with the -G 0 option. Using the -A option sets -G 0 for
linking.
For jump instructions to operate correctly, the beginning and ending points of the instruction must be in the same 256
megabyte segment. Thus, it is invalid to use the default address of a ZMAGIC file as the base file and allow the newly
linked text to start at the value of the end symbol.
To solve this problem, use the -D option when you create the base file. Using this option ensures that the text and data
will be in the same 256 megabyte segment. Alternatively, use the -N option, which places the data section immediately fol-
lowing the text section.
-B num Set the bss segment origin. The argument num is a hexadecimal address. You can use this option only if the final object is
an OMAGIC file.
-Bstring Append string to the library name created for the -lx or -klx options. When searching for a library, the link editor first
appends string to the library name. If the link editor cannot find a library of that name, it searches for the library name
without string.
-b Do not merge the symbolic information entries for the same file into one entry for that file. Use this option when the sym-
bolic information from the same file appears differently in any of the objects to be linked. This situation can occur when
object files are compiled, by means of conditional compilation, with an apparently different version of an include file.
-bestGnum Calculate the best number to use as an argument to the -G option. Use this option when you are compiling and linking the
files that will produce the objects you want to link with -G. Using too large a number with the -G option may cause the
global pointer data area to overflow; using too small a number may reduce your program's execution speed.
-count
-countall
-nocount Count (or do not count) the specified objects as able to be recompiled when calculating the best number to use as an argu-
ment to the -G option. By default, the -bestGnum option assumes you can recompile everything with the -G option. If you
cannot 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 number for the -G option.
The -nocount option specifies that object files appearing after it on the command line cannot be recompiled. The -count
option specifies that object files appearing after it on the command line can be recompiled. You can alternate the use of
-nocount and -count. The -countall option specifies that all object files appearing after it on the command line can be
recompiled. This option overrides any -nocount options that appear after it on the command line.
-D num Set the data segment origin. The argument num is a hexadecimal address. See Restrictions for information on valid values
for the hexadecimal address.
-d Force definition of common storage and define loader defined symbols even if -r is present.
-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.
-e epsym Set the default entry point address for the output file to be that of the symbol epsym.
-F Load the process on demand from the resulting executable file (413 format) rather than preloading it as a ZMAGIC file. This
behavior is the default. (This option is identical to the -z option.)
-ffill Set the fill pattern for ``holes'' within an output section. The argument fill is a 4-byte hexadecimal constant.
-Gnum Assume the decimal number num specifies 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 largest size is 8 bytes.
-g
-g[123] Disable the -jmpopt option. The -g0 option is accepted, but it has no effect.
-jmpopt
-nojmpopt Fill or do not fill the delay slots of jump instructions with the target of the jump and adjust the jump offset to jump past
that instruction. This feature always is disabled 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.
-klx Search a ucode object library libx.b, where x is a string. Because the link editor searches the library when it encounters
the library name, the placement of the -kl option is significant.
-L Ignore the libx.a or libx.b default directories when searching for libraries. This option is useful when you never want the
link editor to search the default directories and want it to only search the directories you specify with the -Ldir option.
-Ldir Search dir before searching the default directories libx.a or libx.b This option is effective only if it precedes the -l
option.
-lx Search a library libx.a, where x is a string. Because the link editor searches the library when it encounters the library
name, the placement of the -l option is significant.
-M Produce a primitive load map, listing the names of the files that are loaded. This option displays a map that resembles a
UNIX 4.3BSD map. (See also the -m option.)
-m Display a map or listing of the input/output sections on standard output. This option displays a map that resembles a UNIX
System V map. (See also the -M option.)
-N Assign the 0407 magic number to the output file, making it an OMAGIC file. In an OMAGIC file, the data section immediately
follows the text section. The text section can be read or written, but it is not shareable for users executing the OMAGIC
file.
-n Assign 0419 magic number to the output file, making it an NMAGIC file. When users execute the NMAGIC file, the text section
of the executable is read-only and shared among all users executing that file. This option moves the data section up to the
first possible page-size byte boundary following the end of the text.
-o outfile Produce an output object file by the name outfile. The name of the default object file is a.out.
-p file Preserve (do not hide) the symbol names listed in file when loading ucode object files. You must separate the symbol names
in the file with blanks, tabs, or newline characters.
-r Retain relocation entries in the output file. Relocation entries must be saved if the output file is to become an input
file in a subsequent run. This option also prevents final definitions from being given to common symbols and suppresses the
undefined symbol diagnostics.
-S Set silent mode and suppress nonfatal errors.
-s Strip the symbolic information from the output object file.
-T num Set the text segment origin. The argument num is a hexadecimal address. See Restrictions for information on valid values
for the hexadecimal address.
-u symname Enter symname as an undefined symbol in the symbol table. This option is useful for loading linked material entirely from a
library because initially the symbol table is empty. An unresolved reference is needed to force the loading of the first
routine.
-V Display a message giving information about the version of being used.
-VS num Use num as the decimal version stamp to identify the file that is produced. The version stamp is stored in the optional and
symbolic headers.
-v Set verbose mode, which causes the link editor to display the name of each file as it is processed.
-x Do not preserve local (nonglobal) symbols in the output symbol table; enter only external and static symbols. This option
saves space in the output file.
-ysym Display the name of each file in which the specified symbol appears, the symbol's data type, and whether the file defines or
references the symbol. You can specify a number of -y options to trace many symbols.
-z Load the process on demand from the resulting executable file (413 format) rather than preloading it as a ZMAGIC file. This
behavior is the default. (This option is identical to the -F option.)
Restrictions
The text and data segments must not overlap and all addresses must be less than 0x80000000. The stack starts below 0x80000000 and grows
through lower addresses, so leave space for it.
For ZMAGIC and NMAGIC files, the default text segment address is 0x00400000 and the default data segment address is 0x10000000. For OMAGIC
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.
If you use the -B option when you link an OMAGIC file, the origin you specify for the bss segment must follow the data segment. If the bss
segment does not follow the data segment, the OMAGIC file will not run.
The segments must be on 4 megabyte boundaries. Objects linked at addresses other than the default will not run.
Files
Library file
Library file
Library file
Output file
See Also
cc(1), as(1), ar(1), end(3)
RISC ld(1)