LD(1)LD(1) NAME ld - Link editor SYNOPSIS ld [options] 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. If a subsequent run is done, the -e option must be used to preserve the relocation entries. By default, the output from ld is left in file a.out; this file is a dynamic executable if no errors occured during the load. 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. 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. When linking with archives, only those routines defining 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 any symbol remaining unresolved are not consider an error when the linkage is to be shared or dynamic. The library (archive) symbol table (see ar(1)) is a hash table and is searched to resolved external references that can be satisfied by library members. The ordering of library members is unimportant Linking against a dynamic shared object will normally cause that object to be loaded (see rld(1) and dso(5)) whenever the object being created is loaded, thus resolving the symbols supplied by that object. The loading of a dynamic shared object can be delayed using the -delay_load option. In this case the object is not loaded until a symbol supplied by the object is actually referenced. Symbols from a delay loaded object do not preempt symbols from other libraries; they are resolved as if the object was last on the link line. When searching for ucode libraries the default directories searched are /usr/lib/, /lib/ and /usr/local/lib/. Note that, although archives will be found in /usr/local/lib/, shared objects should not be installed there, as they will not be found by rld(1). When searching for 64bit libraries the default directories searched are /usr/lib64/, /lib64/ and /usr/local/lib64/. When searching for n32 libraries the default directories searched are /usr/lib32/, /lib32/ and /usr/local/lib32/. If a link is taking a long time to complete, use the -show option on the link line to check if interprocedural analyasis (IPA) is invoked. 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 * Input specification options * Debugging options * Message options * Stripping options * Output object format options * Layout options * Dynamic linking options * I/O options * Hardware patch options * Registry options * Miscellaneous options * Synonyms * Obsolete options Symbol Resolution and Input Search Path For a complete list of elements that affect runtime DSO search and lookup, as well as dynamic symbol resolution, see the rld(5) man page. The following linker options affects symbol resolution and object specification: -B mode Specifies a search mode. mode can be dynamic, static, direct, or symbolic. dynamic (default). ld searches each directory specified in the library search path for files ending in .so, and if not available then files ending in .a. static ld selects only the files ending in .a (except for libc). If a link with static libraries is needed, but not all of the needed .a files are available, use the following: cc prog.o -o prog -B static -lXm -lXt -B dynamic -lX11 -lgen In this case, libXm.a and libXt.a would be chosen and libX11.so if available; otherwise, libX11.a would be chosen. libgen.so would be chosen if available, otherwise libgen.a. direct Establishes direct binding information by recording the relationship between each symbol reference and the dependency that provides the definition. The runtime linker (rld) uses this information to search directly for the symbol in the associated object rather than to carry out its default symbol search. symbolic ld inserts the element DT_SYMBOLIC into the .dynamic section of a shared object library and this alters the runtime linker's (rld) symbol resolution algorithm for references within the library. Instead of starting a symbol search with the executable file, the runtime linker starts from the shared object itself. If the shared object fails to supply the referenced symbol, the runtime linker then searches the executable file and other shared objects as usual. See "Symbol Resolution and Input Search Path Options" later in this man page for more details. -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. -lx 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 Changes the algorithm for searching for libx.{so,a} or libx.b to look in dir before looking in the default directories. This option is effective only if it precedes the -l options on the command line. dir must be a directory. -Ldir The same as -L dir. -L Synonym for nostdlib. -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. (C, C++, F77, F90) -std Specifies that the linker should not define certain symbol names; for example, end, etext. -no_archive Specifies 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) -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. If the symbol used in this option is not resolved by any object by the end of the link, the resulting executable or DSO will have that symbol undefined. Input Specification Options The following options affect both input object specification and symbol resolution: -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) -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. -make_cmdfile Causes the linker to produce a linker commandfile (see -from). This is mainly used for creating linker test cases, but may also be used for packaging large link command lines. The options in the file are listed on individual lines. The file created is named with the output a.out/dso with .from appended. -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) -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) -no_archive Specifies 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) -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) 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 the output is written to a.out. Output is not written if fatal errors occur. (C, C++, F77, F90) -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. -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) -m Writes a map or listing of the input/output (I/O) sections to standard output. The report is separated into output sections. Each output section has 3 columns: * output section name * virtual address of beginning of output section * hexadecimal number of bytes in output section (size) Each output section is followed by an input section, which has 4 columns: * input section name * virtual address of beginning of input section * hexadecimal number of bytes in input section (size) * input object name (for example, *ld_internal*) for linker generated input sections. This allows the user to see exactly where each section began and where it ended. Some sections such as literal contant sections are merged by the linker to prevent duplication and will be marked as being linker generated. The following is a sample fragment of output from the -m option: LINK EDITOR MEMORY MAP output input virtual section section address size .interp 10000114 15 .interp 10000114 15 *ld_internal* .MIPS.options 10000130 80 .MIPS.options 10000130 80 *ld_internal* .reginfo 100001b0 18 .reginfo 100001b0 18 *ld_internal* .text 1000bf60 83fa4 .text 1000bf60 118 /hosts/alliant/73_roots/ROOT/usr/lib32/mips3/crt1.o .text 1000c080 93c ld_ipa_interface.o .text 1000c9c0 5f0 rel_read_write.o .text 1000cfb0 ec8 dra_demangle.o .text 1000de80 aec code.o .text 1000e970 1de8 compact_rel.o -M Produces a primitive load map (a UNIX 4.3bsd-like map) listing the names of the files that will be loaded. (C, C++, F77, F90) -show Prints the name of the specific linker being used. (C, C++, F77, F90) -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. -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) -V Prints the version of ld being used. -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) Message Options The following options affect the process of issuing error and informational 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. Valid msgtype arguments, and their meanings, are as follows: msgtype Meaning error Treats each message in numlist as an error. info Treats each message in numlist as an informational message. warning Treats each message in numlist as a warning. verbose Treats each message in numlist as a verbose message. off Ignores each message in numlist. For example, 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. (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. -demangle Specifies that demangling of C++ names should take place when generating other messages. (C) -dont_warn_unused Disables the warning that is issued when the -warn_unused option is in effect. (C, C++, F77, F90) -warn_unused Specifies that the linker should issue a warning if it finds that an archive or DSO named on the command line was not 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) -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. (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) -wall Specifies that all warnings are to be suppressed. (C, C++, F77, F90) -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) 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: -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) -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) -call_shared Produces a dynamic executable. The object created can use shared objects at runtime. This is enabled by default. (C, C++, F77, F90) -elf Produces an ELF output object file. This is the default, and currently the only, file format supported. (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) -n32 Specifies that the object to be linked (and the input objects) are to be new-style, 32-bit objects. (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) -r Retains relocation entries in the output file. Use of this option is strongly discouraged. 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. -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) Layout Options The layout options affect the layout of the object file. They are as follows: -B num Sets the uninitialized data (BSS) segment origin. Specify a hexadecimal number for num. If num is hexadecimal, use a value with no leading 0x, as in this example: -B 40000000 64-bit values can be used. -Bdirect Establishes direct binding information by recording the relationship between each symbol reference and the dependency that provides the definition. The runtime linker uses this information to search directly for the symbol in the associated object rather than to carry out its default symbol search. ld uses the so_locations file from the current directory (in preference to usr/lib if the check_registry or update_registry option is not specified. -d Forces definition of common storage and defines loader-defined symbols even if -r is present. -D num Sets the initialized data segment origin. Specify a hexadecimal number for num with no leading 0x, as in this example: -D 40000000 64-bit values can be used. (C, C++, F77, F90) -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. -elspec file Specifies a file to serve as an ELF layout specification file. This file and its syntax are described in elspec(5). -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. -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) -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. alignval must be both PAGESIZE 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. segtype_roundup=integer Rounds the given segment up to the given 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 about this option, see the opt(5) man page. For an example that shows reordering code regions, see the MIPSpro N32/64 Compiling and Performance Tuning Guide. (C, C++, F77, F90) -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. -noivpad Disables the behavior of the -ivpad option. (C, C++, F77, F90) -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) -T num Sets the text segment origin. If num is hexadecimal, use a value with no leading 0x, as in this example: -T 40000000 64-bit values can be used. (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). -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. Dynamic Linking Options For a complete list of elements that affect runtime DSO search and lookup, as well as dynamic symbol resolution, see the rld(5) man page. The following options affect dynamic linking: -LD_DYNAMIC:rhf_mips_flags=<bit_mask> Allows setting flags in the dynamic section's DT_MIPS_FLAGS record. To see the flags available search /usr/include/elf.h and /usr/include/sys/elf.h for the pattern RHF_. Use this option with caution, if at all. -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. (C, C++, F77, F90) -e epsym Sets the default entry point address for the output file to be that of the symbol epsym. (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 of the referencing executable in addition to the interface version. (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. If the next item on the command line is a DSO the linker marks its entry in the liblist as being exported. That means when someone is linking in this DSO the static linker is told that it can look at the liblist of any of the DSOs in its liblist so marked and use them for symbol resolution. This relieves some of the burden from the end user from having to list all the libraries on their linker command line. (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. It is an error if any of these symbols are also specifically marked as hidden using the -hidden_symbol or -hiddens_file options. See the NOTES section information regarding hiding and exporting defined symbols. (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. It is an error if any of these symbols are also specifically marked as hidden using the -hidden_symbol or -hiddens_file options. See the NOTES section information regarding hiding and exporting defined symbols. (C, C++, F77, F90) -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. (C) -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) -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) -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. It is an error if any of these symbols are also specifically marked as hidden using the -exported_symbol or -export_file options. See the NOTES section information regarding hiding and exporting defined symbols. (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. It is an error if any of these symbols are also specifically marked as hidden using the -exported_symbol or -exports_file options. See the NOTES section information regarding hiding and exporting defined symbols. (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) -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. -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) -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) -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. (C) -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) -no_rqs Marks the object being created as not requickstartable. See rqs(1) for details. -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. If you are linking using the cc(1) command, this option should be passed both to the driver and the linker. Both -no_transitive_link and -Wl,-no_transitive_link should be used. (C, C++, F77, F90) -require_minor Sets the LL_REQUIRE_MINOR flag in the .liblist flags field for shared objects 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) -rpath library_path Adds the library_path to the search path for DSOs. Each library path is appended to the DT_RPATH list of directories at the time the executable or DSO is created. At run time, rld(5) looks for any dependent DSOs using the DT_RPATH list before any LD_LIBRARY_PATH lists. (See the rld(5) man page for details.) 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. Note that the DT_RPATHs of any dependent DSOs are implicitly included in the DT_RPATH of the executable or DSO being created and that any library paths added with -rpath are appended to this initial list. library_path may contain multiple colon-separated paths (for example, dir1:dir2). For more information, see the rld(5) man page. (C, C++, F77, F90) -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) -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) -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) 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: -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. -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. Registry Options The following commands affect SO locations to help insure quickstart DSOs. ' -check_registry registry_file Read registry_file for any layout specifications for the DSO being linked. An error occurs if registry_file doesn't exist. This option does not alter registry_file. (C, C++, F77, F90) -update_registry registry_file Read registry_files for any layout specifications for the DSO being linked. Update registry_file with layout information for the DSO being linked. If registry_file doesn't exist, create it. (C, C++, F77, F90) -create_registry registry_file Create a registry_files for the DSO being linked. This will always overwrite registry_file if it exists and create it if it does not exist. This option instructs the linker not to reference any registry file for layout specifications. (C, C++, F77, F90) Miscellaneous Options The following are miscellaneous options: -_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) -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) Synonym Options The following options are synonyms for other ld options: -a This is a synonym of -non_shared. -ajeop This is a synonym for -allow_jump_at_eop. -dn This is a synonym for -non_shared. (C) -dy This is a synonym for -call_shared. (C) -G If the -_SYSTYPE_SVR4 option has been specified, this option is a synonym for -shared and takes no numerical argument. (C) -h This is a synonym for -soname. -hides_file file This is a synonym for the -hiddens_file option. -none Same as -notall. (C, C++, F77, F90) -o32 This is a synonym for -32. -OPT:reorg_common This is a synonym for -ivpad. -SYSTYPE_SVR4 This is a synonym for -_SYSTYPE_SVR4. -U This is a synonym for -ignore_unresolved. -w This is a synonym for -wall. -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. Obsolete Options The following commands either will be ignored or will cause a warning from the linker. -Bstring Append string to the library names created for the -lx and -klx options when searching for library names. For each directory to be searched the name is first created with the string and if it is not found it is created without the string. Old_ld only. -count Does not do anything. -nocount -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. -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) 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 -Xdebug. The -Xlocaldata option has been replaced by the -Xlocal 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. As of the 7.3.1.3m release, the .dynamic section of the a.out now has entries for the timestamp and checksum. This allows downstream tools such as SpeedShop to determine if data files match the executable or not. This information has always been in DSOs. Note that a recompiled a.out now always has different bits. As of the 7.3.1.3m release, the linker generates some text on its own such as the init and fini function driver. Prior to this, the linker neglected to generate debugging information along with this text, making unwinding in the debugger and exception-handling routines problematic. This has been fixed. There are still problems with unwinding through linker-generated code that has been instrumented for performance evaluation. This will be addressed in future releases. EXPORTING AND HIDING SYMBOLS The linker marks symbols to be either hidden or seen (exported) at runtime by other DSO or the a.out file. The default behavior differs between linking in individual objects as opposed to linking in objects from an archive. This option has no affect on linking with DSOs because it only affects defined symbols in the a.out or DSO being created by the link. The following is the default linker behavior: * Individual objects (.o's) are exported. * Objects from archives are hidden. There are six linker options that affect the hiding or exporting of a defined symbol being linked in the a.out or DSO. Four of these options affect the default global behavior of the linker and are position-independent on the commandline. * -exported_symbol and -exports_file both accumulate a list of symbols to mark as exported. They change the default behavior for all objects whether independent or within an archive as being hidden. * -hidden_symbol and -hiddens_file both accumulate a list of symbols to mark as hidden. They change the default behavior for all objects whether independent or within an archive as being exported. Two of the options are position-dependent and have an effect on the next individual object file or archive in the command line. After that the linker reverts back to the current default. They affect all the global symbols in the affected object with the exception of any specifically listed in the first four options above. They change the default for the next object or archive on the command line. * -exports exports all symbols not explicitly specified to be hidden. * -hides will hide all symbols not explicitly specified to be exported. There are two possible conflicts that can occur with combined use of the above options: * If either -exported_symbol or -exports_file are used in conjunction with -hidden_symbol or -hiddens_file, the default rule reverts to hiding symbols. * If the same symbol is explicitly stated for both exporting or hiding an error is issued. If the user demotes or suppresses the error the behavior will be undefined. It is highly reccomended that the user correct the problem. 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 N32/64 Compiling and Performance Tuning Guide