--- /dev/null
+.\" Copyright (c) 1991 Free Software Foundation
+.\" See section COPYING for conditions for redistribution
+.\" $Id$
+.TH gld 1 "5 November 1991" "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 "\|]"
+.RB "[\|" \-noinhibit-exec "\|]"
+.RB "[\|" "\-R\ "\c
+.I filename\c
+\&\|]
+.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
+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 \-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 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.
projects / binutils-gdb.git / commitdiff