NAME

ld, uld − link editor and ucode link editor

SYNOPSIS

ld [ option ... ] file ... 
uld [ option ... ] file ... 

DESCRIPTION

The ld command invokes the DEC OSF/1 link editor which 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 a shared link, 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 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. 

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. 

Position-sensitive options affect link behavior for objects and libraries that follow the option in the command.  These options include −L, −all, −exclude, −exported_symbol, −hidden, −hidden_symbol, −kl, −l, −none, −non_hidden, and −no_archive.  They are described in detail below. 

The symbols _etext, _edata, _end, _ftext, _fdata, _fbss, _gp, .fini, .data, .text, .init, .rdata, .sdata, .sbss, .bs, .lit4, .lit8, .comment, __istart, __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 unwind are also reserved.  These loader defined symbols if referred to, are set their values as described in end(3).  Undefined results may occur if user code defines these symbols. 

Symbol names that start with __init_ and __fini_ have special meaning to the loader.  All routines that start with __init_ are treated, by default, 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 contains 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, whether or not they reference the builtin symbol, cause ld to generate and include code and data to support exception handling.  For shared objects, this is always done because the person creating the shared object might not know whether the program referencing 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 libexc_init.a file is an object file with a .a suffix so that the −L option can be used to find it. 

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 libexc is generally specified libc 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:

     1./usr/shlib

     2./usr/ccs/lib

     3./usr/lib/cmplrs/cc

     4./usr/lib

     5./usr/local/lib

     6./var/shlib

You can alter the ld command’s library directory search order for all libraries subsequently referenced on the command line by using the following position-dependent qualifiers.  Note that any of these options is effective only if it precedes the −l option on the command line for the libraries it is meant to affect. 

−LdirChange the library directory search order for shared object and archive libraries (for instance, lib x.{so, a}), and ucode object libraries (for instance, libx.b), so that ld looks for them in dir before the default library directories. 

−LChange 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. 

−KdirEliminate the search of the default library 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 combination to obtain a similar effect. 

When linking a shared object, ld searches all library directories in order for the shared object library (libx.so).  If it cannot find the shared object library, it again searches all library directories in order for the archive library (libx.a). 

You use the following switch to alter the manner in which ld searches library directories for shared object and archive libraries:

−oldstyle_liblookup
Cause ld to search in order each library directory once, first for the shared object library (libx.so) and then for the archive library (libx.a). 

It omits the search for the archive library if the −no_archive option precedes the library name on the ld command line.  When linking a ucode object library, ld searches the library directories in order for libx.b. 

Use the following position-dependent qualifiers to determine which libraries ld searches for in the library directories when resolving symbol names.  Note that, because ld searches for a shared object or archive library (or ucode object library) when it encounters its name on the command line, the order of these options is significant. 

−lxSearch a library libx.{so, a}, where x is a string. 

−qlxThis option is identical to the −lx option in usage and behavior with this difference: if the library specified by -lx is not found, the linker does not produce error or warning messages.  However, the linker reports unresolved symbol errors and other link time errors normally. 

−klxSearch 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. 

The ld command also accepts the following options:

−o outfile
Produce an output object file by the name outfile. The name of the default object file is a.out. 

