-.\" 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 objfile\c
-\&.\|.\|.
+.\" Automatically generated by Pod::Man version 1.02
+.\" Tue May 22 15:43:56 2001
+.\"
+.\" Standard preamble:
+.\" ======================================================================
+.de Sh \" Subsection heading
.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
-\|]
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Ip \" List item
.br
-.RB "[\|" "\-defsym\ "\c
-.I symbol\c
-\& = \c
-.I expression\c
-\&\|]
-.RB "[\|" "\-e\ "\c
-.I entry\c
-\&\|]
-.RB "[\|" \-embedded\-relocs "\|]"
-.RB "[\|" \-F "\|]"
-.RB "[\|" "\-F\ "\c
-.I format\c
-\&\|]
-.RB "[\|" "\-format\ "\c
-.I input-format\c
-\&\|]
-.RB "[\|" \-g "\|]"
-.RB "[\|" \-G\c
-.I size\c
-\&\|]
-.RB "[\|" \-\-help "\|]"
-.RB "[\|" \-i "\|]"
-.RB "[\|" \-l\c
-.I ar\c
-\&\|]
-.RB "[\|" \-L\c
-.I searchdir\c
-\&\|]
-.RB "[\|" \-M "\|]"
-.RB "[\|" \-Map\c
-.I mapfile\c
-\&\|]
-.RB "[\|" \-m\c
-.I emulation\c
-\&\|]
-.RB "[\|" \-n | \-N "\|]"
-.RB "[\|" \-noinhibit-exec "\|]"
-.RB "[\|" "\-oformat\ "\c
-.I output-format\c
-\&\|]
-.RB "[\|" "\-R\ "\c
-.I filename\c
-\&\|]
-.RB "[\|" \-relax "\|]"
-.RB "[\|" \-r | \-Ur "\|]"
-.RB "[\|" \-S "\|]"
-.RB "[\|" \-s "\|]"
-.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\-once "\|]"
-.RB "[\|" \-\-whole\-archive "\|]"
-.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
-\&.
+.ie \\n(.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
-\c
-.B ld\c
-\& accepts Linker Command Language files
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
+.\" to do unbreakable dashes and therefore won't be available. \*(C` and
+.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` `
+. ds C' '
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr
+.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
+.\" index entries marked with X<> in POD. Of course, you'll have to process
+.\" the output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+. .
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it
+.\" makes way too many mistakes in technical documents.
+.hy 0
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+.bd B 3
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ======================================================================
+.\"
+.IX Title "LD 1"
+.TH LD 1 "binutils-2.11.90" "2001-05-22" "GNU"
+.UC
+.SH "NAME"
+ld \- Using \s-1LD\s0, the \s-1GNU\s0 linker
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+ld [ options ] objfile...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\f(CW\*(C`ld\*(C'\fR combines a number of object and archive files, relocates
+their data and ties up symbol references. Usually the last step in
+compiling a program is to run \f(CW\*(C`ld\*(C'\fR.
+.PP
+\&\f(CW\*(C`ld\*(C'\fR accepts Linker Command Language files written in
+a superset of \s-1AT&T\s0's Link Editor Command Language syntax,
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
+.PP
+This man page does not describe the command language; see the
+\&\f(CW\*(C`ld\*(C'\fR entry in \f(CW\*(C`info\*(C'\fR, or the manual
+ld: the \s-1GNU\s0 linker, for full details on the command language and
+on other aspects of the \s-1GNU\s0 linker.
+.PP
+This version of \f(CW\*(C`ld\*(C'\fR uses the general purpose \s-1BFD\s0 libraries
+to operate on object files. This allows \f(CW\*(C`ld\*(C'\fR to read, combine, and
+write object files in many different formats\-\-\-for example, \s-1COFF\s0 or
+\&\f(CW\*(C`a.out\*(C'\fR. Different formats may be linked together to produce any
+available kind of object file.
+.PP
+Aside from its flexibility, the \s-1GNU\s0 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
+\&\f(CW\*(C`ld\*(C'\fR 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,
+.PP
+The \s-1GNU\s0 linker \f(CW\*(C`ld\*(C'\fR 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
+you have many choices to control its behavior.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+The linker supports a plethora of command-line options, but in actual
+practice few of them are used in any particular context.
+For instance, a frequent use of \f(CW\*(C`ld\*(C'\fR 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
+link a file \f(CW\*(C`hello.o\*(C'\fR:
+.PP
+.Vb 1
+\& ld -o I<output> /lib/crt0.o hello.o -lc
+.Ve
+This tells \f(CW\*(C`ld\*(C'\fR to produce a file called \fIoutput\fR as the
+result of linking the file \f(CW\*(C`/lib/crt0.o\*(C'\fR with \f(CW\*(C`hello.o\*(C'\fR and
+the library \f(CW\*(C`libc.a\*(C'\fR, which will come from the standard search
+directories. (See the discussion of the \fB\-l\fR option below.)
+.PP
+Some of the command-line options to \f(CW\*(C`ld\*(C'\fR may be specified at any
+point in the command line. However, options which refer to files, such
+as \fB\-l\fR or \fB\-T\fR, cause the file to be read at the point at
+which the option appears in the command line, relative to the object
+files and other file options. Repeating non-file options 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
+occurrences (those further to the left on the command line) of that
+option. Options which may be meaningfully specified more than once are
+noted in the descriptions below.
+.PP
+Non-option arguments are object files or archives which are to be linked
+together. They may follow, precede, or be mixed in with command-line
+options, except that an object file argument may not be placed between
+an option and its argument.
+.PP
+Usually the linker is invoked with at least one object file, but you can
+specify other forms of binary input files using \fB\-l\fR, \fB\-R\fR,
+and the script command language. If \fIno\fR binary input files at all
+are specified, the linker does not produce any output, and issues the
+message \fBNo input files\fR.
+.PP
+If the linker can not recognize the format of an object file, it will
+assume that it is a linker script. A script specified in this way
+augments the main linker script used for the link (either the default
+linker script or the one specified by using \fB\-T\fR). This feature
+permits the linker to link against a file which appears to be an object
+or an archive, but actually merely defines some symbol values, or uses
+\&\f(CW\*(C`INPUT\*(C'\fR or \f(CW\*(C`GROUP\*(C'\fR to load other objects. Note that
+specifying a script in this way should only be used to augment the main
+linker script; if you want to use some command that logically can only
+appear once, such as the \f(CW\*(C`SECTIONS\*(C'\fR or \f(CW\*(C`MEMORY\*(C'\fR command, you
+must replace the default linker script using the \fB\-T\fR option.
+.PP
+For options whose names are a single letter,
+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"\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
+.PP
+For options whose names are multiple letters, either one dash or two can
+precede the option name; for example, \fB\-trace-symbol\fR and
+\&\fB\*(--trace-symbol\fR are equivalent. Note \- there is one exception to
+this rule. Multiple letter options that start with a lower case 'o' can
+only be preceeded by two dashes. This is to reduce confusion with the
+\&\fB\-o\fR option. So for example \fB\-omagic\fR sets the output file
+name to \fBmagic\fR whereas \fB\*(--omagic\fR sets the \s-1NMAGIC\s0 flag on the
+output.
+.PP
+Arguments to multiple-letter options must either be separated from the
+option name by an equals sign, or be given as separate arguments
+immediately following the option that requires them. For example,
+\&\fB\*(--trace-symbol foo\fR and \fB\*(--trace-symbol=foo\fR are equivalent.
+Unique abbreviations of the names of multiple-letter options are
+accepted.
+.PP
+Note \- if the linker is being invoked indirectly, via a compiler driver
+(eg \fBgcc\fR) then all the linker command line options should be
+prefixed by \fB\-Wl,\fR (or whatever is appropriate for the particular
+compiler driver) like this:
+.PP
+.Vb 1
+\& gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
+.Ve
+This is important, because otherwise the compiler driver program may
+silently drop the linker options, resulting in a bad link.
+.PP
+Here is a table of the generic command line switches accepted by the \s-1GNU\s0
+linker:
+.Ip "\f(CW\*(C`\-a\f(CIkeyword\f(CW\*(C'\fR" 4
+.IX Item "-akeyword"
+This option is supported for \s-1HP/UX\s0 compatibility. The \fIkeyword\fR
+argument must be one of the strings \fBarchive\fR, \fBshared\fR, or
+\&\fBdefault\fR. \fB\-aarchive\fR is functionally equivalent to
+\&\fB\-Bstatic\fR, and the other two keywords are functionally equivalent
+to \fB\-Bdynamic\fR. This option may be used any number of times.
+.Ip "\f(CW\*(C`\-A\f(CIarchitecture\f(CW\*(C'\fR" 4
+.IX Item "-Aarchitecture"
+.Ip "\f(CW\*(C`\-\-architecture=\f(CIarchitecture\f(CW\*(C'\fR" 4
+.IX Item "--architecture=architecture"
+In the current release of \f(CW\*(C`ld\*(C'\fR, this option is useful only for the
+Intel 960 family of architectures. In that \f(CW\*(C`ld\*(C'\fR configuration, the
+\&\fIarchitecture\fR argument identifies the particular architecture in
+the 960 family, enabling some safeguards and modifying the
+archive-library search path.
+.Sp
+Future releases of \f(CW\*(C`ld\*(C'\fR 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, as does the script command
-.BR TARGET .
-
+.Ip "\f(CW\*(C`\-b \f(CIinput\-format\f(CW\*(C'\fR" 4
+.IX Item "-b input-format"
+.Ip "\f(CW\*(C`\-\-format=\f(CIinput\-format\f(CW\*(C'\fR" 4
+.IX Item "--format=input-format"
+\&\f(CW\*(C`ld\*(C'\fR may be configured to support more than one kind of object
+file. If your \f(CW\*(C`ld\*(C'\fR is configured this way, you can use the
+\&\fB\-b\fR option to specify the binary format for input object files
+that follow this option on the command line. Even when \f(CW\*(C`ld\*(C'\fR is
+configured to support alternative object formats, you don't usually need
+to specify this, as \f(CW\*(C`ld\*(C'\fR should be configured to expect as a
+default input format the most usual format on each machine.
+\&\fIinput-format\fR is a text string, the name of a particular format
+supported by the \s-1BFD\s0 libraries. (You can list the available binary
+formats with \fBobjdump \-i\fR.)
+.Sp
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
+binary format. You can also use \fB\-b\fR 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.
-
+\&\fB\-b\fR \fIinput-format\fR before each group of object files in a
+particular format.
+.Sp
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
+\&\f(CW\*(C`GNUTARGET\*(C'\fR.
+.Sp
+You can also define the input format from a script, using the command
+\&\f(CW\*(C`TARGET\*(C'\fR;
+.Ip "\f(CW\*(C`\-c \f(CIMRI\-commandfile\f(CW\*(C'\fR" 4
+.IX Item "-c MRI-commandfile"
+.Ip "\f(CW\*(C`\-\-mri\-script=\f(CIMRI\-commandfile\f(CW\*(C'\fR" 4
+.IX Item "--mri-script=MRI-commandfile"
+For compatibility with linkers produced by \s-1MRI\s0, \f(CW\*(C`ld\*(C'\fR accepts script
+files written in an alternate, restricted command language, described in
+the \s-1MRI\s0 Compatible Script Files section of \s-1GNU\s0 ld documentation.
+Introduce \s-1MRI\s0 script files with
+the option \fB\-c\fR; use the \fB\-T\fR option to run linker
+scripts written in the general-purpose \f(CW\*(C`ld\*(C'\fR scripting language.
+If \fIMRI-cmdfile\fR does not exist, \f(CW\*(C`ld\*(C'\fR looks for it in the directories
+specified by any \fB\-L\fR options.
+.Ip "\f(CW\*(C`\-d\*(C'\fR" 4
+.IX Item "-d"
+.Ip "\f(CW\*(C`\-dc\*(C'\fR" 4
+.IX Item "-dc"
+.Ip "\f(CW\*(C`\-dp\*(C'\fR" 4
+.IX Item "-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
-\&
+compatibility with other linkers. They assign space to common symbols
+even if a relocatable output file is specified (with \fB\-r\fR). The
+script command \f(CW\*(C`FORCE_COMMON_ALLOCATION\*(C'\fR has the same effect.
+.Ip "\f(CW\*(C`\-e \f(CIentry\f(CW\*(C'\fR" 4
+.IX Item "-e entry"
+.Ip "\f(CW\*(C`\-\-entry=\f(CIentry\f(CW\*(C'\fR" 4
+.IX Item "--entry=entry"
+Use \fIentry\fR as the explicit symbol for beginning execution of your
+program, rather than the default entry point. If there is no symbol
+named \fIentry\fR, the linker will try to parse \fIentry\fR as a number,
+and use that as the entry address (the number will be interpreted in
+base 10; you may use a leading \fB0x\fR for base 16, or a leading
+\&\fB0\fR for base 8).
+.Ip "\f(CW\*(C`\-E\*(C'\fR" 4
+.IX Item "-E"
+.Ip "\f(CW\*(C`\-\-export\-dynamic\*(C'\fR" 4
+.IX Item "--export-dynamic"
+When creating a dynamically linked executable, add all symbols to the
+dynamic symbol table. The dynamic symbol table is the set of symbols
+which are visible from dynamic objects at run time.
+.Sp
+If you do not use this option, the dynamic symbol table will normally
+contain only those symbols which are referenced by some dynamic object
+mentioned in the link.
+.Sp
+If you use \f(CW\*(C`dlopen\*(C'\fR to load a dynamic object which needs to refer
+back to the symbols defined by the program, rather than some other
+dynamic object, then you will probably need to use this option when
+linking the program itself.
+.Ip "\f(CW\*(C`\-EB\*(C'\fR" 4
+.IX Item "-EB"
+Link big-endian objects. This affects the default output format.
+.Ip "\f(CW\*(C`\-EL\*(C'\fR" 4
+.IX Item "-EL"
+Link little-endian objects. This affects the default output format.
+.Ip "\f(CW\*(C`\-f\*(C'\fR" 4
+.IX Item "-f"
+.Ip "\f(CW\*(C`\-\-auxiliary \f(CIname\f(CW\*(C'\fR" 4
+.IX Item "--auxiliary name"
+When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_AUXILIARY\s0 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 \fIname\fR.
+.Sp
+If you later link a program against this filter object, then, when you
+run the program, the dynamic linker will see the \s-1DT_AUXILIARY\s0 field. If
+the dynamic linker resolves any symbols from the filter object, it will
+first check whether there is a definition in the shared object
+\&\fIname\fR. If there is one, it will be used instead of the definition
+in the filter object. The shared object \fIname\fR need not exist.
+Thus the shared object \fIname\fR may be used to provide an alternative
+implementation of certain functions, perhaps for debugging or for
+machine specific performance.
+.Sp
+This option may be specified more than once. The \s-1DT_AUXILIARY\s0 entries
+will be created in the order in which they appear on the command line.
+.Ip "\f(CW\*(C`\-F \f(CIname\f(CW\*(C'\fR" 4
+.IX Item "-F name"
+.Ip "\f(CW\*(C`\-\-filter \f(CIname\f(CW\*(C'\fR" 4
+.IX Item "--filter name"
+When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_FILTER\s0 field to
+the specified name. This tells the dynamic linker that the symbol table
+of the shared object which is being created should be used as a filter
+on the symbol table of the shared object \fIname\fR.
+.Sp
+If you later link a program against this filter object, then, when you
+run the program, the dynamic linker will see the \s-1DT_FILTER\s0 field. The
+dynamic linker will resolve symbols according to the symbol table of the
+filter object as usual, but it will actually link to the definitions
+found in the shared object \fIname\fR. Thus the filter object can be
+used to select a subset of the symbols provided by the object
+\&\fIname\fR.
+.Sp
+Some older linkers used the \f(CW\*(C`\-F\*(C'\fR option throughout a compilation
+toolchain for specifying object-file format for both input and output
+object files. The \s-1GNU\s0 linker uses other mechanisms for this
+purpose: the \f(CW\*(C`\-b\*(C'\fR, \f(CW\*(C`\-\-format\*(C'\fR, \f(CW\*(C`\-\-oformat\*(C'\fR options, the
+\&\f(CW\*(C`TARGET\*(C'\fR command in linker scripts, and the \f(CW\*(C`GNUTARGET\*(C'\fR
+environment variable. The \s-1GNU\s0 linker will ignore the \f(CW\*(C`\-F\*(C'\fR
+option when not creating an \s-1ELF\s0 shared object.
+.Ip "\f(CW\*(C`\-fini \f(CIname\f(CW\*(C'\fR" 4
+.IX Item "-fini name"
+When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
+executable or shared object is unloaded, by setting \s-1DT_FINI\s0 to the
+address of the function. By default, the linker uses \f(CW\*(C`_fini\*(C'\fR as
+the function to call.
+.Ip "\f(CW\*(C`\-g\*(C'\fR" 4
+.IX Item "-g"
+Ignored. Provided for compatibility with other tools.
+.Ip "\f(CW\*(C`\-G\f(CIvalue\f(CW\*(C'\fR" 4
+.IX Item "-Gvalue"
+.Ip "\f(CW\*(C`\-\-gpsize=\f(CIvalue\f(CW\*(C'\fR" 4
+.IX Item "--gpsize=value"
+Set the maximum size of objects to be optimized using the \s-1GP\s0 register to
+\&\fIsize\fR. This is only meaningful for object file formats such as
+\&\s-1MIPS\s0 \s-1ECOFF\s0 which supports putting large and small objects into different
+sections. This is ignored for other object file formats.
+.Ip "\f(CW\*(C`\-h\f(CIname\f(CW\*(C'\fR" 4
+.IX Item "-hname"
+.Ip "\f(CW\*(C`\-soname=\f(CIname\f(CW\*(C'\fR" 4
+.IX Item "-soname=name"
+When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_SONAME\s0 field to
+the specified name. When an executable is linked with a shared object
+which has a \s-1DT_SONAME\s0 field, then when the executable is run the dynamic
+linker will attempt to load the shared object specified by the \s-1DT_SONAME\s0
+field rather than the using the file name given to the linker.
+.Ip "\f(CW\*(C`\-i\*(C'\fR" 4
+.IX Item "-i"
+Perform an incremental link (same as option \fB\-r\fR).
+.Ip "\f(CW\*(C`\-init \f(CIname\f(CW\*(C'\fR" 4
+.IX Item "-init name"
+When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
+executable or shared object is loaded, by setting \s-1DT_INIT\s0 to the address
+of the function. By default, the linker uses \f(CW\*(C`_init\*(C'\fR as the
+function to call.
+.Ip "\f(CW\*(C`\-l\f(CIarchive\f(CW\*(C'\fR" 4
+.IX Item "-larchive"
+.Ip "\f(CW\*(C`\-\-library=\f(CIarchive\f(CW\*(C'\fR" 4
+.IX Item "--library=archive"
+Add archive file \fIarchive\fR to the list of files to link. This
+option may be used any number of times. \f(CW\*(C`ld\*(C'\fR will search its
+path-list for occurrences of \f(CW\*(C`lib\f(CIarchive\f(CW.a\*(C'\fR for every
+\&\fIarchive\fR specified.
+.Sp
+On systems which support shared libraries, \f(CW\*(C`ld\*(C'\fR may also search for
+libraries with extensions other than \f(CW\*(C`.a\*(C'\fR. Specifically, on \s-1ELF\s0
+and SunOS systems, \f(CW\*(C`ld\*(C'\fR will search a directory for a library with
+an extension of \f(CW\*(C`.so\*(C'\fR before searching for one with an extension of
+\&\f(CW\*(C`.a\*(C'\fR. By convention, a \f(CW\*(C`.so\*(C'\fR extension indicates a shared
+library.
+.Sp
+The linker will search an archive only once, at the location where it is
+specified on the command line. If the archive defines a symbol which
+was undefined in some object which appeared before the archive on the
+command line, the linker will include the appropriate \fIfile\fR\|(s) from the
+archive. However, an undefined symbol in an object appearing later on
+the command line will not cause the linker to search the archive again.
+.Sp
+See the \f(CW\*(C`\-(\*(C'\fR option for a way to force the linker to search
+archives multiple times.
+.Sp
+You may list the same archive multiple times on the command line.
+.Sp
+This type of archive searching is standard for Unix linkers. However,
+if you are using \f(CW\*(C`ld\*(C'\fR on \s-1AIX\s0, note that it is different from the
+behaviour of the \s-1AIX\s0 linker.
+.Ip "\f(CW\*(C`\-L\f(CIsearchdir\f(CW\*(C'\fR" 4
+.IX Item "-Lsearchdir"
+.Ip "\f(CW\*(C`\-\-library\-path=\f(CIsearchdir\f(CW\*(C'\fR" 4
+.IX Item "--library-path=searchdir"
+Add path \fIsearchdir\fR to the list of paths that \f(CW\*(C`ld\*(C'\fR will search
+for archive libraries and \f(CW\*(C`ld\*(C'\fR control scripts. You may use this
+option any number of times. The directories are searched in the order
+in which they are specified on the command line. Directories specified
+on the command line are searched before the default directories. All
+\&\f(CW\*(C`\-L\*(C'\fR options apply to all \f(CW\*(C`\-l\*(C'\fR options, regardless of the
+order in which the options appear.
+.Sp
+The default set of paths searched (without being specified with
+\&\fB\-L\fR) depends on which emulation mode \f(CW\*(C`ld\*(C'\fR is using, and in
+some cases also on how it was configured.
+.Sp
+The paths can also be specified in a link script with the
+\&\f(CW\*(C`SEARCH_DIR\*(C'\fR command. Directories specified this way are searched
+at the point in which the linker script appears in the command line.
+.Ip "\f(CW\*(C`\-m\f(CIemulation\f(CW\*(C'\fR" 4
+.IX Item "-memulation"
+Emulate the \fIemulation\fR linker. You can list the available
+emulations with the \fB\*(--verbose\fR or \fB\-V\fR options.
+.Sp
+If the \fB\-m\fR option is not used, the emulation is taken from the
+\&\f(CW\*(C`LDEMULATION\*(C'\fR environment variable, if that is defined.
+.Sp
+Otherwise, the default emulation depends upon how the linker was
+configured.
+.Ip "\f(CW\*(C`\-M\*(C'\fR" 4
+.IX Item "-M"
+.Ip "\f(CW\*(C`\-\-print\-map\*(C'\fR" 4
+.IX Item "--print-map"
+Print a link map to the standard output. A link map provides
+information about the link, including the following:
+.RS 4
+.Ip "\(bu" 4
+Where object files and symbols are mapped into memory.
+.Ip "\(bu" 4
+How common symbols are allocated.
+.Ip "\(bu" 4
+All archive members included in the link, with a mention of the symbol
+which caused the archive member to be brought in.
+.RE
+.RS 4
+.RE
+.Ip "\f(CW\*(C`\-n\*(C'\fR" 4
+.IX Item "-n"
+.Ip "\f(CW\*(C`\-\-nmagic\*(C'\fR" 4
+.IX Item "--nmagic"
+Turn off page alignment of sections, and mark the output as
+\&\f(CW\*(C`NMAGIC\*(C'\fR if possible.
+.Ip "\f(CW\*(C`\-N\*(C'\fR" 4
+.IX Item "-N"
+.Ip "\f(CW\*(C`\-\-omagic\*(C'\fR" 4
+.IX Item "--omagic"
+Set the text and data sections to be readable and writable. Also, do
+not page-align the data segment. If the output format supports Unix
+style magic numbers, mark the output as \f(CW\*(C`OMAGIC\*(C'\fR.
+.Ip "\f(CW\*(C`\-o \f(CIoutput\f(CW\*(C'\fR" 4
+.IX Item "-o output"
+.Ip "\f(CW\*(C`\-\-output=\f(CIoutput\f(CW\*(C'\fR" 4
+.IX Item "--output=output"
+Use \fIoutput\fR as the name for the program produced by \f(CW\*(C`ld\*(C'\fR; if this
+option is not specified, the name \fIa.out\fR is used by default. The
+script command \f(CW\*(C`OUTPUT\*(C'\fR can also specify the output file name.
+.Ip "\f(CW\*(C`\-O \f(CIlevel\f(CW\*(C'\fR" 4
+.IX Item "-O level"
+If \fIlevel\fR is a numeric values greater than zero \f(CW\*(C`ld\*(C'\fR optimizes
+the output. This might take significantly longer and therefore probably
+should only be enabled for the final binary.
+.Ip "\f(CW\*(C`\-q\*(C'\fR" 4
+.IX Item "-q"
+.Ip "\f(CW\*(C`\-\-emit\-relocs\*(C'\fR" 4
+.IX Item "--emit-relocs"
+Leave relocation sections and contents in fully linked exececutables.
+Post link analysis and optimization tools may need this information in
+order to perform correct modifications of executables. This results
+in larger executables.
+.Ip "\f(CW\*(C`\-r\*(C'\fR" 4
+.IX Item "-r"
+.Ip "\f(CW\*(C`\-\-relocateable\*(C'\fR" 4
+.IX Item "--relocateable"
+Generate relocatable output\-\-\-i.e., generate an output file that can in
+turn serve as input to \f(CW\*(C`ld\*(C'\fR. This is often called \fIpartial
+linking\fR. As a side effect, in environments that support standard Unix
+magic numbers, this option also sets the output file's magic number to
+\&\f(CW\*(C`OMAGIC\*(C'\fR.
+If this option is not specified, an absolute file is produced. When
+linking \*(C+ programs, this option \fIwill not\fR resolve references to
+constructors; to do that, use \fB\-Ur\fR.
+.Sp
+This option does the same thing as \fB\-i\fR.
+.Ip "\f(CW\*(C`\-R \f(CIfilename\f(CW\*(C'\fR" 4
+.IX Item "-R filename"
+.Ip "\f(CW\*(C`\-\-just\-symbols=\f(CIfilename\f(CW\*(C'\fR" 4
+.IX Item "--just-symbols=filename"
+Read symbol names and their addresses from \fIfilename\fR, 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. You may use this option more than once.
+.Sp
+For compatibility with other \s-1ELF\s0 linkers, if the \f(CW\*(C`\-R\*(C'\fR option is
+followed by a directory name, rather than a file name, it is treated as
+the \f(CW\*(C`\-rpath\*(C'\fR option.
+.Ip "\f(CW\*(C`\-s\*(C'\fR" 4
+.IX Item "-s"
+.Ip "\f(CW\*(C`\-\-strip\-all\*(C'\fR" 4
+.IX Item "--strip-all"
+Omit all symbol information from the output file.
+.Ip "\f(CW\*(C`\-S\*(C'\fR" 4
+.IX Item "-S"
+.Ip "\f(CW\*(C`\-\-strip\-debug\*(C'\fR" 4
+.IX Item "--strip-debug"
+Omit debugger symbol information (but not all symbols) from the output file.
+.Ip "\f(CW\*(C`\-t\*(C'\fR" 4
+.IX Item "-t"
+.Ip "\f(CW\*(C`\-\-trace\*(C'\fR" 4
+.IX Item "--trace"
+Print the names of the input files as \f(CW\*(C`ld\*(C'\fR processes them.
+.Ip "\f(CW\*(C`\-T \f(CIscriptfile\f(CW\*(C'\fR" 4
+.IX Item "-T scriptfile"
+.Ip "\f(CW\*(C`\-\-script=\f(CIscriptfile\f(CW\*(C'\fR" 4
+.IX Item "--script=scriptfile"
+Use \fIscriptfile\fR as the linker script. This script replaces
+\&\f(CW\*(C`ld\*(C'\fR's default linker script (rather than adding to it), so
+\&\fIcommandfile\fR must specify everything necessary to describe the
+output file. You must use this option if you want to use a command
+which can only appear once in a linker script, such as the
+\&\f(CW\*(C`SECTIONS\*(C'\fR or \f(CW\*(C`MEMORY\*(C'\fR command. If
+\&\fIscriptfile\fR does not exist in the current directory, \f(CW\*(C`ld\*(C'\fR
+looks for it in the directories specified by any preceding \fB\-L\fR
+options. Multiple \fB\-T\fR options accumulate.
+.Ip "\f(CW\*(C`\-u \f(CIsymbol\f(CW\*(C'\fR" 4
+.IX Item "-u symbol"
+.Ip "\f(CW\*(C`\-\-undefined=\f(CIsymbol\f(CW\*(C'\fR" 4
+.IX Item "--undefined=symbol"
+Force \fIsymbol\fR to be entered in the output file as an undefined
+symbol. Doing this may, for example, trigger linking of additional
+modules from standard libraries. \fB\-u\fR may be repeated with
+different option arguments to enter additional undefined symbols. This
+option is equivalent to the \f(CW\*(C`EXTERN\*(C'\fR linker script command.
+.Ip "\f(CW\*(C`\-Ur\*(C'\fR" 4
+.IX Item "-Ur"
+For anything other than \*(C+ programs, this option is equivalent to
+\&\fB\-r\fR: it generates relocatable output\-\-\-i.e., an output file that can in
+turn serve as input to \f(CW\*(C`ld\*(C'\fR. When linking \*(C+ programs, \fB\-Ur\fR
+\&\fIdoes\fR resolve references to constructors, unlike \fB\-r\fR.
+It does not work to use \fB\-Ur\fR on files that were themselves linked
+with \fB\-Ur\fR; once the constructor table has been built, it cannot
+be added to. Use \fB\-Ur\fR only for the last partial link, and
+\&\fB\-r\fR for the others.
+.Ip "\f(CW\*(C`\-\-unique[=\f(CI\s\-1SECTION\s0\f(CW]\*(C'\fR" 4
+.IX Item "--unique[=SECTION]"
+Creates a separate output section for every input section matching
+\&\fI\s-1SECTION\s0\fR, or if the optional wildcard \fI\s-1SECTION\s0\fR argument is
+missing, for every orphan input section. An orphan section is one not
+specifically mentioned in a linker script. You may use this option
+multiple times on the command line; It prevents the normal merging of
+input sections with the same name, overriding output section assignments
+in a linker script.
+.Ip "\f(CW\*(C`\-v\*(C'\fR" 4
+.IX Item "-v"
+.Ip "\f(CW\*(C`\-\-version\*(C'\fR" 4
+.IX Item "--version"
+.Ip "\f(CW\*(C`\-V\*(C'\fR" 4
+.IX Item "-V"
+Display the version number for \f(CW\*(C`ld\*(C'\fR. The \f(CW\*(C`\-V\*(C'\fR option also
+lists the supported emulations.
+.Ip "\f(CW\*(C`\-x\*(C'\fR" 4
+.IX Item "-x"
+.Ip "\f(CW\*(C`\-\-discard\-all\*(C'\fR" 4
+.IX Item "--discard-all"
+Delete all local symbols.
+.Ip "\f(CW\*(C`\-X\*(C'\fR" 4
+.IX Item "-X"
+.Ip "\f(CW\*(C`\-\-discard\-locals\*(C'\fR" 4
+.IX Item "--discard-locals"
+Delete all temporary local symbols. For most targets, this is all local
+symbols whose names begin with \fBL\fR.
+.Ip "\f(CW\*(C`\-y \f(CIsymbol\f(CW\*(C'\fR" 4
+.IX Item "-y symbol"
+.Ip "\f(CW\*(C`\-\-trace\-symbol=\f(CIsymbol\f(CW\*(C'\fR" 4
+.IX Item "--trace-symbol=symbol"
+Print the name of each linked file in which \fIsymbol\fR appears. This
+option may be given any number of times. On many systems it is necessary
+to prepend an underscore.
+.Sp
+This option is useful when you have an undefined symbol in your link but
+don't know where the reference is coming from.
+.Ip "\f(CW\*(C`\-Y \f(CIpath\f(CW\*(C'\fR" 4
+.IX Item "-Y path"
+Add \fIpath\fR to the default library search path. This option exists
+for Solaris compatibility.
+.Ip "\f(CW\*(C`\-z \f(CIkeyword\f(CW\*(C'\fR" 4
+.IX Item "-z keyword"
+The recognized keywords are \f(CW\*(C`initfirst\*(C'\fR, \f(CW\*(C`interpose\*(C'\fR,
+\&\f(CW\*(C`loadfltr\*(C'\fR, \f(CW\*(C`nodefaultlib\*(C'\fR, \f(CW\*(C`nodelete\*(C'\fR, \f(CW\*(C`nodlopen\*(C'\fR,
+\&\f(CW\*(C`nodump\*(C'\fR, \f(CW\*(C`now\*(C'\fR and \f(CW\*(C`origin\*(C'\fR. The other keywords are
+ignored for Solaris compatibility. \f(CW\*(C`initfirst\*(C'\fR marks the object
+to be initialized first at runtime before any other objects.
+\&\f(CW\*(C`interpose\*(C'\fR marks the object that its symbol table interposes
+before all symbols but the primary executable. \f(CW\*(C`loadfltr\*(C'\fR marks
+the object that its filtees be processed immediately at runtime.
+\&\f(CW\*(C`nodefaultlib\*(C'\fR marks the object that the search for dependencies
+of this object will ignore any default library search paths.
+\&\f(CW\*(C`nodelete\*(C'\fR marks the object shouldn't be unloaded at runtime.
+\&\f(CW\*(C`nodlopen\*(C'\fR marks the object not available to \f(CW\*(C`dlopen\*(C'\fR.
+\&\f(CW\*(C`nodump\*(C'\fR marks the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR.
+\&\f(CW\*(C`now\*(C'\fR marks the object with the non-lazy runtime binding.
+\&\f(CW\*(C`origin\*(C'\fR marks the object may contain \f(CW$ORIGIN\fR.
+\&\f(CW\*(C`defs\*(C'\fR disallows undefined symbols.
+.Ip "\f(CW\*(C`\-( \f(CIarchives\f(CW \-)\*(C'\fR" 4
+.IX Item "-( archives -)"
+.Ip "\f(CW\*(C`\-\-start\-group \f(CIarchives\f(CW \-\-end\-group\*(C'\fR" 4
+.IX Item "--start-group archives --end-group"
+The \fIarchives\fR should be a list of archive files. They may be
+either explicit file names, or \fB\-l\fR options.
+.Sp
+The specified archives are searched repeatedly until no new undefined
+references are created. Normally, an archive is searched only once in
+the order that it is specified on the command line. If a symbol in that
+archive is needed to resolve an undefined symbol referred to by an
+object in an archive that appears later on the command line, the linker
+would not be able to resolve that reference. By grouping the archives,
+they all be searched repeatedly until all possible references are
+resolved.
+.Sp
+Using this option has a significant performance cost. It is best to use
+it only when there are unavoidable circular references between two or
+more archives.
+.Ip "\f(CW\*(C`\-assert \f(CIkeyword\f(CW\*(C'\fR" 4
+.IX Item "-assert keyword"
+This option is ignored for SunOS compatibility.
+.Ip "\f(CW\*(C`\-Bdynamic\*(C'\fR" 4
+.IX Item "-Bdynamic"
+.Ip "\f(CW\*(C`\-dy\*(C'\fR" 4
+.IX Item "-dy"
+.Ip "\f(CW\*(C`\-call_shared\*(C'\fR" 4
+.IX Item "-call_shared"
+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. The different variants of this option are
+for compatibility with various systems. You may use this option
+multiple times on the command line: it affects library searching for
+\&\f(CW\*(C`\-l\*(C'\fR options which follow it.
+.Ip "\f(CW\*(C`\-Bgroup\*(C'\fR" 4
+.IX Item "-Bgroup"
+Set the \f(CW\*(C`DF_1_GROUP\*(C'\fR flag in the \f(CW\*(C`DT_FLAGS_1\*(C'\fR entry in the dynamic
+section. This causes the runtime linker to handle lookups in this
+object and its dependencies to be performed only inside the group.
+\&\f(CW\*(C`\-\-no\-undefined\*(C'\fR is implied. This option is only meaningful on \s-1ELF\s0
+platforms which support shared libraries.
+.Ip "\f(CW\*(C`\-Bstatic\*(C'\fR" 4
+.IX Item "-Bstatic"
+.Ip "\f(CW\*(C`\-dn\*(C'\fR" 4
+.IX Item "-dn"
+.Ip "\f(CW\*(C`\-non_shared\*(C'\fR" 4
+.IX Item "-non_shared"
+.Ip "\f(CW\*(C`\-static\*(C'\fR" 4
+.IX Item "-static"
+Do not link against shared libraries. This is only meaningful on
+platforms for which shared libraries are supported. The different
+variants of this option are for compatibility with various systems. You
+may use this option multiple times on the command line: it affects
+library searching for \f(CW\*(C`\-l\*(C'\fR options which follow it.
+.Ip "\f(CW\*(C`\-Bsymbolic\*(C'\fR" 4
+.IX Item "-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 \s-1ELF\s0
+platforms which support shared libraries.
+.Ip "\f(CW\*(C`\-\-check\-sections\*(C'\fR" 4
+.IX Item "--check-sections"
+.Ip "\f(CW\*(C`\-\-no\-check\-sections\*(C'\fR" 4
+.IX Item "--no-check-sections"
+Asks the linker \fInot\fR to check section addresses after they have
+been assigned to see if there any overlaps. Normally the linker will
+perform this check, and if it finds any overlaps it will produce
+suitable error messages. The linker does know about, and does make
+allowances for sections in overlays. The default behaviour can be
+restored by using the command line switch \fB\*(--check-sections\fR.
+.Ip "\f(CW\*(C`\-\-cref\*(C'\fR" 4
+.IX Item "--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.
+.Sp
+The format of the table is intentionally simple, so that it may be
+easily processed by a script if necessary. The symbols are printed out,
+sorted by name. For each symbol, a list of file names is given. If the
+symbol is defined, the first file listed is the location of the
+definition. The remaining files contain references to the symbol.
+.Ip "\f(CW\*(C`\-\-defsym \f(CIsymbol\f(CW=\f(CIexpression\f(CW\*(C'\fR" 4
+.IX Item "--defsym symbol=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
+address given by \fIexpression\fR. 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
+limited form of arithmetic is supported for the \fIexpression\fR 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
+symbol, or use \f(CW\*(C`+\*(C'\fR and \f(CW\*(C`\-\*(C'\fR 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 \-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 \-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
-.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
-.B \-\-help
+using the linker command language from a script. \fINote:\fR there should be no white
+space between \fIsymbol\fR, the equals sign (``\fB=\fR''), and
+\&\fIexpression\fR.
+.Ip "\f(CW\*(C`\-\-demangle[=\f(CIstyle\f(CW]\*(C'\fR" 4
+.IX Item "--demangle[=style]"
+.Ip "\f(CW\*(C`\-\-no\-demangle\*(C'\fR" 4
+.IX Item "--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. Different compilers have
+different mangling styles. The optional demangling style argument can be used
+to choose an appropriate demangling style for your compiler. The linker will
+demangle by default unless the environment variable \fB\s-1COLLECT_NO_DEMANGLE\s0\fR
+is set. These options may be used to override the default.
+.Ip "\f(CW\*(C`\-\-dynamic\-linker \f(CIfile\f(CW\*(C'\fR" 4
+.IX Item "--dynamic-linker file"
+Set the name of the dynamic linker. This is only meaningful when
+generating dynamically linked \s-1ELF\s0 executables. The default dynamic
+linker is normally correct; don't use this unless you know what you are
+doing.
+.Ip "\f(CW\*(C`\-\-embedded\-relocs\*(C'\fR" 4
+.IX Item "--embedded-relocs"
+This option is only meaningful when linking \s-1MIPS\s0 embedded \s-1PIC\s0 code,
+generated by the \-membedded-pic option to the \s-1GNU\s0 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.
+.Ip "\f(CW\*(C`\-\-fatal\-warnings\*(C'\fR" 4
+.IX Item "--fatal-warnings"
+Treat all warnings as errors.
+.Ip "\f(CW\*(C`\-\-force\-exe\-suffix\*(C'\fR" 4
+.IX Item "--force-exe-suffix"
+Make sure that an output file has a .exe suffix.
+.Sp
+If a successfully built fully linked output file does not have a
+\&\f(CW\*(C`.exe\*(C'\fR or \f(CW\*(C`.dll\*(C'\fR suffix, this option forces the linker to copy
+the output file to one of the same name with a \f(CW\*(C`.exe\*(C'\fR suffix. This
+option is useful when using unmodified Unix makefiles on a Microsoft
+Windows host, since some versions of Windows won't run an image unless
+it ends in a \f(CW\*(C`.exe\*(C'\fR suffix.
+.Ip "\f(CW\*(C`\-\-no\-gc\-sections\*(C'\fR" 4
+.IX Item "--no-gc-sections"
+.Ip "\f(CW\*(C`\-\-gc\-sections\*(C'\fR" 4
+.IX Item "--gc-sections"
+Enable garbage collection of unused input sections. It is ignored on
+targets that do not support this option. This option is not compatible
+with \fB\-r\fR, nor should it be used with dynamic linking. The default
+behaviour (of not performing this garbage collection) can be restored by
+specifying \fB\*(--no-gc-sections\fR on the command line.
+.Ip "\f(CW\*(C`\-\-help\*(C'\fR" 4
+.IX Item "--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\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
-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
+.Ip "\f(CW\*(C`\-\-target\-help\*(C'\fR" 4
+.IX Item "--target-help"
+Print a summary of all target specific options on the standard output and exit.
+.Ip "\f(CW\*(C`\-Map \f(CImapfile\f(CW\*(C'\fR" 4
+.IX Item "-Map mapfile"
+Print a link map to the file \fImapfile\fR. See the description of the
+\&\fB\-M\fR option, above.
+.Ip "\f(CW\*(C`\-\-no\-keep\-memory\*(C'\fR" 4
+.IX Item "--no-keep-memory"
+\&\f(CW\*(C`ld\*(C'\fR normally optimizes for speed over memory usage by caching the
+symbol tables of input files in memory. This option tells \f(CW\*(C`ld\*(C'\fR to
+instead optimize for memory usage, by rereading the symbol tables as
+necessary. This may be required if \f(CW\*(C`ld\*(C'\fR runs out of memory space
+while linking a large executable.
+.Ip "\f(CW\*(C`\-\-no\-undefined\*(C'\fR" 4
+.IX Item "--no-undefined"
+.Ip "\f(CW\*(C`\-z defs\*(C'\fR" 4
+.IX Item "-z defs"
+Normally when creating a non-symbolic shared library, undefined symbols
+are allowed and left to be resolved by the runtime loader. These options
+disallows such undefined symbols.
+.Ip "\f(CW\*(C`\-\-allow\-shlib\-undefined\*(C'\fR" 4
+.IX Item "--allow-shlib-undefined"
+Allow undefined symbols in shared objects even when \-\-no-undefined is
+set. The net result will be that undefined symbols in regular objects
+will still trigger an error, but undefined symbols in shared objects
+will be ignored. The implementation of no_undefined makes the
+assumption that the runtime linker will choke on undefined symbols.
+However there is at least one system (BeOS) where undefined symbols in
+shared libraries is normal since the kernel patches them at load time to
+select which function is most appropriate for the current architecture.
+I.E. dynamically select an appropriate memset function. Apparently it
+is also normal for \s-1HPPA\s0 shared libraries to have undefined symbols.
+.Ip "\f(CW\*(C`\-\-no\-warn\-mismatch\*(C'\fR" 4
+.IX Item "--no-warn-mismatch"
+Normally \f(CW\*(C`ld\*(C'\fR 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 \f(CW\*(C`ld\*(C'\fR 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.
+.Ip "\f(CW\*(C`\-\-no\-whole\-archive\*(C'\fR" 4
+.IX Item "--no-whole-archive"
+Turn off the effect of the \f(CW\*(C`\-\-whole\-archive\*(C'\fR option for subsequent
+archive files.
+.Ip "\f(CW\*(C`\-\-noinhibit\-exec\*(C'\fR" 4
+.IX Item "--noinhibit-exec"
+Retain the executable output file whenever it is still usable.
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 "\-oformat " "output\-format"\c
-\&
-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"\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
-.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
+errors during the link process; it exits without writing an output file
+when it issues any error whatsoever.
+.Ip "\f(CW\*(C`\-\-oformat \f(CIoutput\-format\f(CW\*(C'\fR" 4
+.IX Item "--oformat output-format"
+\&\f(CW\*(C`ld\*(C'\fR may be configured to support more than one kind of object
+file. If your \f(CW\*(C`ld\*(C'\fR is configured this way, you can use the
+\&\fB\*(--oformat\fR option to specify the binary format for the output
+object file. Even when \f(CW\*(C`ld\*(C'\fR is configured to support alternative
+object formats, you don't usually need to specify this, as \f(CW\*(C`ld\*(C'\fR
+should be configured to produce as a default output format the most
+usual format on each machine. \fIoutput-format\fR is a text string, the
+name of a particular format supported by the \s-1BFD\s0 libraries. (You can
+list the available binary formats with \fBobjdump \-i\fR.) The script
+command \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR can also specify the output format, but
+this option overrides it.
+.Ip "\f(CW\*(C`\-qmagic\*(C'\fR" 4
+.IX Item "-qmagic"
+This option is ignored for Linux compatibility.
+.Ip "\f(CW\*(C`\-Qy\*(C'\fR" 4
+.IX Item "-Qy"
+This option is ignored for \s-1SVR4\s0 compatibility.
+.Ip "\f(CW\*(C`\-\-relax\*(C'\fR" 4
+.IX Item "--relax"
+An option with machine dependent effects.
+This option is only supported on a few targets.
+.Sp
+On some platforms, the \fB\*(--relax\fR option performs global
+optimizations that become possible when the linker resolves addressing
+in the program, such as relaxing address modes and synthesizing new
+instructions in the output object file.
+.Sp
+On some platforms these link time global optimizations may make symbolic
+debugging of the resulting executable impossible.
+This is known to be
+the case for the Matsushita \s-1MN10200\s0 and \s-1MN10300\s0 family of processors.
+.Sp
+On platforms where this is not supported, \fB\*(--relax\fR is accepted,
+but ignored.
+.Ip "\f(CW\*(C`\-\-retain\-symbols\-file \f(CIfilename\f(CW\*(C'\fR" 4
+.IX Item "--retain-symbols-file filename"
+Retain \fIonly\fR the symbols listed in the file \fIfilename\fR,
+discarding all others. \fIfilename\fR is simply a flat file, with one
+symbol name per line. This option is especially useful in environments
+(such as VxWorks)
+where a large global symbol table is accumulated gradually, to conserve
+run-time memory.
+.Sp
+\&\fB\*(--retain-symbols-file\fR does \fInot\fR discard undefined symbols,
+or symbols needed for relocations.
+.Sp
+You may only specify \fB\*(--retain-symbols-file\fR once in the command
+line. It overrides \fB\-s\fR and \fB\-S\fR.
+.Ip "\f(CW\*(C`\-rpath \f(CIdir\f(CW\*(C'\fR" 4
+.IX Item "-rpath dir"
+Add a directory to the runtime library search path. This is used when
+linking an \s-1ELF\s0 executable with shared objects. All \f(CW\*(C`\-rpath\*(C'\fR
+arguments are concatenated and passed to the runtime linker, which uses
+them to locate shared objects at runtime. The \f(CW\*(C`\-rpath\*(C'\fR option is
+also used when locating shared objects which are needed by shared
+objects explicitly included in the link; see the description of the
+\&\f(CW\*(C`\-rpath\-link\*(C'\fR option. If \f(CW\*(C`\-rpath\*(C'\fR is not used when linking an
+\&\s-1ELF\s0 executable, the contents of the environment variable
+\&\f(CW\*(C`LD_RUN_PATH\*(C'\fR will be used if it is defined.
+.Sp
+The \f(CW\*(C`\-rpath\*(C'\fR option may also be used on SunOS. By default, on
+SunOS, the linker will form a runtime search patch out of all the
+\&\f(CW\*(C`\-L\*(C'\fR options it is given. If a \f(CW\*(C`\-rpath\*(C'\fR option is used, the
+runtime search path will be formed exclusively using the \f(CW\*(C`\-rpath\*(C'\fR
+options, ignoring the \f(CW\*(C`\-L\*(C'\fR options. This can be useful when using
+gcc, which adds many \f(CW\*(C`\-L\*(C'\fR options which may be on \s-1NFS\s0 mounted
+filesystems.
+.Sp
+For compatibility with other \s-1ELF\s0 linkers, if the \f(CW\*(C`\-R\*(C'\fR option is
+followed by a directory name, rather than a file name, it is treated as
+the \f(CW\*(C`\-rpath\*(C'\fR option.
+.Ip "\f(CW\*(C`\-rpath\-link \f(CI\s\-1DIR\s0\f(CW\*(C'\fR" 4
+.IX Item "-rpath-link DIR"
+When using \s-1ELF\s0 or SunOS, one shared library may require another. This
+happens when an \f(CW\*(C`ld \-shared\*(C'\fR link includes a shared library as one
+of the input files.
+.Sp
+When the linker encounters such a dependency when doing a non-shared,
+non-relocatable 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 \f(CW\*(C`\-rpath\-link\*(C'\fR option
+specifies the first set of directories to search. The
+\&\f(CW\*(C`\-rpath\-link\*(C'\fR option may specify a sequence of directory names
+either by specifying a list of names separated by colons, or by
+appearing multiple times.
+.Sp
+This option should be used with caution as it overrides the search path
+that may have been hard compiled into a shared library. In such a case it
+is possible to use unintentionally a different search path than the
+runtime linker would do.
+.Sp
+The linker uses the following search paths to locate required shared
+libraries.
+.RS 4
+.Ip "1." 4
+Any directories specified by \f(CW\*(C`\-rpath\-link\*(C'\fR options.
+.Ip "2." 4
+Any directories specified by \f(CW\*(C`\-rpath\*(C'\fR options. The difference
+between \f(CW\*(C`\-rpath\*(C'\fR and \f(CW\*(C`\-rpath\-link\*(C'\fR is that directories
+specified by \f(CW\*(C`\-rpath\*(C'\fR options are included in the executable and
+used at runtime, whereas the \f(CW\*(C`\-rpath\-link\*(C'\fR option is only effective
+at link time. It is for the native linker only.
+.Ip "3." 4
+On an \s-1ELF\s0 system, if the \f(CW\*(C`\-rpath\*(C'\fR and \f(CW\*(C`rpath\-link\*(C'\fR options
+were not used, search the contents of the environment variable
+\&\f(CW\*(C`LD_RUN_PATH\*(C'\fR. It is for the native linker only.
+.Ip "4." 4
+On SunOS, if the \f(CW\*(C`\-rpath\*(C'\fR option was not used, search any
+directories specified using \f(CW\*(C`\-L\*(C'\fR options.
+.Ip "5." 4
+For a native linker, the contents of the environment variable
+\&\f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR.
+.Ip "6." 4
+For a native \s-1ELF\s0 linker, the directories in \f(CW\*(C`DT_RUNPATH\*(C'\fR or
+\&\f(CW\*(C`DT_RPATH\*(C'\fR of a shared library are searched for shared
+libraries needed by it. The \f(CW\*(C`DT_RPATH\*(C'\fR entries are ignored if
+\&\f(CW\*(C`DT_RUNPATH\*(C'\fR entries exist.
+.Ip "7." 4
+The default directories, normally \fI/lib\fR and \fI/usr/lib\fR.
+.Ip "8." 4
+For a native linker on an \s-1ELF\s0 system, if the file \fI/etc/ld.so.conf\fR
+exists, the list of directories found in that file.
+.RE
+.RS 4
+.Sp
+If the required shared library is not found, the linker will issue a
+warning and continue with the link.
+.RE
+.Ip "\f(CW\*(C`\-shared\*(C'\fR" 4
+.IX Item "-shared"
+.Ip "\f(CW\*(C`\-Bshareable\*(C'\fR" 4
+.IX Item "-Bshareable"
+Create a shared library. This is currently only supported on \s-1ELF\s0, \s-1XCOFF\s0
+and SunOS platforms. On SunOS, the linker will automatically create a
+shared library if the \f(CW\*(C`\-e\*(C'\fR option is not used and there are
+undefined symbols in the link.
+.Ip "\f(CW\*(C`\-\-sort\-common\*(C'\fR" 4
+.IX Item "--sort-common"
+This option tells \f(CW\*(C`ld\*(C'\fR to sort the common symbols by size when it
+places them in the appropriate output sections. 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.
+.Ip "\f(CW\*(C`\-\-split\-by\-file [\f(CIsize\f(CW]\*(C'\fR" 4
+.IX Item "--split-by-file [size]"
+Similar to \f(CW\*(C`\-\-split\-by\-reloc\*(C'\fR but creates a new output section for
+each input file when \fIsize\fR is reached. \fIsize\fR defaults to a
+size of 1 if not given.
+.Ip "\f(CW\*(C`\-\-split\-by\-reloc [\f(CIcount\f(CW]\*(C'\fR" 4
+.IX Item "--split-by-reloc [count]"
+Tries to creates extra sections in the output file so that no single
+output section in the file contains more than \fIcount\fR relocations.
+This is useful when generating huge relocatable files for downloading into
+certain real time kernels with the \s-1COFF\s0 object file format; since \s-1COFF\s0
+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 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 \-\-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
+input sections for redistribution, so if a single input section contains
+more than \fIcount\fR relocations one output section will contain that
+many relocations. \fIcount\fR defaults to a value of 32768.
+.Ip "\f(CW\*(C`\-\-stats\*(C'\fR" 4
+.IX Item "--stats"
+Compute and display statistics about the operation of the linker, such
+as execution time and memory usage.
+.Ip "\f(CW\*(C`\-\-traditional\-format\*(C'\fR" 4
+.IX Item "--traditional-format"
+For some targets, the output of \f(CW\*(C`ld\*(C'\fR is different in some ways from
+the output of some existing linker. This switch requests \f(CW\*(C`ld\*(C'\fR to
+use the traditional format instead.
+.Sp
+For example, on SunOS, \f(CW\*(C`ld\*(C'\fR combines duplicate entries in the
+symbol string table. This can reduce the size of an output file with
+full debugging information by over 30 percent. Unfortunately, the SunOS
+\&\f(CW\*(C`dbx\*(C'\fR program can not read the resulting program (\f(CW\*(C`gdb\*(C'\fR has no
+trouble). The \fB\*(--traditional-format\fR switch tells \f(CW\*(C`ld\*(C'\fR to not
+combine duplicate entries.
+.Ip "\f(CW\*(C`\-\-section\-start \f(CIsectionname\f(CW=\f(CIorg\f(CW\*(C'\fR" 4
+.IX Item "--section-start sectionname=org"
+Locate a section in the output file at the absolute
+address given by \fIorg\fR. You may use this option as many
+times as necessary to locate multiple sections in the command
+line.
+\&\fIorg\fR must be a single hexadecimal integer;
+for compatibility with other linkers, you may omit the leading
+\&\fB0x\fR usually associated with hexadecimal values. \fINote:\fR there
+should be no white space between \fIsectionname\fR, the equals
+sign (``\fB=\fR''), and \fIorg\fR.
+.Ip "\f(CW\*(C`\-Tbss \f(CIorg\f(CW\*(C'\fR" 4
+.IX Item "-Tbss org"
+.Ip "\f(CW\*(C`\-Tdata \f(CIorg\f(CW\*(C'\fR" 4
+.IX Item "-Tdata org"
+.Ip "\f(CW\*(C`\-Ttext \f(CIorg\f(CW\*(C'\fR" 4
+.IX Item "-Ttext org"
+Use \fIorg\fR as the starting address for\-\-\-respectively\-\-\-the
+\&\f(CW\*(C`bss\*(C'\fR, \f(CW\*(C`data\*(C'\fR, or the \f(CW\*(C`text\*(C'\fR segment of the output file.
+\&\fIorg\fR must be a single hexadecimal integer;
+for compatibility with other linkers, you may omit the leading
+\&\fB0x\fR usually associated with hexadecimal values.
+.Ip "\f(CW\*(C`\-\-dll\-verbose\*(C'\fR" 4
+.IX Item "--dll-verbose"
+.Ip "\f(CW\*(C`\-\-verbose\*(C'\fR" 4
+.IX Item "--verbose"
+Display the version number for \f(CW\*(C`ld\*(C'\fR and list the linker emulations
+supported. Display which input files can and cannot be opened. Display
+the linker script if using a default builtin script.
+.Ip "\f(CW\*(C`\-\-version\-script=\f(CIversion\-scriptfile\f(CW\*(C'\fR" 4
+.IX Item "--version-script=version-scriptfile"
+Specify the name of a version script to the linker. This is typically
+used when creating shared libraries to specify additional information
+about the version heirarchy for the library being created. This option
+is only meaningful on \s-1ELF\s0 platforms which support shared libraries.
+.Ip "\f(CW\*(C`\-\-warn\-common\*(C'\fR" 4
+.IX Item "--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\-once
+Unfortunately, some C libraries use this practice, so you may get some
+warnings about symbols in the libraries as well as in your programs.
+.Sp
+There are three kinds of global symbols, illustrated here by C examples:
+.RS 4
+.Ip "\fBint i = 1;\fR" 4
+.IX Item "int i = 1;"
+A definition, which goes in the initialized data section of the output
+file.
+.Ip "\fBextern int i;\fR" 4
+.IX Item "extern int i;"
+An undefined reference, which does not allocate space.
+There must be either a definition or a common symbol for the
+variable somewhere.
+.Ip "\fBint i;\fR" 4
+.IX Item "int i;"
+A common symbol. If there are only (one or more) common symbols for a
+variable, it goes in the uninitialized data area of the output file.
+The linker merges multiple common symbols for the same variable into a
+single symbol. If they are of different sizes, it picks the largest
+size. The linker turns a common symbol into a declaration, if there is
+a definition of the same variable.
+.RE
+.RS 4
+.Sp
+The \fB\*(--warn-common\fR option can produce five kinds of warnings.
+Each warning consists of a pair of lines: the first describes the symbol
+just encountered, and the second describes the previous symbol
+encountered with the same name. One or both of the two symbols will be
+a common symbol.
+.RS 4
+.RE
+.Ip "1." 4
+Turning a common symbol into a reference, because there is already a
+definition for the symbol.
+.Sp
+.Vb 3
+\& I<file>(I<section>): warning: common of `I<symbol>'
+\& overridden by definition
+\& I<file>(I<section>): warning: defined here
+.Ve
+.Ip "2." 4
+Turning a common symbol into a reference, because a later definition for
+the symbol is encountered. This is the same as the previous case,
+except that the symbols are encountered in a different order.
+.Sp
+.Vb 3
+\& I<file>(I<section>): warning: definition of `I<symbol>'
+\& overriding common
+\& I<file>(I<section>): warning: common is here
+.Ve
+.Ip "3." 4
+Merging a common symbol with a previous same-sized common symbol.
+.Sp
+.Vb 3
+\& I<file>(I<section>): warning: multiple common
+\& of `I<symbol>'
+\& I<file>(I<section>): warning: previous common is here
+.Ve
+.Ip "4." 4
+Merging a common symbol with a previous larger common symbol.
+.Sp
+.Vb 3
+\& I<file>(I<section>): warning: common of `I<symbol>'
+\& overridden by larger common
+\& I<file>(I<section>): warning: larger common is here
+.Ve
+.Ip "5." 4
+Merging a common symbol with a previous smaller common symbol. This is
+the same as the previous case, except that the symbols are
+encountered in a different order.
+.Sp
+.Vb 3
+\& I<file>(I<section>): warning: common of `I<symbol>'
+\& overriding smaller common
+\& I<file>(I<section>): warning: smaller common is here
+.Ve
+.RE
+.RS 4
+.RE
+.Ip "\f(CW\*(C`\-\-warn\-constructors\*(C'\fR" 4
+.IX Item "--warn-constructors"
+Warn if any global constructors are used. This is only useful for a few
+object file formats. For formats like \s-1COFF\s0 or \s-1ELF\s0, the linker can not
+detect the use of global constructors.
+.Ip "\f(CW\*(C`\-\-warn\-multiple\-gp\*(C'\fR" 4
+.IX Item "--warn-multiple-gp"
+Warn if multiple global pointer values are required in the output file.
+This is only meaningful for certain processors, such as the Alpha.
+Specifically, some processors put large-valued constants in a special
+section. A special register (the global pointer) points into the middle
+of this section, so that constants can be loaded efficiently via a
+base-register relative addressing mode. Since the offset in
+base-register relative mode is fixed and relatively small (e.g., 16
+bits), this limits the maximum size of the constant pool. Thus, in
+large programs, it is often necessary to use multiple global pointer
+values in order to be able to address all possible constants. This
+option causes a warning to be issued whenever this case occurs.
+.Ip "\f(CW\*(C`\-\-warn\-once\*(C'\fR" 4
+.IX Item "--warn-once"
Only warn once for each undefined symbol, rather than once per module
which refers to it.
-
-.TP
-.B \-\-whole\-archive
-For each archive mentioned on the command line, 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 \-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.
-
+.Ip "\f(CW\*(C`\-\-warn\-section\-align\*(C'\fR" 4
+.IX Item "--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 \f(CW\*(C`SECTIONS\*(C'\fR command does not specify a start address for
+the section.
+.Ip "\f(CW\*(C`\-\-whole\-archive\*(C'\fR" 4
+.IX Item "--whole-archive"
+For each archive mentioned on the command line after the
+\&\f(CW\*(C`\-\-whole\-archive\*(C'\fR 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. This option may be used more than once.
+.Sp
+Two notes when using this option from gcc: First, gcc doesn't know
+about this option, so you have to use \f(CW\*(C`\-Wl,\-whole\-archive\*(C'\fR.
+Second, don't forget to use \f(CW\*(C`\-Wl,\-no\-whole\-archive\*(C'\fR after your
+list of archives, because gcc will add its own list of archives to
+your link and you may not want this flag to affect those as well.
+.Ip "\f(CW\*(C`\-\-wrap \f(CIsymbol\f(CW\*(C'\fR" 4
+.IX Item "--wrap symbol"
+Use a wrapper function for \fIsymbol\fR. Any undefined reference to
+\&\fIsymbol\fR will be resolved to \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR. Any
+undefined reference to \f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR will be resolved to
+\&\fIsymbol\fR.
+.Sp
+This can be used to provide a wrapper for a system function. The
+wrapper function should be called \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR. If it
+wishes to call the system function, it should call
+\&\f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR.
+.Sp
+Here is a trivial example:
+.Sp
+.Vb 6
+\& void *
+\& __wrap_malloc (int c)
+\& {
+\& printf ("malloc called with %ld\en", c);
+\& return __real_malloc (c);
+\& }
+.Ve
+If you link other code with this file using \f(CW\*(C`\-\-wrap malloc\*(C'\fR, then
+all calls to \f(CW\*(C`malloc\*(C'\fR will call the function \f(CW\*(C`_\|_wrap_malloc\*(C'\fR
+instead. The call to \f(CW\*(C`_\|_real_malloc\*(C'\fR in \f(CW\*(C`_\|_wrap_malloc\*(C'\fR will
+call the real \f(CW\*(C`malloc\*(C'\fR function.
+.Sp
+You may wish to provide a \f(CW\*(C`_\|_real_malloc\*(C'\fR function as well, so that
+links without the \f(CW\*(C`\-\-wrap\*(C'\fR option will succeed. If you do this,
+you should not put the definition of \f(CW\*(C`_\|_real_malloc\*(C'\fR in the same
+file as \f(CW\*(C`_\|_wrap_malloc\*(C'\fR; if you do, the assembler may resolve the
+call before the linker has a chance to wrap it to \f(CW\*(C`malloc\*(C'\fR.
+.Ip "\f(CW\*(C`\-\-enable\-new\-dtags\*(C'\fR" 4
+.IX Item "--enable-new-dtags"
+.Ip "\f(CW\*(C`\-\-disable\-new\-dtags\*(C'\fR" 4
+.IX Item "--disable-new-dtags"
+This linker can create the new dynamic tags in \s-1ELF\s0. But the older \s-1ELF\s0
+systems may not understand them. If you specify
+\&\f(CW\*(C`\-\-enable\-new\-dtags\*(C'\fR, the dynamic tags will be created as needed.
+If you specify \f(CW\*(C`\-\-disable\-new\-dtags\*(C'\fR, no new dynamic tags will be
+created. By default, the new dynamic tags are not created. Note that
+those options are only available for \s-1ELF\s0 systems.
.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.
-
+The i386 \s-1PE\s0 linker supports the \f(CW\*(C`\-shared\*(C'\fR option, which causes
+the output to be a dynamically linked library (\s-1DLL\s0) instead of a
+normal executable. You should name the output \f(CW\*(C`*.dll\*(C'\fR when you
+use this option. In addition, the linker fully supports the standard
+\&\f(CW\*(C`*.def\*(C'\fR files, which may be specified on the linker command line
+like an object file (in fact, it should precede archives it exports
+symbols from, to ensure that they get linked in, just like a normal
+object file).
.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.
+In addition to the options common to all targets, the i386 \s-1PE\s0 linker
+support additional command line options that are specific to the i386
+\&\s-1PE\s0 target. Options that take values may be separated from their
+values by either a space or an equals sign.
+.Ip "\f(CW\*(C`\-\-add\-stdcall\-alias\*(C'\fR" 4
+.IX Item "--add-stdcall-alias"
+If given, symbols with a stdcall suffix (@\fInn\fR) will be exported
+as-is and also with the suffix stripped.
+.Ip "\f(CW\*(C`\-\-base\-file \f(CIfile\f(CW\*(C'\fR" 4
+.IX Item "--base-file file"
+Use \fIfile\fR as the name of a file in which to save the base
+addresses of all the relocations needed for generating DLLs with
+\&\fIdlltool\fR.
+.Ip "\f(CW\*(C`\-\-dll\*(C'\fR" 4
+.IX Item "--dll"
+Create a \s-1DLL\s0 instead of a regular executable. You may also use
+\&\f(CW\*(C`\-shared\*(C'\fR or specify a \f(CW\*(C`LIBRARY\*(C'\fR in a given \f(CW\*(C`.def\*(C'\fR
+file.
+.Ip "\f(CW\*(C`\-\-enable\-stdcall\-fixup\*(C'\fR" 4
+.IX Item "--enable-stdcall-fixup"
+.Ip "\f(CW\*(C`\-\-disable\-stdcall\-fixup\*(C'\fR" 4
+.IX Item "--disable-stdcall-fixup"
+If the link finds a symbol that it cannot resolve, it will attempt to
+do \*(L"fuzzy linking\*(R" by looking for another defined symbol that differs
+only in the format of the symbol name (cdecl vs stdcall) and will
+resolve that symbol by linking to the match. For example, the
+undefined symbol \f(CW\*(C`_foo\*(C'\fR might be linked to the function
+\&\f(CW\*(C`_foo@12\*(C'\fR, or the undefined symbol \f(CW\*(C`_bar@16\*(C'\fR might be linked
+to the function \f(CW\*(C`_bar\*(C'\fR. When the linker does this, it prints a
+warning, since it normally should have failed to link, but sometimes
+import libraries generated from third-party dlls may need this feature
+to be usable. If you specify \f(CW\*(C`\-\-enable\-stdcall\-fixup\*(C'\fR, this
+feature is fully enabled and warnings are not printed. If you specify
+\&\f(CW\*(C`\-\-disable\-stdcall\-fixup\*(C'\fR, this feature is disabled and such
+mismatches are considered to be errors.
+.Ip "\f(CW\*(C`\-\-export\-all\-symbols\*(C'\fR" 4
+.IX Item "--export-all-symbols"
+If given, all global symbols in the objects used to build a \s-1DLL\s0 will
+be exported by the \s-1DLL\s0. Note that this is the default if there
+otherwise wouldn't be any exported symbols. When symbols are
+explicitly exported via \s-1DEF\s0 files or implicitly exported via function
+attributes, the default is to not export anything else unless this
+option is given. Note that the symbols \f(CW\*(C`DllMain@12\*(C'\fR,
+\&\f(CW\*(C`DllEntryPoint@0\*(C'\fR, and \f(CW\*(C`impure_ptr\*(C'\fR will not be automatically
+exported.
+.Ip "\f(CW\*(C`\-\-exclude\-symbols \f(CIsymbol\f(CW,\f(CIsymbol\f(CW,...\*(C'\fR" 4
+.IX Item "--exclude-symbols symbol,symbol,..."
+Specifies a list of symbols which should not be automatically
+exported. The symbol names may be delimited by commas or colons.
+.Ip "\f(CW\*(C`\-\-file\-alignment\*(C'\fR" 4
+.IX Item "--file-alignment"
+Specify the file alignment. Sections in the file will always begin at
+file offsets which are multiples of this number. This defaults to
+512.
+.Ip "\f(CW\*(C`\-\-heap \f(CIreserve\f(CW\*(C'\fR" 4
+.IX Item "--heap reserve"
+.Ip "\f(CW\*(C`\-\-heap \f(CIreserve\f(CW,\f(CIcommit\f(CW\*(C'\fR" 4
+.IX Item "--heap reserve,commit"
+Specify the amount of memory to reserve (and optionally commit) to be
+used as heap for this program. The default is 1Mb reserved, 4K
+committed.
+.Ip "\f(CW\*(C`\-\-image\-base \f(CIvalue\f(CW\*(C'\fR" 4
+.IX Item "--image-base value"
+Use \fIvalue\fR as the base address of your program or dll. This is
+the lowest memory location that will be used when your program or dll
+is loaded. To reduce the need to relocate and improve performance of
+your dlls, each should have a unique base address and not overlap any
+other dlls. The default is 0x400000 for executables, and 0x10000000
+for dlls.
+.Ip "\f(CW\*(C`\-\-kill\-at\*(C'\fR" 4
+.IX Item "--kill-at"
+If given, the stdcall suffixes (@\fInn\fR) will be stripped from
+symbols before they are exported.
+.Ip "\f(CW\*(C`\-\-major\-image\-version \f(CIvalue\f(CW\*(C'\fR" 4
+.IX Item "--major-image-version value"
+Sets the major number of the \*(L"image version\*(R". Defaults to 1.
+.Ip "\f(CW\*(C`\-\-major\-os\-version \f(CIvalue\f(CW\*(C'\fR" 4
+.IX Item "--major-os-version value"
+Sets the major number of the \*(L"os version\*(R". Defaults to 4.
+.Ip "\f(CW\*(C`\-\-major\-subsystem\-version \f(CIvalue\f(CW\*(C'\fR" 4
+.IX Item "--major-subsystem-version value"
+Sets the major number of the \*(L"subsystem version\*(R". Defaults to 4.
+.Ip "\f(CW\*(C`\-\-minor\-image\-version \f(CIvalue\f(CW\*(C'\fR" 4
+.IX Item "--minor-image-version value"
+Sets the minor number of the \*(L"image version\*(R". Defaults to 0.
+.Ip "\f(CW\*(C`\-\-minor\-os\-version \f(CIvalue\f(CW\*(C'\fR" 4
+.IX Item "--minor-os-version value"
+Sets the minor number of the \*(L"os version\*(R". Defaults to 0.
+.Ip "\f(CW\*(C`\-\-minor\-subsystem\-version \f(CIvalue\f(CW\*(C'\fR" 4
+.IX Item "--minor-subsystem-version value"
+Sets the minor number of the \*(L"subsystem version\*(R". Defaults to 0.
+.Ip "\f(CW\*(C`\-\-output\-def \f(CIfile\f(CW\*(C'\fR" 4
+.IX Item "--output-def file"
+The linker will create the file \fIfile\fR which will contain a \s-1DEF\s0
+file corresponding to the \s-1DLL\s0 the linker is generating. This \s-1DEF\s0 file
+(which should be called \f(CW\*(C`*.def\*(C'\fR) may be used to create an import
+library with \f(CW\*(C`dlltool\*(C'\fR or may be used as a reference to
+automatically or implicitly exported symbols.
+.Ip "\f(CW\*(C`\-\-section\-alignment\*(C'\fR" 4
+.IX Item "--section-alignment"
+Sets the section alignment. Sections in memory will always begin at
+addresses which are a multiple of this number. Defaults to 0x1000.
+.Ip "\f(CW\*(C`\-\-stack \f(CIreserve\f(CW\*(C'\fR" 4
+.IX Item "--stack reserve"
+.Ip "\f(CW\*(C`\-\-stack \f(CIreserve\f(CW,\f(CIcommit\f(CW\*(C'\fR" 4
+.IX Item "--stack reserve,commit"
+Specify the amount of memory to reserve (and optionally commit) to be
+used as stack for this program. The default is 32Mb reserved, 4K
+committed.
+.Ip "\f(CW\*(C`\-\-subsystem \f(CIwhich\f(CW\*(C'\fR" 4
+.IX Item "--subsystem which"
+.Ip "\f(CW\*(C`\-\-subsystem \f(CIwhich\f(CW:\f(CImajor\f(CW\*(C'\fR" 4
+.IX Item "--subsystem which:major"
+.Ip "\f(CW\*(C`\-\-subsystem \f(CIwhich\f(CW:\f(CImajor\f(CW.\f(CIminor\f(CW\*(C'\fR" 4
+.IX Item "--subsystem which:major.minor"
+Specifies the subsystem under which your program will execute. The
+legal values for \fIwhich\fR are \f(CW\*(C`native\*(C'\fR, \f(CW\*(C`windows\*(C'\fR,
+\&\f(CW\*(C`console\*(C'\fR, and \f(CW\*(C`posix\*(C'\fR. You may optionally set the
+subsystem version also.
+.SH "ENVIRONMENT"
+.IX Header "ENVIRONMENT"
+You can change the behavior of \f(CW\*(C`ld\*(C'\fR with the environment variables
+\&\f(CW\*(C`GNUTARGET\*(C'\fR, \f(CW\*(C`LDEMULATION\*(C'\fR, and \f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR.
.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.
+\&\f(CW\*(C`GNUTARGET\*(C'\fR determines the input-file object format if you don't
+use \fB\-b\fR (or its synonym \fB\*(--format\fR). Its value should be one
+of the \s-1BFD\s0 names for an input format. If there is no
+\&\f(CW\*(C`GNUTARGET\*(C'\fR in the environment, \f(CW\*(C`ld\*(C'\fR uses the natural format
+of the target. If \f(CW\*(C`GNUTARGET\*(C'\fR is set to \f(CW\*(C`default\*(C'\fR then \s-1BFD\s0
+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 specify
+object-file formats is unique. However, the configuration procedure for
+\&\s-1BFD\s0 on each system places the conventional format for that system first
+in the search-list, so ambiguities are resolved in favor of convention.
.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.
+\&\f(CW\*(C`LDEMULATION\*(C'\fR determines the default emulation if you don't use the
+\&\fB\-m\fR option. The emulation can affect various aspects of linker
+behaviour, particularly the default linker script. You can list the
+available emulations with the \fB\*(--verbose\fR or \fB\-V\fR options. If
+the \fB\-m\fR option is not used, and the \f(CW\*(C`LDEMULATION\*(C'\fR environment
+variable is not defined, the default emulation depends upon how the
+linker was configured.
+.PP
+Normally, the linker will default to demangling symbols. However, if
+\&\f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR is set in the environment, then it will
+default to not demangling symbols. This environment variable is used in
+a similar fashion by the \f(CW\*(C`gcc\*(C'\fR linker wrapper program. The default
+may be overridden by the \fB\*(--demangle\fR and \fB\*(--no-demangle\fR
+options.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIar\fR\|(1), \fInm\fR\|(1), \fIobjcopy\fR\|(1), \fIobjdump\fR\|(1), \fIreadelf\fR\|(1) and
+the Info entries for \fIbinutils\fR and
+\&\fIld\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc.
.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.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts. A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
projects / external / binutils.git / blobdiff