ld(1)
ld - Link editor
As shipped in IRIX 6.5.7. Last changed in IRIX 6.5.5.
NAME ld - Link editor SYNOPSIS ld [-32] [-64] [-a] [-abi] [-ajeop] [-all] [-allow_jump_at_eop] [-allow_missing] [-allow_r5k_jump_at_eop] [-aoutkeep] [-B num] [-Bsymbolic] [-call_shared] [-cckr] [-check_registry location_file] [-cxx] [-d] [-D num] [-default_delay_load] [-delay_load] [-demangle] [-dont_warn_unused] [-d] [-e symbol] [-elf] [-elsmap] [-elspec file] [-exact_version] [-exclude object] [-exports] [-exports_file file] [-exported_symbol symbol_list] [-f fill] [-fini ffuncsymbols] [-force_load] [-from option_list_file] [-full_transitive_link] [-G [num]] [-gpinfo] [-guarantee_init] [-guarantee_start_init] [-h] [-hiddens_file file] [-hidden_symbol symbol_list] [-hides] [-I pathname] [-ignore_minor] [-ignore_unresolved] [-ignore_version] [-info] [-init ifuncsymbol] [-ivpad] [-l x] [-L dir] [-LD_LAYOUT:...] [-LD_MSG:...] [-m] [-MDupdate file] [-mips2] [-mips3] [-mips4] [-mmap] [-n] [-N] [-n32] [-no_archive] [-noinfo] [-noivpad] [-no_jump_at_eop] [-no_library_replacement] [-no_rqs] [-none] [-non_shared] [-no_r5k_jump_at_eop] [-nostdlib] [-notall] [-no_transitive_link] [-no_unresolved] [-objectlist object_list_file] [-o outfile] [-quickstart_info] [-r] [-read] [-rdata_shared] [-rdata_writable] [-rpath library_path] [-require_minor] [-s] [-set_version version_string] [-shared] [-show] [-show_unref] [-soname shared_object_name] [-_SYSTYPE_SVR4] [-T num] [-transitive_link] [-u symname] [-U] [-update_registry location_file] [-v] [-V] [-VS num] [-w] [-Wx] [-warn_unused] [-woff numlist] [-x] [-Xlocal names] [-ysym] [-z] file ... IMPLEMENTATION IRIX systems DESCRIPTION ld, the link editor, links ELF object files to create an executable file. ld uses the archive format 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 shared linking), and supports symbol table information for symbolic debugging. In the simplest case, the names of several object files are specified, and ld combines them. This produces an object module that can be executed or used as input for a subsequent ld run. By default, the output from ld is left in file a.out. Input sections are linked together contiguously into output sections. Output sections are organized in an ELF file into loadable segments specified in the program header. Segments represent a contiguous portion of the file to be loaded into memory, with possibly the addition of extra memory at the end. For more information, see the elf(4) man page. The sections within the argument object files are combined, some by merging and others by concatenation. Unless the -e option is specified, the entry point of the output is the first instruction in the text segment. Typically, ld is invoked by cc(1), CC(1), f77(1), or f90(1) as the final step in compilation, but it can be run separately. Many ld options can be specified to the linker as options to the -Wl option on the compiler command line. For example: cc ... -Wl,-m The following terms are used on this man page and throughout the loader documentation: Term Definition a.out File a.out is an executable file produced by ld, but it is not a Dynamic Shared Object (DSO). By default, the IRIX compilers invoke ld and produce an a.out file that is a dynamic executable. You can also request that the compiler produce an a.out file that is not a dynamic executable by compiling with the -non_shared option on the compiler command line. DSO A DSO, or Dynamic Shared Object, is an executable object file that is relocatable by rld(5) at load time. It consists of shared text and data. It is produced by the linker. Usually written to file.so. Library A generic term that includes both DSOs and archive libraries. Object file A relocatable file produced by the compiler and written to file.o. Archive Produced by ar(1). Usually written to file.a. Section A contiguous block of data and internal information in an object file that is manipulated by the linker as a single piece. Segment A contiguous block of data and internal information in an executable file that is manipulated by the kernel as a single piece. In general, the linker takes sections from object files and concatenates them to form segments in executable files. In general, the kernel maps each segment into the processes address space at the addresses specified by the linker. This man page describes each ld option. After each option's description is a parenthesized list that indicates the compiler command lines from which the particular option can be passed as an argument to the compiler's -Wl option. The compilers are represented as follows in the these lists: Notation Compiler C MIPSpro C Compiler C++ MIPSpro C++ Compiler F77 MIPSpro Fortran 77 Compiler F90 MIPSpro 7 Fortran 90 Compiler The following sections catagorize the linker options. Symbol Resolution and Input Search Path The following linker options are involved in the symbol resolution process: -lx Identifies library files. The linker searches for libraries libx.so or libx.a, where x is a string. A shared object or an archive is searched when its name is encountered, so the position of the -l option on the command line is significant. (C, C++, F77, F90) -L dir Controls the library search path. When dir is specified, the linker searches the directories specified in dir before it searches the default directories. The linker searches for libx.so, libx.a, or libx.b in dir. If -L dir is specified in conjunction with -l x, the -L option must be before (to the left) of the -l option(s). If the -L dir option is specified in conjunction with the -v option, the system writes the search paths and indicates which libraries were actually chosen. This option can be specified without a space between -L and dir. (C, C++, F77, F90) -nostdlib Prevents the linker from searching in the default directories. This option is useful when the default directories for libraries should not be searched and only the directories specified by -L dir are to be searched. The -nostdlib option is a synonym for the -L option specified without its dir argument. For example, assume that you wanted library mylib searched, and mylib is stored in directory mydir. Further assume that you do not want the linker to search in the default directories. The following sample command lines are equivalent: ld -nostdlib -L mydirs -lmine kangaroo.o ld -L -L mydirs -lmine kangaroo.o This searches for libmine.a or libmine.so in mydirs. mydirs is a colon-separated list of search directories. The -nostdlib option must be specified in conjunction with the -L dir option. (C, C++, F77, F90) -u symname Enters symname as an undefined symbol in the symbol table. This is useful for loading entirely from an archive because initially, the symbol table is empty and an unresolved reference is needed to force the loading of the first routine. (C, C++) -cckr Sets the value of the variable _lib_version to specify non-ANSI semantics to libc. For more information, see end(3C). (C) -cxx Specifies special handling of certain symbols needed for proper linkage and execution of C++ programs. Input Specification Options The following options affect both input object specification and symbol resolution: -from option_list_file Allows you to specify arguments to ld from a file. ld reads file option_list_file as if it appeared on the command line in the same position as the -from option. New-line characters in option_list_file are treated as if they were ordinary spaces. -objectlist object_list_file Specifies a file list. The file specified by object_list_file contains a list of file or archive names. By putting the file list in an object_list_file instead of on the command line, you can avoid exceeding the limit on the length of a command line. This is primarily useful when linking very large programs with many objects and long file names. In the object_list_file, blank lines and leading white space are ignored. Files must be listed one per line. A file name is considered ended by the next whitespace character. Characters after the file name are ignored. Any leading dash (-) characters in an object_list_file line are considered part of a file name; nothing in the file is interpreted as an option. Lines in the file are limited to BUFSIZ*2 characters (16 Kbytes) each. (C, C++, F77, F90) -all Links in all of the objects from all archives following this option. This option is commonly used in conjunction with the -shared option to create a shared object out of an existing archive. (C, C++, F77, F90) -notall Turns off the action of the -all option. This pulls objects out of the archive into a DSO if the objects resolve unresolved symbols in the already included object, but these objects are included without exporting their symbols by default. (C, C++, F77, F90) -exclude object Used in conjunction with the -all and -shared options. The object specified is excluded from the shared object. (C, C++, F77, F90) -no_archive Specifies that that references to libraries specified in the -l option must resolve to shared objects. Typically, if the shared object, as specified by the -l option, is not found, the linker attempts to find the corresponding archive to resolve undefines. Specifying this does not allow those archives to be used. (C, C++, F77, F90) -MDupdate file By default, the linker adds the names of any objects and DSOs used in the link to file. When compiling, file is updated to contain header, library, and run-time make(1) dependencies for the output file. When this option is specified, the linker updates only lines that end with a distinctive make comment and begin with the name of the output file followed by a colon (:). The standard name for file is Makedepend. (C, C++, F77, F90) -MDignore name Prevents the linker from adding the named object or DSO to the Makedepend file. For more information, see the -MDupdate file option's description. (C, C++, F77, F90) Debugging Options The debugging options control listings and messages that can be produced when debugging new software. For more information on controlling messages when debugging, see the description for the -LD_MSG: option group. The following options aid in debugging linking sessions: -aoutkeep By default, ld removes the output file if there are link errors. When this option is specified, though, the output is written to a.out. (C, C++, F77, F90) -m Writes a map or listing of the input/output (I/O) sections to standard output. This is a UNIX system V-like map. -gpinfo Produces a listing of short data section components (page pointers, GOT pointers, small data, and small literals). This may be useful in identifying modules with large GP-relative sections. The listing produced by this option is a subset of the information that is produced when -m is specified. If you receive message 171, it means that the GP-relative data has been broken up into several areas (multigot). The -gpinfo option does not work in such cases, but you can specify the -m option. The -m option is a good alternative. It provides all the information needed to analyze GP-relative usage. -show Prints the name of the specific linker being used. (C, C++, F77, F90) -v Sets verbose mode. This option generates more information than the -show option. This options shows linker phases, what and where it searches for objects and libraries, and what is actually linked in. (C, C++, F77, F90) -quickstart_info Prints extra information regarding the quickstart status of the executable file created. This includes a full list of conflict symbols and their objects of origin. (C, C++, F77, F90) -ysym Writes symbol information to stderr. Indicates each file in which sym appears, sym's type, and whether the file defines or references sym. Many such options can be given to trace many symbols. Each -ysym applies to those files listed after this option on the command line. Symbols and archived objects that are not linked in and DSOs that are not used do not appear in the output. (C, C++, F77, F90) -V Prints the version of ld being used. -f fill Sets the fill pattern for holes between sections within an output segment. The argument fill must be a four-byte hexadecimal constant. As the linker lays out sections, the alignment restrictions lead to gaps, or holes, between the sections. This option specifies the value to use to fill the holes. -show_unref Lists defined but unreferenced symbols. This option can be used when looking for dead code in a program. Note that library routines typically define symbols that might not be referenced by all programs. Also, in the case of weak and strong symbol pairs, in which two different symbols point to the same virtual address, if only one of them is referenced, the other symbol is still listed. This does not necessarily mean the specified function is never used. -split_common Shows how and where split commons were laid out. For more information on this, see the opt(5) man page's description of the -OPT:reorg_common option. Message Options The following options affect the process of issuing messages: -LD_MSG:[msgtype=numlist][:msgtype=numlist]... Changes or respecifies message severities. This option controls the general message handling interface for ld. It allows you to change the default message severity. For numlist, specify a comma- or dash-separated list of message numbers. For a list of the linker messages and their numbers, see the MESSAGES section. Valid msgtype arguments, and their meanings, are as follows: msgtype Meaning error Treats each message in numlist as an error. warning Treats each message in numlist as a warning. info Treats each message in numlist as an informational message. verbose Treats each message in numlist as a verbose message. off Ignores each message in numlist. Example 1: Specifying -LD_MSG:warning=33 tells the linker to treat message 33, which by default is an error, as a warning. Similarly, specifying -LD_MSG:warning=33:off=47-68 tells the linker to treat message 33 as a warning and to ignore all messages from 47 to 68 inclusive. Example 2: Some information obtained when the -v (verbose mode) option is enabled can be of use when debugging programs. To obtain informational messages regarding symbol resolution conflict, preemption, and type mismatch information in regard to weak symbols, specify the following ld options: -LD_MSG:info=134,175-177 -quickstart_info The preceding options produce the following messages: 134: Weak definition preempting another weak definition. 174: Strong definition preempting a weak definition. 175: Weak definition type mismatch with a strong definition. 176: Weak definition type mismatch with a reference. 177: Weak definition type mismatch with another weak definition. Fatal errors cannot be modified by -LD_MSG:. (C, C++, F77, F90) -U Suppresses error messages that would be generated for undefined symbols. This option allows you to create an executable with undefined symbols. Referencing an undefined symbol during execution can cause a segmentation fault and a core dump. -woff numlist Suppresses the messages specified in numlist. For numlist specify a comma-separated list of warning message numbers. For example, specifying -woff " 5,17,23" suppresses warning messages numbered 5, 17, and 23. If you are linking using the cc(1) command, this option should be passed to the linker with the following three options: -Wl,-woff,5 -Wl,- woff,17 -Wl,-woff,23. This is equivalent to specifying -LD_MSG:OFF=5,7,23. (C, C++, F77, F90) -w Specifies that all warnings are to be suppressed. (C, C++, F77, F90) -info Generates messages of an informational nature that might highlight unusual, but not illegal, situations. This is enabled by default. (C, C++, F77, F90) -noinfo Suppresses informational messages generated when the -info option is in effect. (C, C++, F77, F90) -demangle Specifies that demangling of C++ names should take place when generating other messages. (C) -ignore_unresolved Produces an executable or DSO and exits with zero status even if there are unresolved symbols. Resolution of these symbols is completed by rld(5). If the -call_shared option is also specified, a list of the unresolved symbols is generated. If the -shared option is also specified, no such list is generated. If the -non_shared option is also specified, the -ignore_unresolved option is ignored and the -no_unresolved option is put into effect, as it always is when -non_shared is specified. This option is enabled by default when the -shared option is specified, but it is not enabled when the -call_shared or -non_shared options are enabled. (C, C++, F77, and F90) -no_unresolved Lists unresolved symbols. If the -shared option is also specified, a DSO is produced and ld exits with zero status. If the -call_shared or -non_shared options are specified, ld exits with nonzero status and no executable is produced. This option is enabled by default when the -call_shared or -non_shared options are specified, but it is disabled by default when the -shared option is specified. (C, C++, F77, and F90) -warn_unused Specifies that the linker should issue a warning if it finds that some object has not been used in a link. The semantics of dynamic linking dictate that this cannot be determined absolutely at static link time, but it is usually quite reliable. This option is enabled by default. (C, C++, F77, F90) -dont_warn_unused Disables the warning that is issued when the -warn_unused option is in effect. (C, C++, F77, F90) -allow_missing When using an ELF layout specification file with the -elspec option, the linker typically generates an error if portions of the object file that are not strippable have been omitted from the output. Specifying the -allow_missing option overrides this error check and allows the omission of data or text that would ordinarily be linked. In this case, you must ensure that the output is correct. Stripping Options The following options are involved in the process of stripping information from an object file. The linker does not strip out information that would prevent the program from running. -s Strips the symbolic information from the output object file. (C, C++, F77, F90) -x Does not preserve local (non-global) symbols in the output symbol table. The linker enters external and static symbols only. This option conserves space in the output file. Output Object Format Options The following options affect the format of the output object file: -r Retains 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. This option cannot be specified in conjunction with the -non_shared option; do not use them together on the same command line. -elf Produces an ELF output object file. This is the default, and currently the only, file format supported. (C, C++, F77, F90) -non_shared Produces a static executable. The output object created will not use any shared objects during execution. This declares that you are not loading position-independent code (PIC). This option cannot be specified in conjunction with the -r option; do not use them together on the same command line. (C, C++, F77, F90) -shared Produces a DSO, creates all of the tables for run-time linking, and resolves references to other specified shared objects. The object created can be used by the linker to make dynamic executables. (C, C++, F77, F90) -call_shared Produces a dynamic executable. The object created can use shared objects at runtime. This is enabled by default. (C, C++, F77, F90) -32 or -o32 Specifies that the object to be linked (and the input objects) are to be old-style, 32-bit ucode objects. (C, C++, F77, F90) -n32 Specifies that the object to be linked (and the input objects) are to be new-style, 32-bit objects. (C, C++, F77, F90) -64 Specifies that the object to be linked (and the input objects) are to be 64-bit objects. (C, C++, F77, F90) -abi Specifies that the resultant output executable conforms to generic MIPS ABI conventions. (C, C++, F77, F90) -mips2 Specifies that the linker should try to produce a binary that conforms to the MIPS 2 ISA. (C, C++, F77, F90) -mips3 Specifies that the linker should try to produce a binary that conforms to the MIPS 3 ISA. If ld finds object files that are MIPS 4, the resulting binary is silently marked as being a -mips4 binary. (C, C++, F77, F90) -mips4 Specifies that the linker should try to produce a binary that conforms to the MIPS 4 ISA. (C, C++, F77, F90) Layout Options The layout options affect the layout of the object file. They are as follows: -LD_LAYOUT:[command=arg][:command=arg]... The -LD_LAYOUT option group accepts arguments that control the layout of the object file. These arguments are as follows: seglign=alignval Defines the minimum segment alignment to be alignval. This value needs to be both 0x1000 or greater and a power of 2. lgot_buffer=val Used by ld after it exhausts local Global Offset Table (GOT) page slots. The val argument is the number of extra slots per local GOT area to use. mgot_threshold=setting This is for internal use. When used in conjunction with force_multigot, forces different levels of multigot during regression testing. When disabled, every input section to has its own GOT. setting indicates a Boolean option that can be enabled or disabled. To enable, specify ON, 1, or TRUE. To disable, specify OFF, 0, or FALSE. multigot This is for internal use. Usually, the linker attempts to link everything, generating a single GOT. If this fails, it reruns the layout phase and possibly creates multiple GOT regions. This option causes the first layout pass to fail. This is used in conjunction with the mgot_threshold option described previously. force_multigot This is for internal use. When used in conjunction with the mgot_threshold (described previously), it forces multiple levels of multigot during regression testing. segalign=val Defines the minimum segment alignment. val must be both 0x1000 or greater and a power of 2. one_got=setting Prevents the linker from producing multiple GP regions. For more information, see mgot_threshold, which is described previously in this list. setting indicates a Boolean option that can be enabled or disabled. To enable, specify ON, 1, or TRUE. To disable, specify OFF, 0, or FALSE. reorder_file=feedback_file Names a feedback file. When specified, function layout in the text section is optimized to minimize page faults and I-cache misses based upon the frequency information in feedback_file. This file is usually produced by prof(1)/cvperf(1) or sscord(1)/ssorder(1), but a user can also construct or modify this ASCII file. Note that object files must have been compiled with the -OPT:procedure_reorder=ON option specified. For more information on this option, see the opt(5) man page. For information on messages related to this option, see the MESSAGES section of this man page. For an example that shows reordering code regions, see the MIPSpro Compiling and Performance Tuning Guide. (C, C++, F77, F90) -d Forces definition of common storage and defines loader-defined symbols even if -r is present. -z Arranges that the process pages are loaded on demand from the resulting executable file rather than preloaded, and that the text pages are shared among all users. This is in effect by default. -n Preloads the entire text and data portions of the executable(s) when the output file is executed. This involves moving the data areas up to the first possible pagesize byte boundary following the end of the text. You must specify the -non_shared option in conjunction with the -n option. (C, C++, F77, F90) -N Places the data segment immediately after the text and does not make the text portion read only or sharable. You must specify the -non_shared option in conjunction with the -N option. -T num Sets the text segment origin. (C, C++, F77, F90) -D num Sets the initialized data segment origin. Specify a hexadecimal number for num. (C, C++, F77, F90) -B num Sets the uninitialized data (BSS) segment origin. Specify a hexadecimal number for num. -G [num] Specifies the largest size, in bytes, of a .comm item that is to be allocated in the small BSS section for reference off of the global pointer (GP). The default is 8 bytes. If the -_SYSTYPE_SVR4 option has been specified, this option is a synonym for the -shared option and takes no numerical argument. -rdata_writable Puts .rodata into the data segment, which has write permission. This is in effect by default. (C, C++, F77, F90) -rdata_shared Puts .rodata into the text segment, where it is shared across processes and is read-only. (C, C++, F77, F90) -ivpad Improves cache behavior by causing the linker to perform intervariable padding of some large variables. This is in effect by default. (C, C++, F77, F90) -noivpad Disables the behavior of the -ivpad option. (C, C++, F77, F90) -Xlocal names Assigns the named global BSS (uninitialized data) symbols to a special local data section in the a.out file. This is useful for hand-parallelized Fortran programs that require this symbol to be private for each thread. A symbol assigned to the small BSS or small data section of an object file cannot be moved to the special section. If the symbol is assigned to either the small BSS or small data section, either recompile with a smaller -G number or use the following directive in your source code: #pragma section_non_gp(name) (in C) or C*$*SECTION_NON_GP(name) (in Fortran). -elspec file Specifies a file to serve as an ELF layout specification file. This file and its syntax are described in elspec(5). -elsmap Specifies that the linker should emit a layout map in the form of an ELF layout specification. The output from this specification can be used with the -elspec option without modification. -check_registry location_file Checks the location of this shared object's segments and makes sure they stay out of the way of others in the location_file. A single registry file, either with -check_registry or -update_registry, is allowed. This option must be specified in conjunction with the -shared option. (C, C++, F77, F90) -update_registry location_file Registers the location of this shared object's segments and makes sure they stay out of the way of others in the location_file. The location_file is updated if it is writable. A single registry file, either with -check_registry or -update_registry, is allowed. This option is must be specified in conjunction with used with the -shared option. The default registry file is either /usr/lib,32/so_locations or /usr/lib,64/so_locations, depending on your compilation. For more information on so_locations, see the dso(5) man page. (C, C++, F77, F90) Dynamic Linking Options The following options affect dynamic linking: -e symbol Sets the default entry point address for the output file to be that of the symbol symbol. (C, C++, F77, F90) -I pathname Writes the path name into the .interp section. The pathname is a path name for the system to invoke as a program interpreter. -default_delay_load When creating a dynamic shared object using the -shared option, this option marks that shared object as default delay load. (C, C++, F77, F90) -delay_load Indicates that the next specified DSO should be delay loaded. Typically, linking against a DSO causes that DSO to be loaded at runtime whenever the DSO being created is loaded. This resolves the symbols supplied by that object. You can use the -delay_load option to delay the loading of a DSO. When -delay_load is specified, the DSO is not loaded until a symbol supplied by the DSO is actually referenced. Be careful when using the -delay_load option or when linking against a DSO that was built using the -default_delay_load option. Symbols from a delay-loaded DSO do not preempt symbols from other libraries; they are resolved as if the DSO was last on the link line. (C, C++, F77, F90) -force_load Forces the normal loading of the next specified DSO, overriding any default delay load attribute associated with that DSO. (C, C++, F77, F90) -exports Used in conjunction with the -shared or -call_shared options. Specifies that symbols from the next object, archive, or DSO be exported by the object being created. This is the default behavior for linking in an object, but it is not for archives or DSOs. (C, C++, F77, F90) -hides Used in conjunction with the -shared or -call_shared options. Specifies that symbols from the next object, archive, or DSO be hidden by the object being created. This is the default behavior for linking in archives or DSOs, but it is not for relocatable objects. (C, C++, F77, F90) -exported_symbol symbol_list Used in conjunction with the -shared or -call_shared options. Marks the specified symbols as exported. Use a comma to separate the symbols. If you specify any exported symbols, all unspecified symbols are automatically hidden. (C, C++, F77, F90) -exports_file file Used in conjunction with the -shared or -call_shared options. The specified file must contain a list of symbols that should be exported. The list is comprised of symbol names separated by spaces or new-line characters. Any symbols not specifically exported will be automatically hidden. (C, C++, F77, F90) -hidden_symbol symbol_list Used in conjunction with the -shared or -call_shared options. Marks the specified symbols as hidden. Use a comma to separate the symbols. This option is ignored if any symbols are specifically marked as exported using the -exported_symbol or -exports_file options. If you specify -hidden_symbol, all unspecified symbols are automatically exported, including those that were implicitly hidden when loading archive libraries. (C, C++, F77, F90) -hiddens_file file Used in conjunction with the -shared or -call_shared options. The file specified by file must contain a list of symbols to be hidden. The list is comprised of symbols separated by spaces or new-lines characters. This option is ignored if any symbols in the list are specifically marked as exported using the -exported_symbol or -exports_file option. (C, C++, F77, F90) -transitive_link Typically, every shared object and every executable has a dependency list of shared objects that are needed for correct execution. The runtime linker, rld(5), loads these objects when any process is run. If the depended-upon shared objects have more objects that they in turn depend upon, rld(5) adds them at the end of the list, and so on, performing a transitive closure. By default, a similar operation is performed at static, ld, link time. Any shared object that is listed on the command line is put on a.out's dependency list. Then any new shared objects from the dependency lists of the already-processed shared objects are also processed and checked for conflicting definitions of symbols, but they are not added to the list of shared objects needed by the object being built. This is the default behavior. (C, C++, F77, F90) -no_transitive_link Some applications may find it desirable to hide some of their dependent libraries. This option cancels the upward propagation of libraries to facilitate such hiding. Executables and shared objects built in this way can experience slightly slower startup. (C, C++, F77, F90) -full_transitive_link Specifies that the linker perform the work described for the -no_transitive_link option and, in addition, add each library encountered to the list of objects needed by the current object, beyond what is specified on the link line. (C, C++, F77, F90) -B symbolic Inserts the element DT_SYMBOLIC into the .dynamic section of a shared object library. This alters the dynamic linker's symbol resolution algorithm for references within the library. Instead of starting a symbol search with the executable file, the dynamic linker starts from the shared object itself. If the shared object fails to supply the referenced symbol, the dynamic linker then searches the executable file and other shared objects as usual. -set_version version_string Sets the value of the DT_MIPS_IVERSION field in the dynamic section of the shared object to version_string. The version_string must consist of a series of version strings separated by colons (:). (C, C++, F77, F90) -exact_version Sets the LL_EXACT_MATCH flag in the .liblist flags field. This indicates to rld(5) that this shared object must match the timestamp and checksum from the .liblist section in addition to the interface version. This means that all DSOs run against must match exactly the version, timestamp, and checksum against which the application was linked (or processed by rqs). Moreover, if the object is copied to another machine, it will not run unless the object is first processed by rqs(1) because the other machine is likely to have a different checksum and timestamp for things on the liblist of this object, such as libc.so.1. On a MIPS4 machine (such as R10000), the following would not execute: cc t.c -n32 -mips3 -Wl,-exact_version ; ./a.out rld(5) would generate a fatal error for the previous command because the MIPS3 libc.so.1 linked against is not the same as the MIPS4 libc.so.1 against which the executable will run on that machine. (C, C++, F77, F90) -ignore_version Sets the LL_IGNORE_VERSION flag in the liblist flags field. For subsequent shared objects in the liblist, rld(5) does not try to match the interface version as specified at link time. (C, C++, F77, F90) -require_minor Sets the LL_REQUIRE_MINOR flag in the .liblist flags field for DSOs listed subsequently on the ld command line. This indicates to rld(5) that the shared object used at runtime must have the exact same minor (and major) version number as that at static link time. Otherwise, execution aborts. For more information on major and minor version numbers, see the dso(5) man page. (C, C++, F77, F90) -ignore_minor Clears the LL_REQUIRE_MINOR flag in the .liblist flags field for shared objects listed subsequently on the ld command line. This allows rld(5) to use a shared object at runtime that has a different minor version number. This option is enabled by default. For more information on major and minor version numbers, see the dso(5) man page. (C, C++, F77, F90) -no_library_replacement Turns on a flag in the dynamic section so that rld(5) does not allow execution time or runtime changes to the path (except by a superuser) to find the shared objects. Typically, this option is used for security purposes on system utilities. (C, C++, F77, F90) -rpath library_path Adds the library_path to the search path for DSOs. Each library path is appended to the list of directories at the time the executable or DSO is loaded. This option directs rld(5) to look in the named directories, but to look only for DSOs, and to stop looking when the correct one is found. This option can be specified only when the -shared or -call_shared options are also in effect. For more information, see the rld(5) man page. (C, C++, F77, F90) -soname shared_object_name Sets DT_SONAME for a shared object. Must be specified in conjunction with the -shared option. The shared_object_name can be a single component name (for example, libc.a), a full path name (starting with a slash), or a relative path name (containing a slash). Single component names use rpath, LD_LIBRARY_PATH, and the default paths to resolve their locations. (C, C++, F77, F90) -init ifuncsymbol Puts a call to ifuncsymbol into the code that rld(5) exercises before the main program begins. The ifuncsymbol contains initialization code to be called before control is passed to main. In the case of a DSO opened with dlopen(3C) or sgidladd(3C) an initialization function is called after the DSO is loaded but before it is referenced. A single -init option is effective in a given DSO or executable. To specify more than one ifuncsymbol, specify multiple -init options on the command line. If multiple -init options are specified, they are executed at runtime in the order listed on the command line. This option can be specified only when the -shared or -call_shared options are also in effect. Any user .init sections are concatenated to the ones generated by the linker. For information on how to specify your own -init functions, see the EXAMPLES section. (C) -fini ffuncsymbol Puts calls to one or more ffuncsymbol into the code that rld(5) exercises after the main program exits. The ffuncsymbol contains the termination code to be called after the main program exits. In the case of a DSO that is no longer referenced and is closed using dlclose(3C), this function is called before the DSO is unmapped. A single -fini option is effective in a given DSO or executable. To specify more than one ffuncsymbol, specify multiple -fini options on the command line. If multiple -fini options are provided, they are executed at runtime in the reverse order listed on the command line. The ordering facilitates pairing -init and -fini entries in makefiles. This option can be specified only when the -shared or -call_shared options are also in effect. For information on how to specify your own -fini functions, see the EXAMPLES section. (C) I/O Options The options affect I/O: -mmap Directs the linker to use mmap(2) as its preferred mode for reading object files. This usually results in better I/O performances, except when using NFS mounted files with high network latencies. This is enabled by default. -read Directs the linker to use the open(2), lseek(2), and read(2) utilities as its preferred mode for reading object files. Setting this option when many object files are remotely mounted with high network latency often improves performance. Hardware Patch Options The following options are patches to the hardware: -no_jump_at_eop Works around an R4000 bug present in 2.1 and 2.2 silicon. This option tries to prevent certain classes of branch instructions from being the last instruction on a page of virtual memory. This option is enabled by default for links of MIPS3 or lower programs. You can use the hinv(1M) command to determine what revision of R4000 is present in the system. The kernel automatically works around this problem with early versions of the R4000, but there is a small performance penalty. Using this option helps avoid the situation in which a kernel workaround is needed. -allow_jump_at_eop Disables the work-around for the R4000 bug. When this flag is present, no adjustment is attempted. The work-around is enabled by default, so the presence of the -allow_jump_at_eop option before any object files disables the feature. Disabling the workaround can result in code that is not compatible across platforms and may also result in a performance penalty on some R4000 systems. Miscellaneous Options The following are miscellaneous options: -o outfile Produces an output object file by the name outfile. The name of the default output file is a.out. For example, in the event that outfile has undefined references at the end of the link editor run, and the -r option was not used, and the -aoutkeep option was used, outfile is renamed a.out. If there are undefined references and the -aoutkeep option was not used, there is no output from ld. If the specified output file already exists, the ownership and mode from the existing file are retained. (C, C++, F77, F90) -VS num Uses 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. (C, C++, F77, F90) -_SYSTYPE_SVR4 Alters the meaning of the -G option to conform to the UNIX System V Release 4 usage. For more information, see the -G [num] option. When specified on the compiler command line, this option is -SYSTYPE_SVR4. (C, C++, F77, F90) Synonym Options The following options are synonyms for other ld options: -ajeop This is a synonym for -allow_jump_at_eop. -G If the -_SYSTYPE_SVR4 option has been specified, this option is a synonym for -shared and takes no numerical argument. (C) -Wx,-G num This is a synonym for the non-SVR4 meaning of -G. The meaning of this option is unaffected by the use of the -SYSTYPE_SVR4 option. -h This is a synonym for -soname. -dy This is a synonym for -call_shared. (C) -dn This is a synonym for -non_shared. (C) -a This is a synonym of -non_shared. -none Same as -notall. (C, C++, F77, F90) -SYSTYPE_SVR4 This is a synonym for -_SYSTYPE_SVR4. -OPT:reorg_common This is a synonym for -ivpad. -o32 This is a synonym for -32. -hides_file file This is a synonym for the -hiddens_file option. RESERVED SYMBOLS The following symbols are reserved for internal use: .bss, .comment, .data, .fini, .init, .lit4, .lit8, .rdata, .sbss, .sdata, .text, _BASE_ADDRESS, _DYNAMIC, _DYNAMIC_LINK, _DYNAMIC_LINKING, _GOT_OFFSET, __dso_displacement, __elf_header, __fstart, __istart, __lcldta_address, __lcldta_size, __program_header_table, __rld_obj_head, __start, __unwind, _data_init_table, _edata, _end, _etext, _fbss, _fdata, _ftext, _gp, _gp_disp, _lib_version, _procedure_string_table, _procedure_table, _procedure_table_size, _rld_new_interface, _rt_symbol_string_table, _rt_symbol_table, and _rt_symbol_table_size. In addition, all symbols that begin with the prefixes __elf_vaddr and __elf_size are reserved. It is erroneous to define these symbols. In ANSI C, the following symbols can be defined: end, edata, and etext. If they are not defined (but only referenced), they are assigned the same values as _end, _edata, and _etext respectively. For more information on these symbols, see the end(3C) man page. LIBRARY SEARCH ORDER If an argument specified on the ld command line 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 DSOs. When linking with archives, only the routines that define an unresolved external reference are loaded. Shared objects are used only 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 unresolved symbols are not considered an error when linking with the -shared option. 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 not important. By default, internal libraries are not searched. When searching for ucode libraries, the default directories searched are /usr/lib/, /lib/, and /usr/local/lib/. Note that although archives are found in /usr/local/lib/, shared objects should not be installed there because rld(5) will not find them. When searching for 64-bit libraries, the default directories searched are /usr/lib64/, /lib64/, and /usr/local/lib64/. When searching for new 32-bit libraries, the default directories searched are /usr/lib32/, /lib32/, and /usr/local/lib32/. NOTES An object's segments must not overlap, and all of the object's addresses must be less than 0x80000000 (except when compiling with the old 32-bit option (-32), for which the size maximum is 0x4000000). The stack starts at 0x80000000 and grows down through lower addresses. Space should be left for it. The default text segment address is 0x10000000, with the data segment immediately following the text segment. By default, the bss segment follows the data segment. While 64-bit programs can use much more than 2 gigabytes of memory, the executable file can be at most 2 gigabytes in size. When creating an executable object runnable on UNIX, a.out, /usr/lib/crt1.o, should be the first object loaded, and /usr/lib/crtn.o should be last, following any libraries. The compilers (cc(1), CC(1), f90(1), and f77(1)) automatically load these object files in the proper order. Note that if ld is invoked directly, those two objects are not loaded automatically. It is your responsibility to specify them explicitly. The linker no longer recognizes archives built with ar -C (COFF-style) archive headers. The following group of options have been superseded by the -elspec functionality: -Xnobsschange, -Xnosortbss, -Xsortbss, -Xndblock, -Xblock, -Xblockrange, -Xndlocaldata, -Xalignbss, -Xnoalignbss, -Xcachemisalign, -Xcachesize, -Xcachelinesize, -Xdefmovemax, -Xsetalign, and -Xdebug. The -Xlocaldata option has been replaced by the -Xlocal option. EXPORTING AND HIDING SYMBOLS By default, all symbols are exported. That is, if they were externally visible in the incoming object file, they will be externally visible in the generated a.out or DSO. The one exception to this rule is when loading an archive library when building a DSO. In this case, the default behavior is to silently hide all symbols that come from the archive library. The -all option can be used to override that default behavior. WARNING: Be careful when using -hidden_symbol and archive libraries. The -hidden_symbol option silently exports the other symbols from the archive library when you might have expected them to remain hidden. When building a DSO it is a good idea to control its interface by exporting only those symbols that users are allowed to reference. This is best done by listing exported symbols in a file and using the -export_file option. This option exports the listed symbols and hides all others. EXAMPLES The following sample ld command line illustrates how to specify -init and -fini functions: ld ... -init mystartup1 -fini myshutdown1 -init mystartup2 -fini myshutdown2 The -fini routines execute in the reverse order from how they are specified on the command line, myshutdown2 first and myshutdown1 second. You cannot run myshutdown2 after myshutdown1 because all local objects will already have been destroyed by myshutdown1. FILES /usr/local/lib/lib*.a /lib/lib*.so /lib/lib*.a /usr/lib/lib*.so /usr/lib/lib*.a /usr/lib/so_locations /usr/local/lib/lib*.a libraries /lib32/lib*.so /lib32/lib*.a /usr/lib32/lib*.so /usr/lib32/lib*.a /usr/lib32/so_locations /usr/local/lib32/lib*.a libraries /lib64/lib*.so /lib64/lib*.a /usr/lib64/lib*.so /usr/lib64/lib*.a /usr/lib64/so_locations /usr/local/lib64/lib*.a libraries a.out SEE ALSO ar(1), as(1), cc(1), collide(1), f77(1), f90(1), hinv(1M), make(1), prof(1), rqs(1) lseek(2), mmap(2), open(2), read(2) end(3C) elf(4) dso(5), gp_overflow(5), opt(5), rld(5) MIPSpro Compiling and Performance Tuning Guide This man page is available only online.