*** UNIX MANUAL PAGE BROWSER ***

ld(1old) ld(1old) NAME ld, uld - link editor and ucode link editor (outdated) SYNOPSIS ld [ option ... ] file ... uld [ option ... ] file ... DESCRIPTION Note This manpage is outdated. It is being retained only for the purpose of documenting the uld linker. This manpage will not be updated to reflect changes to the ld linker. It should be referenced only for information on the uld linker. For documentation on the ld linker, see ld(1). The ld command invokes the DIGITAL UNIX link editor ("linker") which links extended COFF object files. The ld command combines several object files into one, performs reloca- tion, resolves external symbols, builds tables and relocation informa- tion for run-time linkage in case of doing a shared link, and supports symbol table information for symbolic debugging. In the simplest case, the names of several object files are specified on the command line. The ld command combines them, producing an object module that can be executed or used as input by a subsequent ld command. (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 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 opti- mizations by subsequent compiler passes. The symbol tables of COFF ob- ject 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 li- braries, 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. The archive symbol table (see ar(1)) is searched to resolve external references that can be sat- isfied by archive library members. The ordering of library members is important (see lorder(1)). Shared objects are normally used if the output is to be dynamic. In that case, only the name is used for ex- ternal resolution; no object is included as part of the output object file. All 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 (through compiler drivers) to both link editors. Position-sensitive options affect link behavior for objects and li- braries that follow the option in the command. These options include -L, -all, -exclude, -exported_symbol, -hidden, -hidden_symbol, -kl, -l, -none, -non_hidden, -no_archive, -no_so, and -so_archive. They are de- scribed in detail in the Flags section in this reference page. The symbols _etext, _edata, _end, _ftext, _fdata, _fbss, _gp, __fstart, data_init_table, _DYNAMIC, _DYNAMIC_LINK, _BASE_ADDRESS, _GOT_OFFSET, _procedure_tabl, _procedure_table_size, _procedure_string_table, _cobol_main, and _unwind are reserved. If the -std1 flag is not set (see the cc(1) reference page), the symbols etext, edata, end, and un- wind are also reserved. These linker-defined symbols, if referred to, are set to the values described in end(3). Undefined results may occur if user code defines any of these symbols. Symbol names that start with __init_ and __fini_ have special meaning to the linker: All routines that start with __init_ are treated, by de- fault, as initialization routines. These are routines that are called without an argument when the file that contains them is loaded or when the program that contains them is started. All routines that start with __fini_ are treated by default as termination routines, which are routines that are called without an argument when the file that con- tains them is unloaded or when the program that contains them exits. Any executable program that references the builtin symbol _fpdata_size (either directly or through a shared object) and all shared objects, regardless of whether they reference the builtin symbol, causes the linker to generate and include code and data to support exception han- dling. For shared objects, this is always done because the programmer creating the shared object might not know whether the program referenc- ing the shared object uses exception handling. This support is needed so that the exception handling system can unwind stack frames and find handlers for exceptions (see exception_intro(3)). Exception support consists of the following: Generating data structures that the exception system can use to perform unwinds Generating .init and .fini section calls to register the exception data structures within the exception system Linking libexc_init.a, which contains a set of bridge routines that call the exception system registration routines The libc library has a set of dummy routines that replace the exception routines when the exception system is not present. By default, this replacement works because libc is generally specified last on the link line. The cc(1) command ensures that libc is the last library on the command line unless otherwise specified. Users requiring the exception system must not explicitly specify libc before libexc on the command line. FLAGS When searching for libraries, ld looks for them, by default, in the following directories in the order shown: /usr/shlib /usr/ccs/lib /usr/lib/cmplrs/cc /usr/lib /usr/local/lib /var/shlib You can use the following position-dependent qualifiers to alter the ld command's library directory search order for all libraries subsequently referenced on the command line. Note that any of these options is ef- fective only if it precedes the -l option on the command line for the libraries it is meant to affect. Change the library directory search order for shared object and archive libraries (libx.{so|a}) and ucode object libraries (libx.b) so that ld looks for them in dir before look- ing in the default library directories. Change the library directory search order for shared object and archive libraries (libx.{so|a}) and ucode object libraries (libx.b) so that ld never looks for them in the default library directories. Use this option when the default library directories should not be searched and only the directories specified by -Ldir are to be searched. Eliminate the search of the default li- brary directories and instead cause ld to search the single directory dir. Instead of using this option, which is intended exclusively for the compiler driver, you should use the -L and -Ldir options in combi- nation to obtain a similar effect. When linking a shared object, ld searches all library directories for the shared object library (libx.so). If it cannot find the shared ob- ject library, it again searches all library directories for the archive library (libx.a). You use the following switches to alter the manner in which ld searches library directories for shared object and archive libraries and the manner in which ld establishes the order of initialization routines in the image: Cause ld to search each library directory, first for the shared object library (libx.so) and then for the archive library (libx.a). Request that the execution order of init routines match the link order of the objects and archive libraries from which the routines are loaded. This ordering might not match the execution order used when archive libraries are replaced with shared libraries. Reverse the execution order of init routines. This option does not affect init routines identified by the -init option; nor does it affect fini rou- tines. This option also does not change the relative order of groups of init routines linked in from archive libraries, but it does affect the relative order of init routines within those groups. The library search can be restricted to shared libraries by the -no_archive option or to archive libraries by the -no_so option. The -so_archive option removes either of these search restrictions. When linking a ucode object library, ld searches the library directo- ries for libx.b. Use the following position-dependent qualifiers to determine which li- braries ld searches for in the library directories when resolving sym- bol names. The order of these options is significant because ld searches for a shared object or archive library (or ucode object li- brary) when it encounters its name on the command line. Search a li- brary, libx.{so|a}, where x is a string. This option is identical to the -lx option in usage and behavior except for the following differ- ence: if the library specified by -qlx is not found, the linker does not produce error or warning messages. However, the linker reports un- resolved symbol errors and other link-time errors normally. Search a ucode object library, libx.b, where x is a string. In all other re- spects, this option is the same as the -lx option. The ld command also accepts the following options: Direct the linker to read the contents of file filename as if the contents had been supplied on the command line. Inside file filename, lines ending with \ are treated as contin- uation lines, and lines starting with # are treated as comment lines and ignored. The -v flag can be used to display the ex- pansion of files specified in a -input file. The files can be nested up to 20 levels. Produce an output object file with the name outfile. The name of the default object file is a.out. Preserve (not "hides") the symbol names listed in file when loading ucode object files. The symbol names in the file are separated by blanks, tabs, or newlines. Strip the symbolic in- formation from the output object file. Do not preserve local (non-.globl) symbols in the output symbol table; enter external and static symbols only. This option reduces the size of the output file. Retain relocation entries in the output file. Re- location 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 sup- presses "undefined symbol" diagnostics. Force definition of common storage and define linker-defined symbols even if -r is present. Force definition of common storage. (Linker-defined symbols are not defined.) Enter symname in the symbol table as an undefined symbol. This is useful for loading entirely from a library because the symbol table is initially empty and an unre- solved reference is needed to force the loading of the first routine. Create a ZMAGIC (demand paged) output file. Text and data segments are aligned on page boundaries and their sizes are a multiple of the page size. This is the default. Produce an msym table for a dynamic executable or shared object. This ta- ble contains additional dynamic symbol information. If an exe- cutable or shared library is built without an msym table, the loader creates one each time the executable or shared library is loaded. Use of the -msym option causes the linker to create the msym table, thus reducing load time and the amount of dynamic memory allocated by the loader. Unlike the loader-generated msym tables, the linker produces msym tables that are shared be- tween processes. Create an NMAGIC (shared text) output file. Text and data segment addresses are 0x20000000 and 0x40000000 respectively. The text and data segments sizes are a multiple of the page size. Create an NMAGIC (shared text) output file. Text and data segments are aligned on page boundaries and their sizes are a multiple of the page size. The data segment immedi- ately follows the text segment in the address space. Create an OMAGIC (impure) output file. Text and data segments are aligned on 16-byte boundaries and their sizes are a 16-byte multiple. The data segment immediately follows the text segment in the ad- dress space. Set the text segment origin. The argument num is a hexadecimal number. See the Notes section for restrictions. Set the data segment origin. The argument num is a hexadecimal number. See the Notes section for restrictions. 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. Set the default entry point address for the output file to be that of the symbol epsym. Produce a map or listing of the in- put/output sections on the standard output (UNIX System V-like map). Produce a primitive load map, listing the names of the files to be loaded (UNIX 4.3BSD-like map). Set silent mode and suppress nonfatal errors. Set verbose mode. Print the name of each file as it is processed. Indicate each file in which sym appears, sym's type, and whether the file defines or references sym. To allow you to trace multiple symbols, this option can be specified many times on a command line. Print a message that provides information about the version of ld being used. 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. Set the fill pattern for "holes" within an output section. The argument fill is a four-byte hexadecimal constant. Do not merge the symbolic information entries for the same file into one entry for that file. This is needed only when the symbolic information from the same file appears differ- ently 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. Per- form additional type processing to provide improved symbolic de- bugging information. Perform incremental loading, that is, do linking in a way that allows the resulting object to 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 mater- ial will be entered into the text and data portions of a.out, but the new symbol table will reflect every symbol defined be- fore and after the incremental load. This argument must appear before any other object file in the argument list. The -T option can 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 pro- gram, the initial value of the program break (see brk(2)) must also be rounded. Produce a static executable. The output ob- ject created will not use any shared objects during execution. The -init and -fini switches cannot be used in combination with the -non_shared switch. This is the default. Disable the auto- matic recognition of symbols prefixed with __init_ as initial- ization routines as well as disabling the automatic recognition of symbols prefixed with __fini_ as termination routines. This option is only for applications that already have defined sym- bols with the prefixes __init_ or __fini_. Produce a shared ob- ject. This includes creating all of the tables for run-time linking and resolving references to other specified shared ob- jects. The object created may be used by the linker to produce dynamic executables. Produce a dynamic executable. The object created may use shared objects at run time. Convert the symbol following this flag into a local symbol. This flag is position independent. (Used for shared linkage only.) Convert all ex- ternal symbols from objects following this flag into local sym- bols. (Used for shared linkage only.) Turn off the -hidden op- tion. To turn off the -hidden option for a single symbol, use the -exported_symbol option. Turn off the -hidden option for a single symbol, specified by pattern. Pattern matching uses shell wildcard characters (?, *, [, ]). For more information, see sh(1). Ignore any unresolved symbols matching pattern. Such symbols are not displayed and are not treated as errors or warnings. You can enter this option multiple times on a command line. The patterns use shell wildcard characters (?, *, [, ]). The wildcard characters must be properly quoted to prevent them from being expanded by the shell. For more information, see sh(1). Produce a warning message when unresolved symbols are encountered, except for those matching -expect_unresolved. This is the default behavior for building shared libraries. Produce an error message and cause the link to fail when unresolved sym- bols are encountered, except for those matching -expect_unre- solved. This is the default behavior for linking executable pro- grams. Link in all of the objects from the archives following this flag. This option is used in conjunction with the -shared option to create a shared object. Turn off the -all option. Exclude the specified object from the shared object being cre- ated by the linker. Used in conjunction with -all and -shared. Require -l references to 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 un- defined symbols. This option disallows using those archives. Note that this option is positional and can be used more than once on a command line. It affects only those options that fol- low it, and it is turned off by the next occurrence of a -no_so or -so_archive option. Require -l references to resolve to archive libraries. Note that this option is positional and can be used more than once on a command line. It affects only those options that follow it, and it is turned off by the next occur- rence of a -no_archive or -so_archive option. Turn off either the -no_archive or -no_so options allowing -l references to re- solve to either shared objects or archive libraries in shared or call_shared links. Check the location of this shared object's segments and make sure they stay out of the way of other ob- ject's segments in the location_file. Multiple instances of this option are allowed. This option is used with -shared. 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. Set a flag in the dynamic section of the output object so that rld does not allow exec-time or run-time changing of the path (except for super user) to find the shared objects. Typically, the option is used by system utilities for security purposes. Create an rpath record containing the specified path string. The path string is a colon-separated list of directo- ries that is meaningful only when creating an executable with shared linkage. If an item in the path supplied to -rpath is of the form $VARNAME or ${VARNAME}, the linker interprets it as an environment variable. Additional rpath directories found in shared objects on the link command line are appended to path. Duplicate entries are ex- cluded. The loader uses the rpath record to search for shared libraries at run time. Set DT_SONAME for a shared object. The name can be a single component name (for example, libc.a), a full pathname (starting with a slash), or a relative pathname (containing a slash). The default DT_SONAME used for shared ob- jects is the filename component of the output file name. Spec- ify the output file name using the -o option as described pre- viously. Used in conjunction with -shared option. Make the procedure represented by the symbol into an initialization rou- tine. An initialization routine is a routine that is called without an argument when either the file that contains the rou- tine is loaded or the program that contains the routine is started. Make the procedure represented by the symbol into a termination routine. A termination routine is a routine that is called without an argument when either the file that contains the routine is unloaded or the program that contains the routine exits. Cause ld to link in any shared object that occurs in the dependency list in addition to those shared objects on the link command line. If ld cannot find the shared object in the depen- dency list, it will cause a fatal error. Turn off all code op- timizations performed by the linker. This is the default. Turn on the code optimizations that can be performed quickly with little additional time and memory overhead during the link. Note that cc(1) passes -O1 as the default when linking. Turn on all code optimizations that can be performed by the linker. Set a flag in the dynamic section of the object produced by the linker. The flag directs the loader to ensure that the shared libraries used by this dynamic object at run time match the shared libraries referenced at link time. By default, a shared library's version is included in the match test. This option requires a stricter test that includes shared library checksums and timestamps. This option is used when building a dynamic executable file (with -call_shared) or a shared library (with -shared). Estab- lish the version identifier (or identifiers) associated with a shared library. The string version-string is either a single version identifier or a colon-separated list of version identi- fiers. No restrictions are placed on the names of version iden- tifiers; however, it is highly recommended that UNIX directory naming conventions be followed. If a shared library is built with this option, any executable built against it will record a dependency on the specified ver- sion or, if a list of version identifiers is specified, the rightmost version specified in the list. If a shared library is built with a list of version identifiers, the loader will allow any executable to run that has a shared library dependency on any of the listed versions. This option is only useful when building a shared library (with -shared). Set a flag in the dynamic section in output objects requesting a depth_first, ring_search method for resolving sym- bol references between shared objects. See loader(5) for a com- plete description of this alternate symbol resolution policy. This option is used in conjunction with -call_shared. Direct the linker to load the executable in the lower 31-bit address- able virtual address range. The -T and -D options to the ld(1) command can also be used to ensure that the text and data seg- ments addresses, respectively, are loaded into low memory. The -taso option, however, in addition to setting default addresses for text and data segments, also causes shared libraries linked outside the 31-bit address space to be appropriately relocated by the loader. If you specify -taso and also specify text and data segment addresses with -T and -D, those addresses override the -taso default addresses. The -taso flag can be helpful when porting programs that assume address values can be stored in 32-bit variables (that is, programs that assume that pointers are the same length as int variables). Generates an OMAGIC file suitable for input to the om post-link optimizer. This flag should be used only with the cc command. OBJECT AND LIBRARY ORDERING The ordering of object files, archive libraries, and shared libraries on the command line affects how symbols are resolved. For example, if an archive library appears before an object file or shared library that references one of its symbols, the linker may report that symbol as un- resolved. Unresolved symbol errors can be avoided by adhering to the following suggestions: Object files should be ordered before all archive li- braries and shared libraries. If archives and shared libraries cannot be specified in dependency order, shared libraries should be ordered before archive libraries. If necessary, archives can be specified more than once on the ld command line to handle unresolved symbols that were encountered after previous symbol-resolution passes through the archives. Symbols defined in object files are always included in the output ob- ject. Ordering object files first might prevent the inclusion of con- flicting symbols that are also defined in archive libraries or shared libraries specified on the ld command line. As each object, archive library, and shared library is processed by the linker, new symbol definitions and references are added to the output object. If a symbol reference is added for a symbol that does not yet have an associated symbol definition, it is an "undefined" symbol. The linker must find a definition of every undefined symbol. The defini- tion must exist in either an object, archive, or shared library speci- fied on the command line. Archives and shared libraries are processed in the following ways: When the linker processes an archive library, it extracts objects from the archive that define any symbols that are cur- rently undefined. As each object is extracted from an archive library, the linker processes the object, identifies any additional undefined symbols, and extracts the objects that define those symbols. When the linker processes a shared library, it extracts symbol definitions from the shared library for symbols that are currently undefined. These symbol definitions are added to the output object. The shared library might also define many symbols that are not added to the output object. These symbols will not be considered as additional objects (archive li- braries and shared libraries) are processed; however, the linker does not report these symbols as unresolved if they are referenced in ob- jects ordered after the shared library on the command line. The linker also identifies new undefined symbols while process- ing a shared library. These undefined symbols are not added to the output object and are not reported as unresolved, but the linker does consider these undefined symbols as it processes ad- ditional objects on the command line. COMMON SYMBOL RESOLUTION A symbol's class determines how the linker will resolve it, particu- larly when there are multiple objects, archives and shared libraries on the command line that define the same symbol. In general, if the linker processes more than one object defining the same text or data symbol, it report an error indicating that the symbol is multiply de- fined. On the other hand, certain classes of symbols such as commons and allocated commons can be defined in multiple objects and libraries without causing multiple-definition errors. The linker uses symbol class, size, and command-line ordering to deter- mine which symbol definition to use in the output object. Symbols are selected according to the following precedence, in descending order: Data or text Largest allocated common Largest common Common symbols are characterized by their size and type only. These symbols are displayed as type C in nm output. Allocated common symbols are commons that have an address as well as a size and type. These symbols are displayed as type S or B in nm out- put. All other symbols are either data, text, or undefined. The linker searches archive libraries only to extract definitions for symbols that are undefined. It does not replace an existing symbol de- finition with a symbol of higher precedence extracted from an archive. The linker applies the precedences rules only when choosing between multiple symbol definitions in object files and shared libraries. NOTES Any of the three types of objects (ZMAGIC, NMAGIC, OMAGIC) can be run on DIGITAL UNIX systems. Within the objects, segments must not overlap and all addresses must be less than 0x40000000000: For ZMAGIC files, the default text segment address is 0x120000000 and the default data segment address is 0x140000000. (If -taso is specified the default ad- dresses for the text and data segments are 0x12000000 and 0x14000000, respectively.) For NMAGIC files, the default text segment address is 0x20000000 and the default data segment address is 0x40000000. For OMAGIC files, the default text segment address is 0x10000000, with the data segment following the text segment. The stack starts below the text segment and grows through lower ad- dresses, so space should be left for it. An additional constraint is that all addresses within an executable's data segment must not be any farther than 0x7fff8000 from all addresses within the text segment. For all types of files, the bss segment follows the data segment by de- fault. For OMAGIC files, the -B flag should not be used because the bss segment must always follow the data segment. For NMAGIC and ZMAGIC files, the location of the bss segment does not have any distance re- quirements. FILES shared libraries libraries, include files, and other files compiler ex- ecutable files directory directory output file RELATED INFORMATION ld(1), as(1), ar(1), cc(1), end(3), loader(5) Programmer's Guide Assembly Language Programmer's Guide delim off ld(1old)