diff options
author | K. Richard Pixley <rich@cygnus> | 1992-12-08 04:59:31 +0000 |
---|---|---|
committer | K. Richard Pixley <rich@cygnus> | 1992-12-08 04:59:31 +0000 |
commit | 43bbd567f2d928b2628e508ee9c75a3920e26b4d (patch) | |
tree | 21f1ab246e1a3f963e73c3662bc1d44f591349a1 /ld/gld.1 | |
parent | a362ee23634a2f9ce9642eab09592e8ff6ae509b (diff) | |
download | gdb-43bbd567f2d928b2628e508ee9c75a3920e26b4d.zip gdb-43bbd567f2d928b2628e508ee9c75a3920e26b4d.tar.gz gdb-43bbd567f2d928b2628e508ee9c75a3920e26b4d.tar.bz2 |
recording file death
Diffstat (limited to 'ld/gld.1')
-rw-r--r-- | ld/gld.1 | 1044 |
1 files changed, 0 insertions, 1044 deletions
diff --git a/ld/gld.1 b/ld/gld.1 deleted file mode 100644 index 2579063..0000000 --- a/ld/gld.1 +++ /dev/null @@ -1,1044 +0,0 @@ -.\" Copyright (c) 1991, 1992 Free Software Foundation -.\" See section COPYING for conditions for redistribution -.TH gld 1 "23 January 1992" "cygnus support" "GNU Development Tools" -.de BP -.sp -.ti \-.2i -\(** -.. - -.SH NAME -gld \- the GNU linker - -.SH SYNOPSIS -.hy 0 -.na -.TP -.B gld -.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 gld\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 gld\c -\&. - -\c -.B gld\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 -gld: the GNU linker -\&, for full details on the command language and on other aspects of -the GNU linker. - -This version of \c -.B gld\c -\& uses the general purpose BFD libraries -to operate on object files. This allows \c -.B gld\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 gld\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 gld\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 gld\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 -$\ gld\ \-o\ output\ /lib/crt0.o\ hello.o\ \-lc -.br -.sp -This tells \c -.B gld\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 gld\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 gld\c -\&, this option is useful only for the -Intel 960 family of architectures. In that \c -.B gld\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 gld\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 gld\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 gld\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 gld\c -\&. - -.TP -.BI "-c " "commandfile"\c -\& -Directs \c -.B gld\c -\& to read link commands from the file -\c -.I commandfile\c -\&. These commands will completely override \c -.B gld\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 gld\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 gld\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 gld\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 gld\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. -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"\c -\& -.I sym\c -\& -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 gld\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 gld\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 gld\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 gld\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 gld\c -\&'s dominant -personality. Although \c -.B gld\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 gld\c -\& compile-time switch \c -.B GNU960\c -\&. If \c -.B gld\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 gld\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 gld\c -\& itself was compiled with \c -.B GNU960\c -\& defined. - -If your \c -.B gld\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 gld\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 gld\c -\&. You can set -\c -.B LDEMULATION=vanilla\c -\& to disable emulation of other linkers. This -setting makes \c -.B gld\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 -gld: 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. |