Query: ld
OS: sunos
Section: 1
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
ld(1) ld(1)NAMEld - link-editor for object filesSYNOPSIS/usr/ccs/bin/ld [-64] [-a | -r] [-b] [-c name] [-C] [-G] [-i] [-m] [-s] [-t] [-V] [-B direct | nodirect] [-B dynamic | static] [-B group] [-B local] [-B eliminate] [-B reduce] [-B symbolic] [-d y | n] [-D token,...] [-e epsym] [-F name | -f name] [-h name] [-I name] [-L path] [-l x] [-M mapfile] [-N string] [-o outfile] [-p auditlib] [-P auditlib] [-Q y | n] [-R path] [-S supportlib] [-u symname] [-Y P,dirlist] [-z absexec] [-z allextract | defaultextract | weakextract ] [-z combreloc] [-z defs | nodefs] [-z direct | nodirect] [-z endfiltee] [-z finiarray=function] [-z groupperm | nogroupperm] [-z ignore | record] [-z initarray=function] [-z initfirst] [-z inter- pose] [-z lazyload | nolazyload] [ -z ld32=arg1,arg2,...] [ -z ld64=arg1,arg2,...] [-z loadfltr] [-z muldefs] [-z nocompstrtab] [-z node- faultlib] [-z nodelete] [-z nodlopen] [-z nodump] [-z nopartial] [-z noversion] [-z now] [-z origin] [-z preinitarray=function] [-z redloc- sym] [-z rescan] [-z text | textwarn | textoff] [-z verbose] filename... The ld command combines relocatable object files, performs relocation, and resolves external symbols. ld operates in two modes, static or dynamic, as governed by the -d option. In all cases, the output of ld is left in a.out by default. See . In static mode, -dn, relocatable object files that are provided as arguments are combined to produce a static executable file. If the -r option is specified, relocatable object files are combined to produce one relocatable object file. See Static Executables. In dynamic mode, -dy, the default, relocatable object files that are provided as arguments are combined to produce an executable object file. This file is linked at execution with any shared object files that are provided as arguments. If the -G option is specified, relocat- able object files are combined to produce a shared object. If any argument is a library, ld by default searches the library exactly once at the point the library is encountered on the argument list. The library can be either a shared object or relocatable archive. See ar.h(3HEAD)). For an archive library, ld loads only those routines that define an unresolved external reference. ld searches the symbol table of the ar- chive library sequentially to resolve external references that can be satisfied by library members. This search is repreated until no external references can be resolved by the archive. Thus, the order of members in the library is functionally unimportant, unless multiple library members exist that define the same external symbol. Archive libraries that have interdependencies can require multiple command-line definitions, or use of the -z rescan option. A shared object consists of an indivisible, whole unit that has been generated by a previous link-edit of one or more input files. When the link-editor processes a shared object, the entire contents of the shared object become a logical part of the resulting output file image. The shared object is not physically copied during the link-edit as its actual inclusion is deferred until process execution. This logical inclusion means that all symbol entries defined in the shared object are made available to the link-editing process. No command-line option is required to distinguish 32-bit objects or 64-bit objects. The link-editor uses the ELF class of the first relo- catable object file that is found on the command line, to govern the mode in which to operate. The mixing of 32-bit objects and 64-bit objects is not permitted. See also the -64 option and the LD_NOEXEC_64 environment variable. Static Executables The creation of static executables has been discouraged for many releases. In fact, 64-bit system archive libraries have never been pro- vided. Because a static executable is built against system archive libraries, the executable contains system implementation details. This self-containment has a number of drawbacks. o The executable is immune to the benefits of system patches delivered as shared objects. The executable therefore, must be rebuilt to take advantage of many system improvements. o The ability of the executable to run on future releases can be compromised. o The duplication of system implementation details negatively affects system performance. With Solaris 10, 32-bit system archive libraries are no longer provided. Without these libraries, specifically libc.a, the creation of static executables is no longer achievable without specialized system knowledge. Note, that the link-editors capability to process static linking options, and the processing of archive libraries, remains unchanged. The following options are supported: -64 Creates a 64-bit object. By default, the class of the object being generated is determined from the first ELF object processed from the command line. This option is useful when creating an object directly with ld whose input is solely from an archive library or a map- file. See the -M option. -a In static mode only, produces an executable object file. Undefined references are not permitted. This option is the default behavior for static mode. -a can not be used with the -r option. See Static Executables under . -b In dynamic mode only, does no special processing for relocations that reference symbols in shared objects. Without the -b option, the link-editor creates special position-independent relocations for references to functions defined in shared objects. In addition, the link-editor arranges for data objects that are defined in shared objects to be copied into the memory image of an executable at run- time. The -b option is intended for specialized dynamic objects and is not recommended for general use. Its use suppresses all specialized processing required to insure an object's shareability, and can even prevent the relocation of 64-bit executables. -B direct | nodirect Options governing direct binding. -B direct establishes direct binding information by recording the relationship between each symbol reference and the dependency that provides the definition. In addition, direct binding information is established between each symbol reference and an associated definition within the object being created. The runtime linker uses this information to search directly for a symbol in the associated object rather than to carry out a default symbol search. Direct binding information can only be established to dependencies specified with the link-edit. Thus, you should use the -z defs option. Objects that wish to interpose on symbols in a direct binding environment should identify themselves as interposers with the -z interpose option. The use of -B direct enables -z lazyload for all dependencies. -B nodirect prevents any direct binding to the interfaces offered by the object being created. The object being created can continue to directly bind to external interfaces by specifying the -z direct option. -B dynamic | static Options governing library inclusion. -B dynamic is valid in dynamic mode only. These options can be specified any number of times on the command line as toggles: if the -B static option is given, no shared objects are accepted until -B dynamic is seen. See also the -l option. -B eliminate Causes any global symbols, not assigned to a version definition, to be eliminated from the symbol table. Version definitions can be supplied by means of a mapfile to indicate the global symbols that should remain visible in the generated object. This option achieves the same symbol elimination as the auto-elimination directive that is available as part of a mapfile version definition. This option can be useful when combining versioned and non-versioned relocatable objects. See also the -B reduce option. -B group Establishes a shared object and its dependencies as a group. Objects within the group are bound to other members of the group at run- time. The runtime processing of an object containing this flag mimics that which occurs if the object is added to a process using dlopen(3C) with the RTLD_GROUP mode. An object that has an explicit dependency on a object identified as a group, becomes a member of the group. As the group must be self contained, use of the -B group option also asserts the -z defs option. -B local Causes any global symbols, not assigned to a version definition, to be reduced to local. Version definitions can be supplied by means of a mapfile to indicate the global symbols that should remain visible in the generated object. This option achieves the same symbol reduction as the auto-reduction directive that is available as part of a mapfile version definition. This option can be useful when combining versioned and non-versioned relocatable objects. See also the -B eliminate option. -B reduce When generating a relocatable object, causes the reduction of symbolic information defined by any version definitions. Version defini- tions can be supplied by means of a mapfile to indicate the global symbols that should remain visible in the generated object. By default, when a relocatable object is generated, version definitions are only recorded in the output image. The actual reduction of symbolic information is carried out when the object is used in the construction of a dynamic executable or shared object. This option is applied automatically when a dynamic executable, or shared object is created. -B symbolic In dynamic mode only. When building a shared object, binds references to global symbols to their definitions, if available, within the object. Normally, references to global symbols within shared objects are not bound until runtime, even if definitions are available. This model allows definitions of the same symbol in an executable or other shared object to override the object's own definition. ld issues warnings for undefined symbols unless -z defs overrides. The -B symbolic option is intended for specialized dynamic objects and is not recommended for general use. To reduce the runtime relo- cation overhead of an object, the creation of a version definition is recommended. -c name Records the configuration file name for use at runtime. Configuration files can be employed to alter default search paths, provide a directory cache, and provide alternative object dependencies. See crle(1). -C Demangles C++ symbol names displayed in diagnostic messages. -d y | n When -d y, the default, is specified, ld uses dynamic linking. When -d n is specified, ld uses static linking. See Static Executables under , and -B dynamic|static. -D token,... Prints debugging information, as specified by each token, to the standard error. The special token help indicates the full list of tokens available. -e epsym Sets the entry point address for the output file to be the symbol epsym. -f name Useful only when building a shared object. Specifies that the symbol table of the shared object is used as an auxiliary filter on the symbol table of the shared object specified by name. Multiple instances of this option are allowed. This option can not be combined with the -F option. -F name Useful only when building a shared object. Specifies that the symbol table of the shared object is used as a filter on the symbol table of the shared object specified by name. Multiple instances of this option are allowed. This option can not be combined with the -f option. -G In dynamic mode only, produces a shared object. Undefined symbols are allowed. -h name In dynamic mode only, when building a shared object, records name in the object's dynamic section. name is recorded in any dynamic objects that are linked with this object rather than the object's file system name. Accordingly, name is used by the runtime linker as the name of the shared object to search for at runtime. -i Ignores LD_LIBRARY_PATH. This option is useful when an LD_LIBRARY_PATH setting is in effect to influence the runtime library search, which would interfere with the link-editing being performed. -I name When building an executable, uses name as the path name of the interpreter to be written into the program header. The default in static mode is no interpreter. In dynamic mode, the default is the name of the runtime linker, ld.so.1(1). Either case can be overridden by -I name. exec(2) loads this interpreter when the a.out is loaded, and passes control to the interpreter rather than to the a.out directly. -l x Searches a library libx.so or libx.a, the conventional names for shared object and archive libraries, respectively. In dynamic mode, unless the -B static option is in effect, ld searches each directory specified in the library search path for a libx.so or libx.a file. The directory search stops at the first directory containing either. ld chooses the file ending in .so if -lx expands to two files with names of the form libx.so and libx.a. If no libx.so is found, then ld accepts libx.a. In static mode, or when the -B static option is in effect, ld selects only the file ending in .a. ld searches a library when the library is encountered, so the placement of -l is sig- nificant. -L path Adds path to the library search directories. ld searches for libraries first in any directories specified by the -L options and then in the standard directories. This option is useful only if the option precedes the -l options to which the -L option applies. The environ- ment variable LD_LIBRARY_PATH can be used to supplement the library search path. See LD_LIBRARY_PATH under . -m Produces a memory map or listing of the input/output sections, together with any non-fatal multiply-defined symbols, on the standard output. -M mapfile Reads mapfile as a text file of directives to ld. This option can be specified multiple times. If mapfile is a directory, then all reg- ular files, as defined by stat(2), within the directory are processed. See for a description of mapfiles. Example mapfiles are pro- vided in /usr/lib/ld. See . -N string This option causes a DT_NEEDED entry to be added to the .dynamic section of the object being built. The value of the DT_NEEDED string is the string that is specified on the command line. This option is position dependent, and the DT_NEEDED .dynamic entry is relative to the other dynamic dependencies discovered on the link-edit line. This option is useful for specifying dependencies within device driver relocatable objects when combined with the -dy and -r options. -o outfile Produces an output object file that is named outfile. The name of the default object file is a.out. -p auditlib Identifies an audit library, auditlib. This audit library is used to audit the object being created at runtime. A shared object identi- fied as requiring auditing with the -p option, has this requirement inherited by any object that specifies the shared object as a dependency. See the -P option. -P auditlib Identifies an audit library, auditlib. This audit library is used to audit the dependencies of the object being created at runtime. Dependency auditing can also be inherited from dependencies that are identified as requiring auditing. See the -p option. -Q y | n Under -Q y, an ident string is added to the .comment section of the output file. This string identifies the version of the link-editor used to create the file. This results in multiple ld idents when there have been multiple linking steps, such as when using ld -r. This identification is identical with the default action of the cc command. -Q n suppresses version identification. -r Combines relocatable object files to produce one relocatable object file. ld does not complain about unresolved references. This option cannot be used with the -a option. -R path A colon-separated list of directories used to specify library search directories to the runtime linker. If present and not NULL, the path is recorded in the output object file and passed to the runtime linker. Multiple instances of this option are concatenated together with each path separated by a colon. -s Strips symbolic information from the output file. Any debugging information, that is, .line, .debug*, and .stab* sections, and their associated relocation entries are removed. Except for relocatable files, a symbol table SHT_SYMTAB and its associated string table sec- tion are not created in the output object file. Note, the elimination of a SHT_SYMTAB symbol table can compromise the .stab* debugging information that is generate using the compiler drivers -g option. See also the -z redlocsym option. -S supportlib The shared object supportlib is loaded with the link-editor and given information regarding the linking process. Support shared objects can also be supplied using the SGS_SUPPORT environment variable. See for more details. -t Turns off the warning for multiply-defined symbols that have different sizes or different alignments. -u symname Enters symname as an undefined symbol in the symbol table. This option is useful for loading entirely from an archive library. In this instance, an unresolved reference is needed to force the loading of the first routine. The placement of this option on the command line is significant. This option must be placed before the library that defines the symbol. -V Outputs a message giving information about the version of ld being used. -Y P,dirlist Changes the default directories used for finding libraries. dirlist is a colon-separated path list. -z absexec Useful only when building a dynamic executable. Specifies that references to external absolute symbols should be resolved immediately instead of being left for resolution at runtime. In very specialized circumstances, this option removes text relocations that can result in excessive swap space demands by an executable. -z allextract | defaultextract | weakextract Alters the extraction criteria of objects from any archives that follow. By default, archive members are extracted to satisfy undefined references and to promote tentative definitions with data definitions. Weak symbol references do not trigger extraction. Under -z allextract, all archive members are extracted from the archive. Under -z weakextract, weak references trigger archive extraction. -z defaultextract provides a means of returning to the default following use of the former extract options. -z combreloc Combines multiple relocation sections. Historically, relocation sections are maintained in a one-to-one relationship with the sections to which the relocations must be applied. When building an executable or shared object, ld sorts the entries of data relocation sec- tions by their symbol reference. This sorting reduces the runtime symbol lookup. Combining multiple data relocation sections allows optimal sorting and hence the least relocation overhead when objects are loaded into memory. -z defs | nodefs The -z defs option forces a fatal error if any undefined symbols remain at the end of the link. This mode is the default when an exe- cutable is built. For historic reasons, this mode is not the default when building a shared object. Use of the -z defs option is recom- mended, as this mode assures the object being built is self-contained. A self-contained object has all symbolic references resolved internally, or to the object's immediate dependencies. The -z nodefs option allows undefined symbols. For historic reasons, this mode is the default when a shared object is built. When used with executables, the behavior of references to such undefined symbols is unspecified. Use of the -z nodefs option is not recommended -z direct | nodirect Enables or disables direct binding to any dependencies that follow on the command line. These options allow finer control over direct binding than the global counterpart -B direct. The -z direct option also differs from the -B direct option in the following areas. Direct binding information is not established between a symbol reference and an associated definition within the object being created. Lazy loading is not enabled. -z endfiltee Marks a filtee so that when processed by a filter, the filtee terminates any further filtee searches by the filter. -z finiarray=function Appends an entry to the .finiarray section of the object being built. If no .finiarray section is present, a section is created. The new entry is initialized to point to function. See for more details. -z groupperm | nogroupperm Assigns, or deassigns each dependency that follows to a unique group. The assignment of a dependency to a group has the same effect as if the dependency had been built using the -B group option. -z ignore | record Ignores, or records, dynamic dependencies that are not referenced as part of the link-edit. Ignores, or records, unreferenced ELF sec- tions from the relocatable objects that are read as part of the link-edit. By default, -z record is in effect. If an ELF section is ignored, the section is eliminated from the output file being generated. A section is ignored when three condi- tions are true. The eliminated section must contribute to an allocatable segment. The eliminated section must provide no global sym- bols. No other section from any object that contributes to the link-edit, must reference an eliminated section. -z initarray=function Appends an entry to the .initarray section of the object being built. If no .initarray section is present, a section is created. The new entry is initialized to point to function. See for more details. -z initfirst Marks the object so that its runtime initialization occurs before the runtime initialization of any other objects brought into the process at the same time. In addition, the object runtime finalization occurs after the runtime finalization of any other objects removed from the process at the same time. This option is only meaningful when building a shared object. -z interpose Marks the object as an interposer. When direct bindings are in effect, the runtime linker searchs for symbols in any interposers before the object associated to the direct binding. See -B direct. -z lazyload | nolazyload Enables or disables the marking of dynamic dependencies to be lazily loaded. Dynamic dependencies which are marked lazyload are not loaded at initial process start-up. These dependencies are delayed until the first binding to the object is made. Note: Lazy loading requires the correct declaration of dependencies, and associated runpaths for each dynamic object used within a process. See for more details. -z ld32=arg1,arg2,... -z ld64=arg1,arg2,... The class of the link-editor is affected by the class of the output file being created and by the capabilities of the underlying oper- ating system. This option provides a means of defining any link-editor argument, so that the argument is only interpreted, respec- tively, by the 32-bit class or 64-bit class of the link-editor. For example, support libraries are class specific, so the correct class of support library can be insured using: ld ... -z ld32=-Saudit32.so.1 -z ld64=-Saudit64.so.1 ... Note: The class of link-editor that is invoked is determined from the ELF class of the first input relocatable file that is seen on the command line. This determination is carried out prior to any -z ld[32|64] processing. -z loadfltr Marks a filter to indicate that filtees must be processed immediately at runtime. Normally, filter processing is delayed until a symbol reference is bound to the filter. The runtime processing of an object that contains this flag mimics that which occurs if the LD_LOAD- FLTR environment variable is in effect. See ld.so.1(1). -z muldefs Allows multiple symbol definitions. By default, multiple symbol definitions that occur between relocatable objects result in a fatal error condition. This option, suppresses the error condition, allowing the first symbol definition to be taken. -z nocompstrtab Disables the compression of ELF string tables. -z nodefaultlib Marks the object so that the runtime default library search path, used after any LD_LIBRARY_PATH or runpaths, is ignored. This option implies that all dependencies of the object can be satisfied from its runpath. -z nodelete Marks the object as non-deletable at runtime. The runtime processing of an object that contains this flag mimics that which occurs if the object is added to a process using dlopen(3C) with the RTLD_NODELETE mode. -z nodlopen Marks the object as not available to dlopen(3C), either as the object specified by the dlopen(), or as any form of dependency required by the object specified by the dlopen(). This option is only meaningful when building a shared object. -z nodump Marks the object as not available to dldump(3C). -z nopartial Partially initialized symbols, that are defined within the input relocatable object files, are expanded in the output file being gener- ated. -z noversion Does not record any versioning sections. Any version sections or associated .dynamic section entries are not generated in the output image. -z now Marks the object as requiring non-lazy runtime binding. This mode is similar to adding the object to the process by using dlopen(3C) with the RTLD_NOW mode, or having the LD_BIND_NOW environment variable in effect. See ld.so.1(1). -z origin Marks the object as requiring immediate $ORIGIN processing at runtime. This option is only maintained for historic compatibility, as the runtime analysis of objects to provide for $ORIGIN processing is now default. -z preinitarray=function Appends an entry to the .preinitarray section of the object being built. If no .preinitarray section is present, a section is created. The new entry is initialized to point to function. See for more details. -z redlocsym Eliminates all local symbols except for the SECT symbols from the symbol table SHT_SYMTAB. All relocations that refer to local symbols are updated to refer to the corresponding SECT symbol. This option allows specialized objects to greatly reduce their symbol table sizes. Note, eliminated local symbols can compromise the .stab* debugging information that is generate using the compiler drivers -g option. See also the -s option. -z rescan Rescans the archive files that are provided to the link-edit. By default, archives are processed once as the archives appear on the command line. Archives are traditionally specified at the end of the command line so that their symbol definitions resolve any preced- ing references. However, specifying archives multiple times to satisfy their own interdependencies, can be necessary. The -z rescan option causes the entire archive list to be reprocessed in an attempt to locate additional archive members that resolve symbol references. This archive rescanning continues until a pass over the archive list occurs in which no new members are extracted. -z text In dynamic mode only, forces a fatal error if any relocations against non-writable, allocatable sections remain. For historic reasons, this mode is not the default when building an executable or shared object. However, its use is recommended to insure that the text seg- ment of the dynamic object being built is shareable between multiple running processes. A shared text segment incurs the least reloca- tion overhead when loaded into memory. -z textoff In dynamic mode only, allows relocations against all allocatable sections, including non-writable ones. This mode is the default when building a shared object. -z textwarn In dynamic mode only, lists a warning if any relocations against non-writable, allocatable sections remain. This mode is the default when building an executable. -z verbose This option provides additional warning diagnostics during a link-edit. Presently, this option conveys suspicious use of displacement relocation. In future, this option might be enhanced to provide additional diagnostics that are deemed too noisy to be generated by default. LD_LIBRARY_PATH A list of directories in which to search for the libraries specified using the -l option. Multiple directories are separated by a colon. In the most general case, this environment variable contains two directory lists separated by a semicolon: dirlist1;dirlist2 If ld is called with any number of occurrences of -L, as in: ld ... -Lpath1 ... -Lpathn ... then the search path ordering is: dirlist1 path1 ... pathn dirlist2 LIBPATH When the list of directories does not contain a semicolon, the list is interpreted as dirlist2. The LD_LIBRARY_PATH environment variable also affects the runtime linkers search for dynamic dependencies. This environment variable can be specified with a _32 or _64 suffix. This makes the environment variable specific, respectively, to 32-bit or 64-bit processes and overrides any non-suffixed version of the environment variable that is in effect. LD_NOEXEC_64 Suppresses the automatic execution of the 64-bit link-editor. By default, the link-editor executes the 64-bit version when the ELF class of the first input relocatable file identifies a 64-bit object. The 64-bit image that a 32-bit link-editor can create, has some limitations. However, some link-edits might find the use of the 32-bit link-editor faster. LD_OPTIONS A default set of options to ld. LD_OPTIONS is interpreted by ld just as though its value had been placed on the command line, immedi- ately following the name used to invoke ld, as in: ld $LD_OPTIONS ... other-arguments ... LD_RUN_PATH An alternative mechanism for specifying a runpath to the link-editor. See the -R option. If both LD_RUN_PATH and the -R option are specified, -R supersedes. SGS_SUPPORT Provides a colon-separated list of shared objects that are loaded with the link-editor and given information regarding the linking process. This environment variable can be specified with a _32 or _64 suffix. This makes the environment variable specific, respec- tively, to the 32-bit or 64-bit class of ld and overrides any non-suffixed version of the environment variable that is in effect. See also the -S option. Notice that environment variable-names that begin with the characters 'LD_' are reserved for possible future enhancements to ld and ld.so.1(1). libx.so shared object libraries. libx.a archive libraries. a.out default output file. LIBPATH For 32-bit libraries, the default search path is /usr/ccs/lib, followed by /lib, and finally /usr/lib. For 64-bit libraries, the default search path is /lib/64, followed by /usr/lib/64. /usr/lib/ld A directory containing several mapfiles that can be used during link-editing. These mapfiles provide various capabilities, such as defining memory layouts, aligning bss, and defining non-executable stacks. See attributes(5) for descriptions of the following attributes: +-----------------------------+-----------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +-----------------------------+-----------------------------+ |Availability |SUNWtoo | +-----------------------------+-----------------------------+ as(1), crle(1), gprof(1), ld.so.1(1), pvs(1), exec(2), stat(2), dlopen(3C), dldump(3C), elf(3ELF), ar.h(3HEAD), a.out(4), attributes(5) Default options applied by ld are maintained for historic reasons. In today's programming environment, where dynamic objects dominate, alternative defaults would often make more sense. However, historic defaults must be maintained to insure compatibility with existing pro- gram development environments. Historic defaults are called out wherever possible in this manual. For a description of the current recom- mended options, see the ``Link-Editor Quick Reference'' in the . If the file being created by ld already exists, the file is truncated after all input files have been processed. The existing file is over- ridden with the new file contents. ld does not create a temporary file as part of the link-edit, since multiple instances of large output files frequently exhaust system resources. The drawback of overriding an existing file occurs if the file is in use by a running process. In this case, the process might be prematurely terminated as the output files image is created. This situation can be avoided by removing the output file before performing the link-edit. This removal is not detrimental to the running process. The removal frees up the file sys- tem namespace, not the actual disk space, for the new output file creation. The disk space of a removed file is freed when the last process referencing the file terminates. 12 Sep 2005 ld(1)