−p filePreserve (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. 

−sStrip the symbolic information from the output object file. 

−xDo 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. 

−rRetain 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. 

−dForce 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.

−nArrange (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 0x20000000 and the default data segment address is 0x40000000. 

−nNArrange (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. 

−NPlace 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. 

−mProduce a map or listing of the input/output sections on the standard output (UNIX system V-like map). 

−MProduce a primitive load map, listing the names of the files that will be loaded (UNIX 4.3bsd-like map). 

−SSet silent mode and suppress non-fatal errors. 

−vSet verbose mode.  Print the name of each file as it is processed. 

−ysymIndicate 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. 

−VPrint 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 fillSet the fill pattern for “holes” within an output section.  The argument fill is a four-byte hexadecimal constant. 

−bDo 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. 

−A fileThis 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 initial value of the break must also be rounded. 

−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 is the default. 

−noprefix_recognition
This option disables the automatic recognition of symbols prefixed with __init as initialization routines, and of symbols prefixed with __fini_ as termination routines.  This option is only for applications that already have defined symbols with the prefixes __init_ or __fini_. 

−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.

−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.

−exported_symbol pattern
Turns off the hidden option for a single symbol, specified by pattern.  Pattern matching uses shell wildcard characters (?, ∗, [, ]).  For more information, see sh(1). 

−expect_unresolved pattern
Any unresolved symbols matching pattern are not displayed and are not treated as errors or warnings.  You can enter this option multiple times.  The patterns use shell wildcard characters (?, ∗, [, ]) which must be properly quoted so they will not be expanded by the shell.  For more information, see sh(1). 

−warning_unresolved
Unresolved symbols, except those matching −expect_unresolved, produce a warning message.  This is the default behavior for building shared libraries. 

−error_unresolved
Unresolved symbols, except those matching −expect_unresolved, produce an error and the link fails.  This is the default behavior for linking executable programs. 

−allLink 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. 

−noneTurns 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 undefined symbols.  This option disallows using those archives.  Note that this option is positional and can be used more than once.  It affects only those options that follow it. 

−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. 

−no_library_replacement
Turns on a flag in the dynamic section so that rld does not allow exectime or run-time changing of the path (except for super user) to find the shared objects.  Typically, used for security purposes on system utilities.

−rpath path
Creates an rpath record containing the specified path string.  The path string is a colon-separated list of directories that is meaningful only when creating an executable with shared linkage.  Additional rpath directories found in shared objects on the link command line will be appended to path.  Duplicate entries will be excluded.  The run-time loader uses the rpath record to search for shared libraries at run time. 

−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).  The default DT_SONAME used for shared objects is the filename component of the output file name.  Specify the output file name using the -o  option as described above. 

−init symbol
Make the procedure represented by the symbol an initialization routine, which is a routine that is called without an argument when the file that contains the routine is loaded, or when the program that contains the routine is started.

−fini symbol
Make the procedure represented by the symbol a termination routine, which is a routine that is called without an argument when the file that contains the routine is unloaded, or when the program that contains the routine exits.

−transitive_link
Causes 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 dependency list, it will cause a fatal error. 

−O0Turns off all code optimizations performed by the ld.  This is the default. 

−O1Turns 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. 

−O2, −O3
Turns on all code optimizations that can be performed by the linker.

−exact_version
Sets a flag in the dynamic object produced by the linker, asking the run-time loader to ensure that the shared libraries this dynamic object uses 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 which 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). 

−set_version version-string
Establishes 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 identifiers.  No restrictions are placed on the names of version identifiers; 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 version 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 run-time 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). 

−depth_ring_search
This option is used in conjunction with −call_shared.  The linker sets a flag in dynamic objects requesting a depth_first, ring_search method for resolving symbol references between shared objects.  See loader(5) for a complete description of this alternate symbol resolution policy. 

−tasoThis option tells the linker that the executable should be loaded in the lower 31-bit addressable virtual address range.  The −T and −D options to the ld(1) command can also be used to ensure that the text and data segments 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 option is useful for porting 32-bit programs to the DEC OSF/1 operating system. 

−omGenerates 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 is ordered before an object file or shared library that references one of its symbols, the linker may report that symbol as unresolved. 

Unresolved symbol errors can be avoided by following the suggestions below:

       •Object files should be ordered before all archive libraries 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 link command line. 

Symbols defined in object files are always included in the output object.  Ordering object files first might prevent the inclusion of conflicting symbols also defined in archive libraries or shared libraries specified on the link command line. 

As each object, archive library and shared library is processed by ld, 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 each undefined symbol in an object, archive, or shared library occurring later on the command line. 

When the linker processes an archive library, it extracts objects from the archive that define any symbols that are currently undefined.  As each object is extracted from an archive library, the linker processes the object, identifies any additional “undefined” symbols, and extracts the objects which 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 libraries and shared libraries are processed; however, the linker will not report these symbols as unresolved if they are referenced in objects ordered after the shared library on the command line. 

The linker also identifies new undefined symbols while processing a shared library.  These undefined symbols are not added to the output object and are not reported as unresolved, but the linker will consider these undefined symbols as it processes additional objects on the command line. 

COMMON SYMBOL RESOLUTION

A symbol’s class determines how the linker will resolve it, particularly 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 will report an error indicating that the symbol is multiply defined.  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 determine which symbol definition to use in the output object.  Symbols are selected according to the following precedence, in descending order:

     1.Data or text

     2.Largest allocated common

     3.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 output.  All other symbols are either data, text, or undefined. 

The linker searches archive libraries only to extract symbols that are undefined.  It does not replace an existing symbol definition 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 can be run on DEC OSF/1 systems.  The segments must not overlap and all addresses must be less than 0x40000000000.  The stack starts below the text segment and grows through lower addresses so space should be left for it.  For ZMAGIC files the default text segment address is 0x120000000 and the default data segment address is 0x140000000. 

For NMAGIC files the default text segment 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 default for all types of files is that the bss segment follows the data segment. 

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. 

The bss segment has no distance requirement for NMAGIC and ZMAGIC files.  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∗.soshared libraries

/usr/ccs/lib/∗libraries, include files, and other files

/usr/lib/cmplrs/cc/∗compiler executable files

/usr/libdirectory

/usr/local/libdirectory

a.outoutput file

RELATED INFORMATION

as(1), ar(1), cc(1), end(3), loader(5)
Programmer’s Guide
Assembly Language Programmer’s Guide