diff options
author | Roland Pesch <pesch@cygnus> | 1992-08-17 18:28:26 +0000 |
---|---|---|
committer | Roland Pesch <pesch@cygnus> | 1992-08-17 18:28:26 +0000 |
commit | 0e166a63532ff1c439ffffde549c54312467432a (patch) | |
tree | 1787dab8704931b4adffaa5a1713dc8ea9c4fae9 /ld/ld.1 | |
parent | 3ae49aef48b0518b5d83babd258fded455fbbadc (diff) | |
download | gdb-0e166a63532ff1c439ffffde549c54312467432a.zip gdb-0e166a63532ff1c439ffffde549c54312467432a.tar.gz gdb-0e166a63532ff1c439ffffde549c54312467432a.tar.bz2 |
Thanks to Zoo watchfulness:
(1) reflect current name of linker (now "ld", not "gld");
(2) fill in missing portion of a reference to full manual;
(3) fix old random typo spotted while proofing above.
Diffstat (limited to 'ld/ld.1')
-rw-r--r-- | ld/ld.1 | 1048 |
1 files changed, 1048 insertions, 0 deletions
@@ -0,0 +1,1048 @@ +.\" Copyright (c) 1991, 1992 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 objfiles\c +\&.\|.\|. +.br +.RB "[\|" \-A\c +.I architecture\c +\&\|] +.RB "[\|" "\-b\ "\c +.I input-format\c +\&\|] +.RB "[\|" \-Bstatic "\|]" +.RB "[\|" "\-c\ "\c +.I commandfile\c +\&\|] +.RB "[\|" \-d | \-dc | \-dp\c +\|] +.br +.RB "[\|" "\-defsym\ "\c +.I symbol\c +\& = \c +.I expression\c +\&\|] +.RB "[\|" "\-e\ "\c +.I entry\c +\&\|] +.RB "[\|" \-F "\|]" +.RB "[\|" "\-F\ "\c +.I format\c +\&\|] +.RB "[\|" "\-format\ "\c +.I input-format\c +\&\|] +.RB "[\|" \-g "\|]" +.RB "[\|" \-i "\|]" +.RB "[\|" \-l\c +.I ar\c +\&\|] +.RB "[\|" \-L\c +.I searchdir\c +\&\|] +.RB "[\|" \-M | \-m "\|]" +.RB "[\|" \-n | \-N "\|]" +.RB "[\|" \-noinhibit-exec "\|]" +.RB "[\|" "\-R\ "\c +.I filename\c +\&\|] +.RB "[\|" \-relax "\|]" +.RB "[\|" \-r | \-Ur "\|]" +.RB "[\|" \-S "\|]" +.RB "[\|" \-s "\|]" +.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 "[\|" \-X "\|]" +.RB "[\|" \-x "\|]" +.RB "[\|" { \c +.I script\c +.BR } "\|]" +.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 objfiles\c +\&, +may follow, precede, or be mixed in with command-line options; save that +an \c +.I objfiles\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 +.IR "objfiles" .\|.\|. +The object files \c +.I objfiles\c +\& to be linked. + +.TP +.BI "-A" "architecture"\c +\& +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\c +\& +specifies a library. + +.TP +.BI "-b " "input-format"\c +\& +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. + +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 +This flag is accepted for command-line compatibility with the SunOS linker, +but has no effect on \c +.B ld\c +\&. + +.TP +.BI "-c " "commandfile"\c +\& +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 \-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\c +\& +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"\c +\& = \c +.I expression\c +\& +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 +.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. for a +discussion of defaults and other ways of specifying the +entry point. + +.TP +.B \-F +.TP +.BI "-F" "format"\c +\& +Some older linkers used this option throughout a compilation toolchain +for specifying object-file format for both input and output object +files. \c +.B ld\c +\&'s mechanisms (the \c +.B \-b\c +\& or \c +.B \-format\c +\& options +for input files, the \c +.B TARGET\c +\& command in linker scripts for output +files, the \c +.B GNUTARGET\c +\& environment variable) are more flexible, but +but it accepts (and ignores) the \c +.B \-F\c +\& option flag for compatibility +with scripts written to call the old linker. + +.TP +.BI "-format " "input-format"\c +\& +Synonym for \c +.B \-b\c +\& \c +.I input-format\c +\&. + +.TP +.B \-g +Accepted, but ignored; provided for compatibility with other tools. + +.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\c +\& +specified. + +.TP +.BI "-L" "searchdir"\c +\& +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\c +\& +command. + +.TP +.B \-M +.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 +.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 +.BI "-o " "output"\c +\& +.I output\c +\& +\c +.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 "-R " "filename"\c +\& +.I file\c +\& +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 \-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 +.BI "{ " "script" " }" +You can, if you wish, include a script of linker commands directly in +the command line instead of referring to it via an input file. When the +character `\|\c +.B {\c +\|' occurs on the command line, the linker switches to +interpreting the command language until the end of the list of commands +is reached\(em\&flagged with a closing brace `\|\c +.B }\c +\|'. Other command-line +options will not be recognized while parsing the script. +See the `\|\c +.B ld\c +\|' entry in `\|\c +.B info\c +\|', or the manual +.I +ld: the GNU linker +\&, for a description of the command language. + +.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 textorg\c +\& must be a hexadecimal integer. + +.TP +.BI "-T " "commandfile"\c +\& +.TP +.BI "-T" "commandfile"\c +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\c +\& +\c +.I will\c +\& resolve references to constructors, unlike \c +.B \-r\c +\&. + +.TP +.B \-v +Display the version number for \c +.B ld\c +\&. + +.TP +.B \-X +If \c +.B \-s\c +\& or \c +.B \-S\c +\& is also specified, delete only local symbols +beginning with `\|\c +.B L\c +\|'. + +.TP +.B \-x +If \c +.B \-s\c +\& or \c +.B \-S\c +\& is also specified, delete all local symbols, +not just those beginning with `\|\c +.B L\c +\|'. + +.PP + +.SH ENVIRONMENT +\c +.B ld\c +\& always consults two environment variables: \c +.B GNUTARGET\c +\& +and \c +.B LDEMULATION\c +\&. Depending on the setting of the latter, other +environment variables may be used as well. + +\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. + +\c +.B LDEMULATION\c +\& controls some aspects of \c +.B ld\c +\&'s dominant +personality. Although \c +.B ld\c +\& is flexible enough to permit its use +in many contexts regardless of configuration, you can use this variable +to make it act more like one or another older linker by default. + +In particular, the value of \c +.B LDEMULATION\c +\& controls what default +linker script is used (thereby controlling the default input and output +formats; ; what default paths are searched for +archive libraries; and in some cases whether additional linker script +commands are available. + +Here is the current set of emulations available: + +.TP +.B LDEMULATION=gld +Emulate the older GNU linker. When this emulation is selected, the +default library search paths are +.sp +.br +/lib +.br +/usr/lib +.br +/usr/local/lib/lib +.br +.sp + +The default output format is set to \c +.B a.out-generic-big\c +\&, and the +default machine is the system's configured BFD default. + +.TP +.B LDEMULATION=gld68k +A variant of the \c +.B gld\c +\& emulation; only differs in specifically +setting the default BFD machine as \c +.B m68k\c +\&. + +.TP +.B LDEMULATION=gld960 +Emulate the Intel port of the older \c +.B gld\c +\& for the i960 +architectures. The default library search paths are taken from two +other environment variables, \c +.B G960LIB\c +\& and \c +.B G960BASE\c +\&. The +default architecture is \c +.B i960\c +\&. The default output format is set +to \c +.B b.out.big\c +\&, and in fact the default output file name (if +\c +.B \-o\c +\& is not specified) is \c +.B b.out\c +\&, to reflect this variant +format, for this emulation. + +This emulation can behave slightly differently depending on the setting +of the \c +.B ld\c +\& compile-time switch \c +.B GNU960\c +\&. If \c +.B ld\c +\& is +compiled with \c +.B GNU960\c +\& defined, then an additional environment +variable\(em\&\c +.B GNUTARGET\c +\&\(em\&is available; its value, if available, +specifies some other default output format than \c +.B b.out.big\c +\&. + +.TP +.B LDEMULATION=gldm88kbcs +Sets the output format to \c +.B m88kbcs\c +\& and the architecture to +\c +.B m88k\c +\&. Default library search paths are +.sp +.br +/lib +.br +/usr/lib +.br +/usr/local/lib +.br +.sp + +.TP +.B LDEMULATION=lnk960 +Emulate the Intel linker \c +.B lnk960\c +\&. The default output format is +\c +.B coff-Intel-big\c +\&. With this emulation, \c +.B ld\c +\& +supports the additional script commands \c +.B HLL\c +\& and \c +.B SYSLIB\c +\& for +specification of library archives. This is the only emulation with +extensive support for the \c +.B \-A\c +\& (architecture) command-line option. +By default, the architecture \c +.B CORE\c +\& is assumed, but you can choose +additional features from the i960 architecture family by using one of +the following with \c +.B \-A\c +\& (or by using the \c +.B OUTPUT_ARCH\c +\& command +from a script): +.sp +.br +CORE +.br +KB +.br +SB +.br +MC +.br +XA +.br +CA +.br +KA +.br +SA +.br +.sp + +The default libraries are chosen with some attention to the architecture +selected; the core library `\|\c +.B cg\c +\|' is always included, but the library +\c +.B fpg\c +\& is also used if you've specified any of the architectures +\c +.B KA\c +\&, \c +.B SA\c +\&, or \c +.B CA\c +\&. + +Like \c +.B gld960\c +\&, this emulation uses additional environment variables +to set the default library search paths. Also like \c +.B gld960\c +\&, the +behavior of this emulation is slightly different depending on whether +\c +.B ld\c +\& itself was compiled with \c +.B GNU960\c +\& defined. + +If your \c +.B ld\c +\& was compiled with \c +.B GNU960\c +\& defined, the default +paths are taken from all three of \c +.B G960LIB\c +\&, \c +.B G960BASE\c +\&, and +\c +.B I960BASE\c +\&. For the first two, paths you supply are automatically +suffixed with `\|\c +.B /lib/libcoff\c +\|'; for the last, your path is +automatically suffixed with `\|\c +.B /lib\c +\|'. + +If your \c +.B ld\c +\& was \c +.I not\c +\& compiled with \c +.B GNU960\c +\& defined, +the default paths are taken from \c +.B I960BASE\c +\&, and \c +.B G960BASE\c +\& is +only consulted if \c +.B I960BASE\c +\& is undefined. In this case +\c +.B G960LIB\c +\& is not used at all. + +.TP +.B LDEMULATION=vanilla +This is the least specific setting for \c +.B ld\c +\&. You can set +\c +.B LDEMULATION=vanilla\c +\& to disable emulation of other linkers. This +setting makes \c +.B ld\c +\& take the default machine from the BFD +configuration on your system; \c +.B a.out-generic-big\c +\& is the default +target. No other defaults are specified. + +.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, 1992 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. |