ld(1) — Commands
Digital
NAME
ld − link editor
uld − ucode link editor
SYNOPSIS
ld [ option ] ... file ...
uld [ option ] ... file ...
DESCRIPTION
ld, the link editor links extended coff object files. The archive format understood by ld is the one created by the archiver ar(1).
The ld command combines several object files into one, performs 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 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. 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 object files 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 important. See lorder(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 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.
When searching for libraries the default directories searched are /usr/shlib, /usr/ccs/lib, /usr/lib/cmplrs/cc, /usr/lib, and /usr/local/lib.
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 precedes 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 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 (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 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 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 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 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 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 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 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
This option specifies incremental loading, i.e. 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 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 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 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 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.
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 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.
−non_shared
Produce a static executable. The output object created will not use any shared objects during execution. The −init and/or the −fini switches cannot be used in combination with the −non_shared switch. This option is primarily used to provide UNIX compilation environments other than the native compilation environment.
−shared
Produce a shared object. This includes creating all of the tables for run-time linking and resolving references to other specified shared objects. The object created may be used by the linker to make dynamic executables.
−call_shared
Produce a dynamic executable. The object created may use shared objects at run-time. This is the default.
−coff Creates a COFF format output file. This is the default.
−elf Creates an ELF format file. This option cannot be used with the −r option.
−package name
All defined symbols beyond this point are put into the package -name. This option is useful in conjunction with the -shared option when building a shared library.
−hidden_symbol symbol
Used for shared linkage. The linker turns the symbol following this flag into a local. This must appear before the symbol is used or defined.
−hidden
Turns all external symbols from objects following this flag into locals. This option is meaningful for shared linkage only.
−export_symbol
Turns off the hidden option for a single symbol.
−all Link in all of the objects from the archives following this flag. This option is used in conjunction with −shared option to create a shared object.
−none
Turns off the −all option.
−exclude object
Used in conjunction with −all and −shared. The object specified will be excluded in making the shared object.
−no_archive
Requires that −l references must resolve to shared objects. Normally, if the shared object as specified by the −l is not found, the linker attempts to find the corresponding archive to resolve undefines. This option disallow using those archives.
−transitive_link
The linker will link in any object which occur 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.
−check_registry location_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.
−update_registry location_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 writable. This option is used with −shared.
−soname shared_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 relative pathname (containing a slash).
−init symbol
Add a call to function name in the .init section
−fini symbol
Add a call to function name in the .fini section
−ROM address
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. SYSTYPE_SYSV.
NOTES
Any of the three types of objects can be run on DEC OSF/1 systems. 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.
FILES
/usr/shlib/lib∗.so shared libraries
/usr/ccs/lib/∗ libraries, include files, and other files
/usr/lib/complrs/cc/∗ compiler executable files
/usr/lib directory
/usr/local/lib directory
a.out output file