diff options
Diffstat (limited to 'ld/ld.1')
-rw-r--r-- | ld/ld.1 | 1115 |
1 files changed, 1115 insertions, 0 deletions
@@ -0,0 +1,1115 @@ +.\" Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation +.\" See section COPYING for conditions for redistribution +.TH ld 1 "17 August 1992" "cygnus support" "GNU Development Tools" +.de BP +.sp +.ti \-.2i +\(** +.. + +.SH NAME +ld \- the GNU linker + +.SH SYNOPSIS +.hy 0 +.na +.TP +.B ld +.RB "[\|" \-o " +.I output\c +\&\|] \c +.I objfile\c +\&.\|.\|. +.br +.RB "[\|" \-A\c +.I architecture\c +\&\|] +.RB "[\|" "\-b\ "\c +.I input-format\c +\&\|] +.RB "[\|" \-Bstatic "\|]" +.RB "[\|" \-Bdynamic "\|]" +.RB "[\|" \-Bsymbolic "\|]" +.RB "[\|" "\-c\ "\c +.I commandfile\c +\&\|] +.RB "[\|" \-\-cref "\|]" +.RB "[\|" \-d | \-dc | \-dp\c +\|] +.br +.RB "[\|" "\-defsym\ "\c +.I symbol\c +\& = \c +.I expression\c +\&\|] +.RB "[\|" \-\-demangle "\|]" +.RB "[\|" \-\-no\-demangle "\|]" +.RB "[\|" "\-e\ "\c +.I entry\c +\&\|] +.RB "[\|" \-embedded\-relocs "\|]" +.RB "[\|" \-E "\|]" +.RB "[\|" \-export\-dynamic "\|]" +.RB "[\|" "\-f\ "\c +.I name\c +\&\|] +.RB "[\|" "\-\-auxiliary\ "\c +.I name\c +\&\|] +.RB "[\|" "\-F\ "\c +.I name\c +\&\|] +.RB "[\|" "\-\-filter\ "\c +.I name\c +\&\|] +.RB "[\|" "\-format\ "\c +.I input-format\c +\&\|] +.RB "[\|" \-g "\|]" +.RB "[\|" \-G +.I size\c +\&\|] +.RB "[\|" "\-h\ "\c +.I name\c +\&\|] +.RB "[\|" "\-soname\ "\c +.I name\c +\&\|] +.RB "[\|" \-\-help "\|]" +.RB "[\|" \-i "\|]" +.RB "[\|" \-l\c +.I ar\c +\&\|] +.RB "[\|" \-L\c +.I searchdir\c +\&\|] +.RB "[\|" \-M "\|]" +.RB "[\|" \-Map +.I mapfile\c +\&\|] +.RB "[\|" \-m +.I emulation\c +\&\|] +.RB "[\|" \-n | \-N "\|]" +.RB "[\|" \-noinhibit-exec "\|]" +.RB "[\|" \-no\-keep\-memory "\|]" +.RB "[\|" \-no\-warn\-mismatch "\|]" +.RB "[\|" \-O\c +.I level\c +\&\|] +.RB "[\|" "\-oformat\ "\c +.I output-format\c +\&\|] +.RB "[\|" "\-R\ "\c +.I filename\c +\&\|] +.RB "[\|" \-relax "\|]" +.RB "[\|" \-r | \-Ur "\|]" +.RB "[\|" "\-rpath\ "\c +.I directory\c +\&\|] +.RB "[\|" "\-rpath\-link\ "\c +.I directory\c +\&\|] +.RB "[\|" \-S "\|]" +.RB "[\|" \-s "\|]" +.RB "[\|" \-shared "\|]" +.RB "[\|" \-sort\-common "\|]" +.RB "[\|" "\-split\-by\-reloc\ "\c +.I count\c +\&\|] +.RB "[\|" \-split\-by\-file "\|]" +.RB "[\|" "\-T\ "\c +.I commandfile\c +\&\|] +.RB "[\|" "\-Ttext\ "\c +.I textorg\c +\&\|] +.RB "[\|" "\-Tdata\ "\c +.I dataorg\c +\&\|] +.RB "[\|" "\-Tbss\ "\c +.I bssorg\c +\&\|] +.RB "[\|" \-t "\|]" +.RB "[\|" "\-u\ "\c +.I sym\c +\&] +.RB "[\|" \-V "\|]" +.RB "[\|" \-v "\|]" +.RB "[\|" \-\-verbose "\|]" +.RB "[\|" \-\-version "\|]" +.RB "[\|" \-warn\-common "\|]" +.RB "[\|" \-warn\-constructors "\|]" +.RB "[\|" \-warn\-multiple\-gp "\|]" +.RB "[\|" \-warn\-once "\|]" +.RB "[\|" \-warn\-section\-align "\|]" +.RB "[\|" \-\-whole\-archive "\|]" +.RB "[\|" \-\-no\-whole\-archive "\|]" +.RB "[\|" "\-\-wrap\ "\c +.I symbol\c +\&\|] +.RB "[\|" \-X "\|]" +.RB "[\|" \-x "\|]" +.ad b +.hy 1 +.SH DESCRIPTION +\c +.B ld\c +\& combines a number of object and archive files, relocates +their data and ties up symbol references. Often the last step in +building a new compiled program to run is a call to \c +.B ld\c +\&. + +\c +.B ld\c +\& accepts Linker Command Language files +to provide explicit and total control over the linking process. +This man page does not describe the command language; see the `\|\c +.B ld\c +\|' entry in `\|\c +.B info\c +\|', or the manual +.I +ld: the GNU linker +\&, for full details on the command language and on other aspects of +the GNU linker. + +This version of \c +.B ld\c +\& uses the general purpose BFD libraries +to operate on object files. This allows \c +.B ld\c +\& to read, combine, and +write object files in many different formats\(em\&for example, COFF or +\c +.B a.out\c +\&. Different formats may be linked together to produce any +available kind of object file. You can use `\|\c +.B objdump \-i\c +\|' to get a list of formats supported on various architectures; see +.BR objdump ( 1 ). + +Aside from its flexibility, the GNU linker is more helpful than other +linkers in providing diagnostic information. Many linkers abandon +execution immediately upon encountering an error; whenever possible, +\c +.B ld\c +\& continues executing, allowing you to identify other errors +(or, in some cases, to get an output file in spite of the error). + +The GNU linker \c +.B ld\c +\& is meant to cover a broad range of situations, +and to be as compatible as possible with other linkers. As a result, +you have many choices to control its behavior through the command line, +and through environment variables. + +.SH OPTIONS +The plethora of command-line options may seem intimidating, but in +actual practice few of them are used in any particular context. +For instance, a frequent use of \c +.B ld\c +\& is to link standard Unix +object files on a standard, supported Unix system. On such a system, to +link a file \c +.B hello.o\c +\&: +.sp +.br +$\ ld\ \-o\ output\ /lib/crt0.o\ hello.o\ \-lc +.br +.sp +This tells \c +.B ld\c +\& to produce a file called \c +.B output\c +\& as the +result of linking the file \c +.B /lib/crt0.o\c +\& with \c +.B hello.o\c +\& and +the library \c +.B libc.a\c +\& which will come from the standard search +directories. + +The command-line options to \c +.B ld\c +\& may be specified in any order, and +may be repeated at will. For the most part, repeating an option with a +different argument will either have no further effect, or override prior +occurrences (those further to the left on the command line) of an +option. + +The exceptions\(em\&which may meaningfully be used more than once\(em\&are +\c +.B \-A\c +\&, \c +.B \-b\c +\& (or its synonym \c +.B \-format\c +\&), \c +.B \-defsym\c +\&, +\c +.B \-L\c +\&, \c +.B \-l\c +\&, \c +.B \-R\c +\&, and \c +.B \-u\c +\&. + +The list of object files to be linked together, shown as \c +.I objfile\c +\&, +may follow, precede, or be mixed in with command-line options; save that +an \c +.I objfile\c +\& argument may not be placed between an option flag and +its argument. + +Usually the linker is invoked with at least one object file, but other +forms of binary input files can also be specified with \c +.B \-l\c +\&, +\c +.B \-R\c +\&, and the script command language. If \c +.I no\c +\& binary input +files at all are specified, the linker does not produce any output, and +issues the message `\|\c +.B No input files\c +\|'. + +Option arguments must either follow the option letter without intervening +whitespace, or be given as separate arguments immediately following the +option that requires them. + +.TP +.BI "-A" "architecture" +In the current release of \c +.B ld\c +\&, this option is useful only for the +Intel 960 family of architectures. In that \c +.B ld\c +\& configuration, the +\c +.I architecture\c +\& argument is one of the two-letter names identifying +members of the 960 family; the option specifies the desired output +target, and warns of any incompatible instructions in the input files. +It also modifies the linker's search strategy for archive libraries, to +support the use of libraries specific to each particular +architecture, by including in the search loop names suffixed with the +string identifying the architecture. + +For example, if your \c +.B ld\c +\& command line included `\|\c +.B \-ACA\c +\|' as +well as `\|\c +.B \-ltry\c +\|', the linker would look (in its built-in search +paths, and in any paths you specify with \c +.B \-L\c +\&) for a library with +the names +.sp +.br +try +.br +libtry.a +.br +tryca +.br +libtryca.a +.br +.sp + +The first two possibilities would be considered in any event; the last +two are due to the use of `\|\c +.B \-ACA\c +\|'. + +Future releases of \c +.B ld\c +\& may support similar functionality for +other architecture families. + +You can meaningfully use \c +.B \-A\c +\& more than once on a command line, if +an architecture family allows combination of target architectures; each +use will add another pair of name variants to search for when \c +.B \-l +specifies a library. + +.TP +.BI "\-b " "input-format" +Specify the binary format for input object files that follow this option +on the command line. You don't usually need to specify this, as +\c +.B ld\c +\& is configured to expect as a default input format the most +usual format on each machine. \c +.I input-format\c +\& is a text string, the +name of a particular format supported by the BFD libraries. +\c +.B \-format \c +.I input-format\c +\&\c +\& has the same effect, as does the script command +.BR TARGET . + +You may want to use this option if you are linking files with an unusual +binary format. You can also use \c +.B \-b\c +\& to switch formats explicitly (when +linking object files of different formats), by including +\c +.B \-b \c +.I input-format\c +\&\c +\& before each group of object files in a +particular format. + +The default format is taken from the environment variable +.B GNUTARGET\c +\&. You can also define the input +format from a script, using the command \c +.B TARGET\c +\&. + +.TP +.B \-Bstatic +Do not link against shared libraries. This is only meaningful on +platforms for which shared libraries are supported. + +.TP +.B \-Bdynamic +Link against dynamic libraries. This is only meaningful on platforms +for which shared libraries are supported. This option is normally the +default on such platforms. + +.TP +.B \-Bsymbolic +When creating a shared library, bind references to global symbols to +the definition within the shared library, if any. Normally, it is +possible for a program linked against a shared library to override the +definition within the shared library. This option is only meaningful +on ELF platforms which support shared libraries. + +.TP +.BI "\-c " "commandfile" +Directs \c +.B ld\c +\& to read link commands from the file +\c +.I commandfile\c +\&. These commands will completely override \c +.B ld\c +\&'s +default link format (rather than adding to it); \c +.I commandfile\c +\& must +specify everything necessary to describe the target format. + + +You may also include a script of link commands directly in the command +line by bracketing it between `\|\c +.B {\c +\|' and `\|\c +.B }\c +\|' characters. + +.TP +.B \-\-cref +Output a cross reference table. If a linker map file is being +generated, the cross reference table is printed to the map file. +Otherwise, it is printed on the standard output. + +.TP +.B \-d +.TP +.B \-dc +.TP +.B \-dp +These three options are equivalent; multiple forms are supported for +compatibility with other linkers. Use any of them to make \c +.B ld +assign space to common symbols even if a relocatable output file is +specified (\c +.B \-r\c +\&). The script command +\c +.B FORCE_COMMON_ALLOCATION\c +\& has the same effect. + +.TP +.BI "-defsym " "symbol" "\fR = \fP" expression +Create a global symbol in the output file, containing the absolute +address given by \c +.I expression\c +\&. You may use this option as many +times as necessary to define multiple symbols in the command line. A +limited form of arithmetic is supported for the \c +.I expression\c +\& in this +context: you may give a hexadecimal constant or the name of an existing +symbol, or use \c +.B +\c +\& and \c +.B \-\c +\& to add or subtract hexadecimal +constants or symbols. If you need more elaborate expressions, consider +using the linker command language from a script. + +.TP +.B \-\-demangle +.TP +.B \-\-no\-demangle +These options control whether to demangle symbol names in error +messages and other output. When the linker is told to demangle, it +tries to present symbol names in a readable fashion: it strips leading +underscores if they are used by the object file format, and converts +C++ mangled symbol names into user readable names. The linker will +demangle by default unless the environment variable +.B COLLECT_NO_DEMANGLE +is set. These options may be used to override the default. + +.TP +.BI "-e " "entry"\c +\& +Use \c +.I entry\c +\& as the explicit symbol for beginning execution of your +program, rather than the default entry point. See the `\|\c +.B ld\c +\|' entry in `\|\c +.B info\c +\|' for a +discussion of defaults and other ways of specifying the +entry point. + +.TP +.B \-embedded\-relocs +This option is only meaningful when linking MIPS embedded PIC code, +generated by the +.B \-membedded\-pic +option to the GNU compiler and assembler. It causes the linker to +create a table which may be used at runtime to relocate any data which +was statically initialized to pointer values. See the code in +testsuite/ld-empic for details. + +.TP +.B \-E +.TP +.B \-export\-dynamic +When creating an ELF file, add all symbols to the dynamic symbol table. +Normally, the dynamic symbol table contains only symbols which are used +by a dynamic object. This option is needed for some uses of +.I dlopen. + +.TP +.BI "-f " "name" +.TP +.BI "--auxiliary " "name" +When creating an ELF shared object, set the internal DT_AUXILIARY field +to the specified name. This tells the dynamic linker that the symbol +table of the shared object should be used as an auxiliary filter on the +symbol table of the shared object +.I name. + +.TP +.BI "-F " "name" +.TP +.BI "--filter " "name" +When creating an ELF shared object, set the internal DT_FILTER field to +the specified name. This tells the dynamic linker that the symbol table +of the shared object should be used as a filter on the symbol table of +the shared object +.I name. + +.TP +.BI "\-format " "input\-format" +Synonym for \c +.B \-b\c +\& \c +.I input\-format\c +\&. + +.TP +.B \-g +Accepted, but ignored; provided for compatibility with other tools. + +.TP +.BI "\-G " "size"\c +Set the maximum size of objects to be optimized using the GP register +to +.I size +under MIPS ECOFF. Ignored for other object file formats. + +.TP +.BI "-h " "name" +.TP +.BI "-soname " "name" +When creating an ELF shared object, set the internal DT_SONAME field to +the specified name. When an executable is linked with a shared object +which has a DT_SONAME field, then when the executable is run the dynamic +linker will attempt to load the shared object specified by the DT_SONAME +field rather than the using the file name given to the linker. + +.TP +.B \-\-help +Print a summary of the command-line options on the standard output and exit. +This option and +.B \-\-version +begin with two dashes instead of one +for compatibility with other GNU programs. The other options start with +only one dash for compatibility with other linkers. + +.TP +.B \-i +Perform an incremental link (same as option \c +.B \-r\c +\&). + +.TP +.BI "\-l" "ar"\c +\& +Add an archive file \c +.I ar\c +\& to the list of files to link. This +option may be used any number of times. \c +.B ld\c +\& will search its +path-list for occurrences of \c +.B lib\c +.I ar\c +\&.a\c +\& for every \c +.I ar +specified. + +.TP +.BI "\-L" "searchdir" +This command adds path \c +.I searchdir\c +\& to the list of paths that +\c +.B ld\c +\& will search for archive libraries. You may use this option +any number of times. + +The default set of paths searched (without being specified with +\c +.B \-L\c +\&) depends on what emulation mode \c +.B ld\c +\& is using, and in +some cases also on how it was configured. The +paths can also be specified in a link script with the \c +.B SEARCH_DIR +command. + +.TP +.B \-M +Print (to the standard output file) a link map\(em\&diagnostic information +about where symbols are mapped by \c +.B ld\c +\&, and information on global +common storage allocation. + +.TP +.BI "\-Map " "mapfile"\c +Print to the file +.I mapfile +a link map\(em\&diagnostic information +about where symbols are mapped by \c +.B ld\c +\&, and information on global +common storage allocation. + +.TP +.BI "\-m " "emulation"\c +Emulate the +.I emulation +linker. You can list the available emulations with the +.I \-\-verbose +or +.I \-V +options. This option overrides the compiled-in default, which is the +system for which you configured +.BR ld . + +.TP +.B \-N +specifies readable and writable \c +.B text\c +\& and \c +.B data\c +\& sections. If +the output format supports Unix style magic numbers, the output is +marked as \c +.B OMAGIC\c +\&. + +When you use the `\|\c +.B \-N\c +\&\|' option, the linker does not page-align the +data segment. + +.TP +.B \-n +sets the text segment to be read only, and \c +.B NMAGIC\c +\& is written +if possible. + +.TP +.B \-noinhibit\-exec +Normally, the linker will not produce an output file if it encounters +errors during the link process. With this flag, you can specify that +you wish the output file retained even after non-fatal errors. + +.TP +.B \-no\-keep\-memory +The linker normally optimizes for speed over memory usage by caching +the symbol tables of input files in memory. This option tells the +linker to instead optimize for memory usage, by rereading the symbol +tables as necessary. This may be required if the linker runs out of +memory space while linking a large executable. + +.TP +.B \-no\-warn\-mismatch +Normally the linker will give an error if you try to link together +input files that are mismatched for some reason, perhaps because they +have been compiled for different processors or for different +endiannesses. This option tells the linker that it should silently +permit such possible errors. This option should only be used with +care, in cases when you have taken some special action that ensures +that the linker errors are inappropriate. + +.TP +.BI "\-o " "output" +.I output\c +\& is a name for the program produced by \c +.B ld\c +\&; if this +option is not specified, the name `\|\c +.B a.out\c +\|' is used by default. The +script command \c +.B OUTPUT\c +\& can also specify the output file name. + +.TP +.BI "\-O" "level" +Generate optimized output files. This might use significantly more +time and therefore probably should be enabled only for generating the +final binary. +\c +.I level\c +\& is supposed to be a numeric value. Any value greater than zero enables +the optimizations. + +.TP +.BI "\-oformat " "output\-format" +Specify the binary format for the output object file. +You don't usually need to specify this, as +\c +.B ld\c +\& is configured to produce as a default output format the most +usual format on each machine. \c +.I output-format\c +\& is a text string, the +name of a particular format supported by the BFD libraries. +The script command +.B OUTPUT_FORMAT +can also specify the output format, but this option overrides it. + +.TP +.BI "\-R " "filename" +Read symbol names and their addresses from \c +.I filename\c +\&, but do not +relocate it or include it in the output. This allows your output file +to refer symbolically to absolute locations of memory defined in other +programs. + +.TP +.B \-relax +An option with machine dependent effects. Currently this option is only +supported on the H8/300. + +On some platforms, use this option to perform global optimizations that +become possible when the linker resolves addressing in your program, such +as relaxing address modes and synthesizing new instructions in the +output object file. + +On platforms where this is not supported, `\|\c +.B \-relax\c +\&\|' is accepted, but has no effect. + +.TP +.B \-r +Generates relocatable output\(em\&i.e., generate an output file that can in +turn serve as input to \c +.B ld\c +\&. This is often called \c +.I partial +linking\c +\&. As a side effect, in environments that support standard Unix +magic numbers, this option also sets the output file's magic number to +\c +.B OMAGIC\c +\&. +If this option is not specified, an absolute file is produced. When +linking C++ programs, this option \c +.I will not\c +\& resolve references to +constructors; \c +.B \-Ur\c +\& is an alternative. + +This option does the same as \c +.B \-i\c +\&. + +.TP +.B \-rpath\ \fIdirectory +Add a directory to the runtime library search path. This is used when +linking an ELF executable with shared objects. All +.B \-rpath +arguments are concatenated and passed to the runtime linker, which uses +them to locate shared objects at runtime. The +.B \-rpath +option is also used when locating shared objects which are needed by +shared objects explicitly included in the link; see the description of +the +.B \-rpath\-link +option. If +.B \-rpath +is not used when linking an ELF executable, the contents of the +environment variable +.B LD_RUN_PATH +will be used if it is defined. + +The +.B \-rpath +option may also be used on SunOS. By default, on SunOS, the linker +will form a runtime search path out of all the +.B \-L +options it is given. If a +.B \-rpath +option is used, the runtime search path will be formed exclusively +using the +.B \-rpath +options, ignoring +the +.B \-L +options. This can be useful when using gcc, which adds many +.B \-L +options which may be on NFS mounted filesystems. + +.TP +.B \-rpath\-link\ \fIdirectory +When using ELF or SunOS, one shared library may require another. This +happens when an +.B ld\ \-shared +link includes a shared library as one of the input files. + +When the linker encounters such a dependency when doing a non-shared, +non-relocateable link, it will automatically try to locate the required +shared library and include it in the link, if it is not included +explicitly. In such a case, the +.B \-rpath\-link +option specifies the first set of directories to search. The +.B \-rpath\-link +option may specify a sequence of directory names either by specifying +a list of names separated by colons, or by appearing multiple times. + +If the required shared library is not found, the linker will issue a +warning and continue with the link. + +.TP +.B \-S +Omits debugger symbol information (but not all symbols) from the output file. + +.TP +.B \-s +Omits all symbol information from the output file. + +.TP +.B \-shared +Create a shared library. This is currently only supported on ELF and +SunOS platforms (on SunOS it is not required, as the linker will +automatically create a shared library when there are undefined symbols +and the +.B \-e +option is not used). + +.TP +.B \-sort\-common +Normally, when +.B ld +places the global common symbols in the appropriate output sections, +it sorts them by size. First come all the one byte symbols, then all +the two bytes, then all the four bytes, and then everything else. +This is to prevent gaps between symbols due to +alignment constraints. This option disables that sorting. + +.TP +.B \-split\-by\-reloc\ \fIcount +Trys to creates extra sections in the output file so that no single +output section in the file contains more than +.I count +relocations. +This is useful when generating huge relocatable for downloading into +certain real time kernels with the COFF object file format; since COFF +cannot represent more than 65535 relocations in a single section. +Note that this will fail to work with object file formats which do not +support arbitrary sections. The linker will not split up individual +input sections for redistribution, so if a single input section +contains more than +.I count +relocations one output section will contain that many relocations. + +.TP +.B \-split\-by\-file +Similar to +.B \-split\-by\-reloc +but creates a new output section for each input file. + +.TP +.BI "\-Tbss " "org"\c +.TP +.BI "\-Tdata " "org"\c +.TP +.BI "\-Ttext " "org"\c +Use \c +.I org\c +\& as the starting address for\(em\&respectively\(em\&the +\c +.B bss\c +\&, \c +.B data\c +\&, or the \c +.B text\c +\& segment of the output file. +\c +.I org\c +\& must be a hexadecimal integer. + +.TP +.BI "\-T " "commandfile" +Equivalent to \c +.B \-c \c +.I commandfile\c +\&\c +\&; supported for compatibility with +other tools. + +.TP +.B \-t +Prints names of input files as \c +.B ld\c +\& processes them. + +.TP +.BI "\-u " "sym" +Forces \c +.I sym\c +\& to be entered in the output file as an undefined symbol. +This may, for example, trigger linking of additional modules from +standard libraries. \c +.B \-u\c +\& may be repeated with different option +arguments to enter additional undefined symbols. + +.TP +.B \-Ur +For anything other than C++ programs, this option is equivalent to +\c +.B \-r\c +\&: it generates relocatable output\(em\&i.e., an output file that can in +turn serve as input to \c +.B ld\c +\&. When linking C++ programs, \c +.B \-Ur +.I will\c +\& resolve references to constructors, unlike \c +.B \-r\c +\&. + +.TP +.B \-\-verbose +Display the version number for \c +.B ld +and list the supported emulations. +Display which input files can and can not be opened. + +.TP +.B \-v, \-V +Display the version number for \c +.B ld\c +\&. +The +.B \-V +option also lists the supported emulations. + +.TP +.B \-\-version +Display the version number for \c +.B ld +and exit. + +.TP +.B \-warn\-common +Warn when a common symbol is combined with another common symbol or with +a symbol definition. Unix linkers allow this somewhat sloppy practice, +but linkers on some other operating systems do not. This option allows +you to find potential problems from combining global symbols. + +.TP +.B \-warn\-constructors +Warn if any global constructors are used. This is only useful for a +few object file formats. For formats like COFF or ELF, the linker can +not detect the use of global constructors. + +.TP +.B \-warn\-multiple\-gp +Warn if the output file requires multiple global-pointer values. This +option is only meaningful for certain processors, such as the Alpha. + +.TP +.B \-warn\-once +Only warn once for each undefined symbol, rather than once per module +which refers to it. + +.TP +.B \-warn\-section\-align +Warn if the address of an output section is changed because of +alignment. Typically, the alignment will be set by an input section. +The address will only be changed if it not explicitly specified; that +is, if the SECTIONS command does not specify a start address for the +section. + +.TP +.B \-\-whole\-archive +For each archive mentioned on the command line after the +.B \-\-whole\-archive +option, include every object file in the archive in the link, rather +than searching the archive for the required object files. This is +normally used to turn an archive file into a shared library, forcing +every object to be included in the resulting shared library. + +.TP +.B \-\-no\-whole\-archive +Turn off the effect of the +.B \-\-whole\-archive +option for archives which appear later on the command line. + +.TP +.BI "--wrap " "symbol" +Use a wrapper function for +.I symbol. +Any undefined reference to +.I symbol +will be resolved to +.BI "__wrap_" "symbol". +Any undefined reference to +.BI "__real_" "symbol" +will be resolved to +.I symbol. + +.TP +.B \-X +Delete all temporary local symbols. For most targets, this is all local +symbols whose names begin with `\|\c +.B L\c +\|'. + +.TP +.B \-x +Delete all local symbols. + +.PP + +.SH ENVIRONMENT +\c +You can change the behavior of +.B ld\c +\& with the environment variable \c +.B GNUTARGET\c +\&. + +\c +.B GNUTARGET\c +\& determines the input-file object format if you don't +use \c +.B \-b\c +\& (or its synonym \c +.B \-format\c +\&). Its value should be one +of the BFD names for an input format. If there is no +\c +.B GNUTARGET\c +\& in the environment, \c +.B ld\c +\& uses the natural format +of the host. If \c +.B GNUTARGET\c +\& is set to \c +.B default\c +\& then BFD attempts to discover the +input format by examining binary input files; this method often +succeeds, but there are potential ambiguities, since there is no method +of ensuring that the magic number used to flag object-file formats is +unique. However, the configuration procedure for BFD on each system +places the conventional format for that system first in the search-list, +so ambiguities are resolved in favor of convention. + +.PP + +.SH "SEE ALSO" + +.BR objdump ( 1 ) +.br +.br +.RB "`\|" ld "\|' and `\|" binutils "\|'" +entries in +.B info\c +.br +.I +ld: the GNU linker\c +, Steve Chamberlain and Roland Pesch; +.I +The GNU Binary Utilities\c +, Roland H. Pesch. + +.SH COPYING +Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc. +.PP +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. +.PP +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. +.PP +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be included in +translations approved by the Free Software Foundation instead of in +the original English. |