ld(1) — RISC
Name
ld, uld − RISC link editor and ucode link editor
Syntax
ld [ options ] [ file file file ...
uld options ] [ file file file ...
Description
The ld command is the RISC link editor. It links RISC extended coff object files. The archive format understood by ld is the one created by the archiver ar(.).
The ld command combines several object files into one, performs relocation, resolves external symbols, and supports symbol table information for symbolic debugging. In the simplest case, the names of several object files are given. The ld command 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 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 symbols 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())) 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.
When searching for libraries the default directories to search in are /lib/, /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 following symbols are reserved and should not be defined: etext, edata, end, _ftext, _fdata, _fbss, _gp, _procedure_table, _procedure_table_size, and _procedure_string_table. These loader defined symbols, if referred to, are set their values as described in end(.).
Options
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 outfile) 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.
−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 directories. 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 useful 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 the string.
−p file Preserve (do not 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 output 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. Relocation 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 symbol 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 is 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 restrictions.
−D num Set the data segment origin. The argument num is a hexadecimal number. See the notes section for restrictions.
−B num Set the bss segment origin. The argument num is a hexadecimal 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 are 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 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 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 −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 different version of an include file.
−jmpopt and −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 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.
−g or −g[0123]
These options are accepted and except for −g1, −g2 or −g disabling the −jmpopt have no other effect.
−A file Specifies incremental loading. For example, linking 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 is taken as a basis on which to define additional symbols. Only newly linked material is entered into the text and data portions of a.out, but the new symbol table reflects every symbol 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 is taken to mean that the newly linked segment commences 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 executing 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 option is not intended for general use.
−i file The .text section of file is moved into the .init section of the resulting object file.
The link editors ld and uld accept object files targeted for either byte ordering 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 cannot 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.
Restrictions
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 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.
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.
The segments must be on 4 megabyte boundaries. Objects linked at addresses other than the default will not run.
Files
/lib/lib*.a
/usr/lib/lib*.a
/usr/local/lib/lib*.alibraries
a.outoutput file