-.\" 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
-\&.\|.\|.
+.rn '' }`
+''' $RCSfile$$Revision$$Date$
+'''
+''' $Log$
+''' Revision 1.9 2001/03/25 20:32:31 nickc
+''' Automate generate on man pages
+'''
+'''
+.de Sh
.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
+.if t .sp .5v
+.if n .sp
+..
+.de Ip
.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 "[\|" \-G\c
-.I size\c
-\&\|]
-.RB "[\|" \-i "\|]"
-.RB "[\|" \-l\c
-.I ar\c
-\&\|]
-.RB "[\|" \-L\c
-.I searchdir\c
-\&\|]
-.RB "[\|" \-M "\|]"
-.RB "[\|" \-m\c
-.I emulation\c
-\&\|]
-.RB "[\|" \-n | \-N "\|]"
-.RB "[\|" \-noinhibit-exec "\|]"
-.RB "[\|" "\-R\ "\c
-.I filename\c
-\&\|]
-.RB "[\|" \-relax "\|]"
-.RB "[\|" \-r | \-Ur "\|]"
-.RB "[\|" \-S "\|]"
-.RB "[\|" \-s "\|]"
-.RB "[\|" "\-T\ "\c
-.I commandfile\c
-\&\|]
-.RB "[\|" "\-Ttext\ "\c
-.I textorg\c
-\&\|]
-.RB "[\|" "\-Tdata\ "\c
-.I dataorg\c
-\&\|]
-.RB "[\|" "\-Tbss\ "\c
-.I bssorg\c
-\&\|]
-.RB "[\|" \-t "\|]"
-.RB "[\|" "\-u\ "\c
-.I sym\c
-\&]
-.RB "[\|" \-V "\|]"
-.RB "[\|" \-v "\|]"
-.RB "[\|" \-X "\|]"
-.RB "[\|" \-x "\|]"
-.RB "[\|" { \c
-.I script\c
-.BR } "\|]"
-.ad b
-.hy 1
-.SH DESCRIPTION
-\c
-.B ld\c
-\& combines a number of object and archive files, relocates
-their data and ties up symbol references. Often the last step in
-building a new compiled program to run is a call to \c
-.B ld\c
-\&.
-
-\c
-.B ld\c
-\& accepts Linker Command Language files
-to provide explicit and total control over the linking process.
-This man page does not describe the command language; see the `\|\c
-.B ld\c
-\|' entry in `\|\c
-.B info\c
-\|', or the manual
-.I
-ld: the GNU linker
-\&, for full details on the command language and on other aspects of
-the GNU linker.
-
-This version of \c
-.B ld\c
-\& uses the general purpose BFD libraries
-to operate on object files. This allows \c
-.B ld\c
-\& to read, combine, and
-write object files in many different formats\(em\&for example, COFF or
-\c
-.B a.out\c
-\&. Different formats may be linked together to produce any
-available kind of object file. You can use `\|\c
-.B objdump \-i\c
-\|' to get a list of formats supported on various architectures; see
-.BR objdump ( 1 ).
+.ie \\n(.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+.de Vb
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve
+.ft R
+.fi
+..
+'''
+'''
+''' Set up \*(-- to give an unbreakable dash;
+''' string Tr holds user defined translation string.
+''' Bell System Logo is used as a dummy character.
+'''
+.tr \(*W-|\(bv\*(Tr
+.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" ""
+''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
+''' \*(L" and \*(R", except that they are used on ".xx" lines,
+''' such as .IP and .SH, which do another additional levels of
+''' double-quote interpretation
+.ds M" """
+.ds S" """
+.ds N" """""
+.ds T" """""
+.ds L' '
+.ds R' '
+.ds M' '
+.ds S' '
+.ds N' '
+.ds T' '
+'br\}
+.el\{\
+.ds -- \(em\|
+.tr \*(Tr
+.ds L" ``
+.ds R" ''
+.ds M" ``
+.ds S" ''
+.ds N" ``
+.ds T" ''
+.ds L' `
+.ds R' '
+.ds M' `
+.ds S' '
+.ds N' `
+.ds T' '
+.ds PI \(*p
+'br\}
+.\" If the F register is turned on, we'll generate
+.\" index entries out stderr for the following things:
+.\" TH Title
+.\" SH Header
+.\" Sh Subsection
+.\" Ip Item
+.\" X<> Xref (embedded
+.\" Of course, you have to process the output yourself
+.\" in some meaninful fashion.
+.if \nF \{
+.de IX
+.tm Index:\\$1\t\\n%\t"\\$2"
+..
+.nr % 0
+.rr F
+.\}
+.TH LD 1 "binutils-2.11.90" "23/Mar/101" "GNU"
+.UC
+.if n .hy 0
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.de CQ \" put $1 in typewriter font
+.ft CW
+'if n "\c
+'if t \\&\\$1\c
+'if n \\&\\$1\c
+'if n \&"
+\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
+'.ft R
+..
+.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
+. \" AM - accent mark definitions
+.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 ? ?
+. ds ! !
+. ds /
+. ds q
+.\}
+.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 ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
+. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
+.\}
+. \" 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 v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
+.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
+.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
+.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
+.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
+.ds oe o\h'-(\w'o'u*4/10)'e
+.ds Oe O\h'-(\w'O'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 v \h'-1'\o'\(aa\(ga'
+. ds _ \h'-1'^
+. ds . \h'-1'.
+. ds 3 3
+. 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
+. ds oe oe
+. ds Oe OE
+.\}
+.rm #[ #] #H #V #F C
+.SH "NAME"
+ld \- Using LD, the GNU linker
+.SH "SYNOPSIS"
+ld [ options ] objfile...
+.SH "DESCRIPTION"
+\f(CWld\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(CWld\fR.
+.PP
+\f(CWld\fR accepts Linker Command Language files written in
+a superset of AT&T's Link Editor Command Language syntax,
+to provide explicit and total control over the linking process.
+.PP
+This man page does not describe the command language; see the
+\f(CWld\fR entry in \f(CWinfo\fR, or the manual
+ld: the GNU linker, for full details on the command language and
+on other aspects of the GNU linker.
+.PP
+This version of \f(CWld\fR uses the general purpose BFD libraries
+to operate on object files. This allows \f(CWld\fR to read, combine, and
+write object files in many different formats---for example, COFF or
+\f(CWa.out\fR. Different formats may be linked together to produce any
+available kind of object file.
+.PP
Aside from its flexibility, the GNU linker is more helpful than other
linkers in providing diagnostic information. Many linkers abandon
execution immediately upon encountering an error; whenever possible,
-\c
-.B ld\c
-\& continues executing, allowing you to identify other errors
+\f(CWld\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 GNU linker \f(CWld\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"
+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(CWld\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(CWhello.o\fR:
+.PP
+.Vb 2
+\&
+\& ld -o I<output> /lib/crt0.o hello.o -lc
+.Ve
+This tells \f(CWld\fR to produce a file called \fIoutput\fR as the
+result of linking the file \f(CW/lib/crt0.o\fR with \f(CWhello.o\fR and
+the library \f(CWlibc.a\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(CWld\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(CWINPUT\fR or \f(CWGROUP\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(CWSECTIONS\fR or \f(CWMEMORY\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 \*(L'o\*(R' 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 NMAGIC 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 2
+\&
+\& 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 GNU
+linker:
+.Ip "\f(CW-a\fIkeyword\fR\fR" 4
+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-A\fIarchitecture\fR\fR" 4
+.Ip "\f(CW--architecture=\fIarchitecture\fR\fR" 4
+In the current release of \f(CWld\fR, this option is useful only for the
+Intel 960 family of architectures. In that \f(CWld\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(CWld\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.
-
+.Ip "\f(CW-b \fIinput-format\fR\fR" 4
+.Ip "\f(CW--format=\fIinput-format\fR\fR" 4
+\f(CWld\fR may be configured to support more than one kind of object
+file. If your \f(CWld\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(CWld\fR is
+configured to support alternative object formats, you don't usually need
+to specify this, as \f(CWld\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(CWGNUTARGET\fR.
+.Sp
+You can also define the input format from a script, using the command
+\f(CWTARGET\fR;
+.Ip "\f(CW-c \fIMRI-commandfile\fR\fR" 4
+.Ip "\f(CW--mri-script=\fIMRI-commandfile\fR\fR" 4
+For compatibility with linkers produced by \s-1MRI\s0, \f(CWld\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(CWld\fR scripting language.
+If \fI\s-1MRI\s0\-cmdfile\fR does not exist, \f(CWld\fR looks for it in the directories
+specified by any \fB\-L\fR options.
+.Ip "\f(CW-d\fR" 4
+.Ip "\f(CW-dc\fR" 4
+.Ip "\f(CW-dp\fR" 4
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(CWFORCE_COMMON_ALLOCATION\fR has the same effect.
+.Ip "\f(CW-e \fIentry\fR\fR" 4
+.Ip "\f(CW--entry=\fIentry\fR\fR" 4
+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-E\fR" 4
+.Ip "\f(CW--export-dynamic\fR" 4
+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(CWdlopen\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-EB\fR" 4
+Link big-endian objects. This affects the default output format.
+.Ip "\f(CW-EL\fR" 4
+Link little-endian objects. This affects the default output format.
+.Ip "\f(CW-f\fR" 4
+.Ip "\f(CW--auxiliary \fIname\fR\fR" 4
+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-F \fIname\fR\fR" 4
+.Ip "\f(CW--filter \fIname\fR\fR" 4
+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-F\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-b\fR, \f(CW--format\fR, \f(CW--oformat\fR options, the
+\f(CWTARGET\fR command in linker scripts, and the \f(CWGNUTARGET\fR
+environment variable. The \s-1GNU\s0 linker will ignore the \f(CW-F\fR
+option when not creating an \s-1ELF\s0 shared object.
+.Ip "\f(CW-fini \fIname\fR\fR" 4
+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_fini\fR as
+the function to call.
+.Ip "\f(CW-g\fR" 4
+Ignored. Provided for compatibility with other tools.
+.Ip "\f(CW-G\fIvalue\fR\fR" 4
+.Ip "\f(CW--gpsize=\fIvalue\fR\fR" 4
+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-h\fIname\fR\fR" 4
+.Ip "\f(CW-soname=\fIname\fR\fR" 4
+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-i\fR" 4
+Perform an incremental link (same as option \fB\-r\fR).
+.Ip "\f(CW-init \fIname\fR\fR" 4
+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_init\fR as the
+function to call.
+.Ip "\f(CW-l\fIarchive\fR\fR" 4
+.Ip "\f(CW--library=\fIarchive\fR\fR" 4
+Add archive file \fIarchive\fR to the list of files to link. This
+option may be used any number of times. \f(CWld\fR will search its
+path-list for occurrences of \f(CWlib\fIarchive\fR.a\fR for every
+\fIarchive\fR specified.
+.Sp
+On systems which support shared libraries, \f(CWld\fR may also search for
+libraries with extensions other than \f(CW.a\fR. Specifically, on \s-1ELF\s0
+and SunOS systems, \f(CWld\fR will search a directory for a library with
+an extension of \f(CW.so\fR before searching for one with an extension of
+\&\f(CW.a\fR. By convention, a \f(CW.so\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-(\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(CWld\fR on \s-1AIX\s0, note that it is different from the
+behaviour of the \s-1AIX\s0 linker.
+.Ip "\f(CW-L\fIsearchdir\fR\fR" 4
+.Ip "\f(CW--library-path=\fIsearchdir\fR\fR" 4
+Add path \fIsearchdir\fR to the list of paths that \f(CWld\fR will search
+for archive libraries and \f(CWld\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-L\fR options apply to all \f(CW-l\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(CWld\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(CWSEARCH_DIR\fR command. Directories specified this way are searched
+at the point in which the linker script appears in the command line.
+.Ip "\f(CW-m\fIemulation\fR\fR" 4
+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(CWLDEMULATION\fR environment variable, if that is defined.
+.Sp
+Otherwise, the default emulation depends upon how the linker was
+configured.
+.Ip "\f(CW-M\fR" 4
+.Ip "\f(CW--print-map\fR" 4
+Print a link map to the standard output. A link map provides
+information about the link, including the following:
+.Ip "\(bu" 8
+Where object files and symbols are mapped into memory.
+.Ip "\(bu" 8
+How common symbols are allocated.
+.Ip "\(bu" 8
+All archive members included in the link, with a mention of the symbol
+which caused the archive member to be brought in.
+.Ip "\f(CW-n\fR" 4
+.Ip "\f(CW--nmagic\fR" 4
+Turn off page alignment of sections, and mark the output as
+\f(CWNMAGIC\fR if possible.
+.Ip "\f(CW-N\fR" 4
+.Ip "\f(CW--omagic\fR" 4
+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(CWOMAGIC\fR.
+.Ip "\f(CW-o \fIoutput\fR\fR" 4
+.Ip "\f(CW--output=\fIoutput\fR\fR" 4
+Use \fIoutput\fR as the name for the program produced by \f(CWld\fR; if this
+option is not specified, the name \fIa.out\fR is used by default. The
+script command \f(CWOUTPUT\fR can also specify the output file name.
+.Ip "\f(CW-O \fIlevel\fR\fR" 4
+If \fIlevel\fR is a numeric values greater than zero \f(CWld\fR optimizes
+the output. This might take significantly longer and therefore probably
+should only be enabled for the final binary.
+.Ip "\f(CW-q\fR" 4
+.Ip "\f(CW--emit-relocs\fR" 4
+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-r\fR" 4
+.Ip "\f(CW--relocateable\fR" 4
+Generate relocatable output---i.e., generate an output file that can in
+turn serve as input to \f(CWld\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(CWOMAGIC\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-R \fIfilename\fR\fR" 4
+.Ip "\f(CW--just-symbols=\fIfilename\fR\fR" 4
+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-R\fR option is
+followed by a directory name, rather than a file name, it is treated as
+the \f(CW-rpath\fR option.
+.Ip "\f(CW-s\fR" 4
+.Ip "\f(CW--strip-all\fR" 4
+Omit all symbol information from the output file.
+.Ip "\f(CW-S\fR" 4
+.Ip "\f(CW--strip-debug\fR" 4
+Omit debugger symbol information (but not all symbols) from the output file.
+.Ip "\f(CW-t\fR" 4
+.Ip "\f(CW--trace\fR" 4
+Print the names of the input files as \f(CWld\fR processes them.
+.Ip "\f(CW-T \fIscriptfile\fR\fR" 4
+.Ip "\f(CW--script=\fIscriptfile\fR\fR" 4
+Use \fIscriptfile\fR as the linker script. This script replaces
+\f(CWld\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(CWSECTIONS\fR or \f(CWMEMORY\fR command. If
+\fIscriptfile\fR does not exist in the current directory, \f(CWld\fR
+looks for it in the directories specified by any preceding \fB\-L\fR
+options. Multiple \fB\-T\fR options accumulate.
+.Ip "\f(CW-u \fIsymbol\fR\fR" 4
+.Ip "\f(CW--undefined=\fIsymbol\fR\fR" 4
+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(CWEXTERN\fR linker script command.
+.Ip "\f(CW-Ur\fR" 4
+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(CWld\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--unique[=\fISECTION\fR]\fR" 4
+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-v\fR" 4
+.Ip "\f(CW--version\fR" 4
+.Ip "\f(CW-V\fR" 4
+Display the version number for \f(CWld\fR. The \f(CW-V\fR option also
+lists the supported emulations.
+.Ip "\f(CW-x\fR" 4
+.Ip "\f(CW--discard-all\fR" 4
+Delete all local symbols.
+.Ip "\f(CW-X\fR" 4
+.Ip "\f(CW--discard-locals\fR" 4
+Delete all temporary local symbols. For most targets, this is all local
+symbols whose names begin with \fBL\fR.
+.Ip "\f(CW-y \fIsymbol\fR\fR" 4
+.Ip "\f(CW--trace-symbol=\fIsymbol\fR\fR" 4
+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-Y \fIpath\fR\fR" 4
+Add \fIpath\fR to the default library search path. This option exists
+for Solaris compatibility.
+.Ip "\f(CW-z \fIkeyword\fR\fR" 4
+The recognized keywords are \f(CWinitfirst\fR, \f(CWinterpose\fR,
+\f(CWloadfltr\fR, \f(CWnodefaultlib\fR, \f(CWnodelete\fR, \f(CWnodlopen\fR,
+\f(CWnodump\fR, \f(CWnow\fR and \f(CWorigin\fR. The other keywords are
+ignored for Solaris compatibility. \f(CWinitfirst\fR marks the object
+to be initialized first at runtime before any other objects.
+\f(CWinterpose\fR marks the object that its symbol table interposes
+before all symbols but the primary executable. \f(CWloadfltr\fR marks
+the object that its filtees be processed immediately at runtime.
+\f(CWnodefaultlib\fR marks the object that the search for dependencies
+of this object will ignore any default library search paths.
+\f(CWnodelete\fR marks the object shouldn't be unloaded at runtime.
+\f(CWnodlopen\fR marks the object not available to \f(CWdlopen\fR.
+\f(CWnodump\fR marks the object can not be dumped by \f(CWdldump\fR.
+\f(CWnow\fR marks the object with the non-lazy runtime binding.
+\f(CWorigin\fR marks the object may contain \f(CW$ORIGIN\fR.
+\f(CWdefs\fR disallows undefined symbols.
+.Ip "\f(CW-( \fIarchives\fR -)\fR" 4
+.Ip "\f(CW--start-group \fIarchives\fR --end-group\fR" 4
+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-assert \fIkeyword\fR\fR" 4
+This option is ignored for SunOS compatibility.
+.Ip "\f(CW-Bdynamic\fR" 4
+.Ip "\f(CW-dy\fR" 4
+.Ip "\f(CW-call_shared\fR" 4
+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-l\fR options which follow it.
+.Ip "\f(CW-Bgroup\fR" 4
+Set the \f(CWDF_1_GROUP\fR flag in the \f(CWDT_FLAGS_1\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--no-undefined\fR is implied. This option is only meaningful on \s-1ELF\s0
+platforms which support shared libraries.
+.Ip "\f(CW-Bstatic\fR" 4
+.Ip "\f(CW-dn\fR" 4
+.Ip "\f(CW-non_shared\fR" 4
+.Ip "\f(CW-static\fR" 4
+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-l\fR options which follow it.
+.Ip "\f(CW-Bsymbolic\fR" 4
+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--check-sections\fR" 4
+.Ip "\f(CW--no-check-sections\fR" 4
+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--cref\fR" 4
+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--defsym \fIsymbol\fR=\fIexpression\fR\fR" 4
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+\fR and \f(CW-\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 \-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 \-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 "\-m " "emulation"\c
-Emulate the
-.I emulation
-linker. You can list the available emulations with the
-.I \-V
-option. 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
+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--demangle[=\fIstyle\fR]\fR" 4
+.Ip "\f(CW--no-demangle\fR" 4
+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--dynamic-linker \fIfile\fR\fR" 4
+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--embedded-relocs\fR" 4
+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--force-exe-suffix\fR" 4
+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.exe\fR or \f(CW.dll\fR suffix, this option forces the linker to copy
+the output file to one of the same name with a \f(CW.exe\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.exe\fR suffix.
+.Ip "\f(CW--no-gc-sections\fR" 4
+.Ip "\f(CW--gc-sections\fR" 4
+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--help\fR" 4
+Print a summary of the command-line options on the standard output and exit.
+.Ip "\f(CW--target-help\fR" 4
+Print a summary of all target specific options on the standard output and exit.
+.Ip "\f(CW-Map \fImapfile\fR\fR" 4
+Print a link map to the file \fImapfile\fR. See the description of the
+\fB\-M\fR option, above.
+.Ip "\f(CW--no-keep-memory\fR" 4
+\f(CWld\fR normally optimizes for speed over memory usage by caching the
+symbol tables of input files in memory. This option tells \f(CWld\fR to
+instead optimize for memory usage, by rereading the symbol tables as
+necessary. This may be required if \f(CWld\fR runs out of memory space
+while linking a large executable.
+.Ip "\f(CW--no-undefined\fR" 4
+.Ip "\f(CW-z defs\fR" 4
+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--allow-shlib-undefined\fR" 4
+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--no-warn-mismatch\fR" 4
+Normally \f(CWld\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(CWld\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--no-whole-archive\fR" 4
+Turn off the effect of the \f(CW--whole-archive\fR option for subsequent
+archive files.
+.Ip "\f(CW--noinhibit-exec\fR" 4
+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 "-R " "filename"\c
-\&
-.I file\c
-\&
-Read symbol names and their addresses from \c
-.I filename\c
-\&, but do not
-relocate it or include it in the output. This allows your output file
-to refer symbolically to absolute locations of memory defined in other
-programs.
-
-.TP
-.B \-relax
-An option with machine dependent effects. Currently this option is only
-supported on the H8/300.
-
-On some platforms, use this option to perform global optimizations that
-become possible when the linker resolves addressing in your program, such
-as relaxing address modes and synthesizing new instructions in the
-output object file.
-
-On platforms where this is not supported, `\|\c
-.B \-relax\c
-\&\|' is accepted, but has no effect.
-
-.TP
-.B \-r
-Generates relocatable output\(em\&i.e., generate an output file that can in
-turn serve as input to \c
-.B ld\c
-\&. This is often called \c
-.I partial
-linking\c
-\&. As a side effect, in environments that support standard Unix
-magic numbers, this option also sets the output file's magic number to
-\c
-.B OMAGIC\c
-\&.
-If this option is not specified, an absolute file is produced. When
-linking C++ programs, this option \c
-.I will not\c
-\& resolve references to
-constructors; \c
-.B \-Ur\c
-\& is an alternative.
-
-This option does the same as \c
-.B \-i\c
-\&.
-
-.TP
-.B \-S
-Omits debugger symbol information (but not all symbols) from the output file.
-
-.TP
-.B \-s
-Omits all symbol information from the output file.
-
-.TP
-.BI "{ " "script" " }"
-You can, if you wish, include a script of linker commands directly in
-the command line instead of referring to it via an input file. When the
-character `\|\c
-.B {\c
-\|' occurs on the command line, the linker switches to
-interpreting the command language until the end of the list of commands
-is reached\(em\&flagged with a closing brace `\|\c
-.B }\c
-\|'. Other command-line
-options will not be recognized while parsing the script.
-See the `\|\c
-.B ld\c
-\|' entry in `\|\c
-.B info\c
-\|', or the manual
-.I
-ld: the GNU linker
-\&, for a description of the command language.
-
-.TP
-.BI "-Tbss " "org"\c
-.TP
-.BI "-Tdata " "org"\c
-.TP
-.BI "-Ttext " "org"\c
-Use \c
-.I org\c
-\& as the starting address for\(em\&respectively\(em\&the
-\c
-.B bss\c
-\&, \c
-.B data\c
-\&, or the \c
-.B text\c
-\& segment of the output file.
-\c
-.I textorg\c
-\& must be a hexadecimal integer.
-
-.TP
-.BI "-T " "commandfile"\c
-\&
-.TP
-.BI "-T" "commandfile"\c
-Equivalent to \c
-.B \-c \c
-.I commandfile\c
-\&\c
-\&; supported for compatibility with
-other tools.
-
-.TP
-.B \-t
-Prints names of input files as \c
-.B ld\c
-\& processes them.
-
-.TP
-.BI "-u " "sym"
-Forces \c
-.I sym\c
-\& to be entered in the output file as an undefined symbol.
-This may, for example, trigger linking of additional modules from
-standard libraries. \c
-.B \-u\c
-\& may be repeated with different option
-arguments to enter additional undefined symbols.
-
-.TP
-.B \-Ur
-For anything other than C++ programs, this option is equivalent to
-\c
-.B \-r\c
-\&: it generates relocatable output\(em\&i.e., an output file that can in
-turn serve as input to \c
-.B ld\c
-\&. When linking C++ programs, \c
-.B \-Ur\c
-\&
-\c
-.I will\c
-\& resolve references to constructors, unlike \c
-.B \-r\c
-\&.
-
-.TP
-.B \-V
-Display the version number for \c
-.B ld
-and list the supported emulations.
-Print which input files can and can not be opened.
-
-.TP
-.B \-v
-Display the version number for \c
-.B ld\c
-\&.
-Print which input files can and can not be opened.
-
-.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
-\|'.
-
+errors during the link process; it exits without writing an output file
+when it issues any error whatsoever.
+.Ip "\f(CW--oformat \fIoutput-format\fR\fR" 4
+\f(CWld\fR may be configured to support more than one kind of object
+file. If your \f(CWld\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(CWld\fR is configured to support alternative
+object formats, you don't usually need to specify this, as \f(CWld\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(CWOUTPUT_FORMAT\fR can also specify the output format, but
+this option overrides it.
+.Ip "\f(CW-qmagic\fR" 4
+This option is ignored for Linux compatibility.
+.Ip "\f(CW-Qy\fR" 4
+This option is ignored for \s-1SVR4\s0 compatibility.
+.Ip "\f(CW--relax\fR" 4
+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--retain-symbols-file \fIfilename\fR\fR" 4
+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-rpath \fIdir\fR\fR" 4
+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-rpath\fR
+arguments are concatenated and passed to the runtime linker, which uses
+them to locate shared objects at runtime. The \f(CW-rpath\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-rpath-link\fR option. If \f(CW-rpath\fR is not used when linking an
+\s-1ELF\s0 executable, the contents of the environment variable
+\f(CWLD_RUN_PATH\fR will be used if it is defined.
+.Sp
+The \f(CW-rpath\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-L\fR options it is given. If a \f(CW-rpath\fR option is used, the
+runtime search path will be formed exclusively using the \f(CW-rpath\fR
+options, ignoring the \f(CW-L\fR options. This can be useful when using
+gcc, which adds many \f(CW-L\fR options which may be on \s-1NFS\s0 mounted
+filesystems.
+.Sp
+For compatibility with other \s-1ELF\s0 linkers, if the \f(CW-R\fR option is
+followed by a directory name, rather than a file name, it is treated as
+the \f(CW-rpath\fR option.
+.Ip "\f(CW-rpath-link \fIDIR\fR\fR" 4
+When using \s-1ELF\s0 or SunOS, one shared library may require another. This
+happens when an \f(CWld -shared\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-rpath-link\fR option
+specifies the first set of directories to search. The
+\f(CW-rpath-link\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.
+.Ip "1." 8
+Any directories specified by \f(CW-rpath-link\fR options.
+.Ip "2." 8
+Any directories specified by \f(CW-rpath\fR options. The difference
+between \f(CW-rpath\fR and \f(CW-rpath-link\fR is that directories
+specified by \f(CW-rpath\fR options are included in the executable and
+used at runtime, whereas the \f(CW-rpath-link\fR option is only effective
+at link time. It is for the native linker only.
+.Ip "3." 8
+On an \s-1ELF\s0 system, if the \f(CW-rpath\fR and \f(CWrpath-link\fR options
+were not used, search the contents of the environment variable
+\f(CWLD_RUN_PATH\fR. It is for the native linker only.
+.Ip "4." 8
+On SunOS, if the \f(CW-rpath\fR option was not used, search any
+directories specified using \f(CW-L\fR options.
+.Ip "5." 8
+For a native linker, the contents of the environment variable
+\f(CWLD_LIBRARY_PATH\fR.
+.Ip "6." 8
+For a native \s-1ELF\s0 linker, the directories in \f(CWDT_RUNPATH\fR or
+\f(CWDT_RPATH\fR of a shared library are searched for shared
+libraries needed by it. The \f(CWDT_RPATH\fR entries are ignored if
+\f(CWDT_RUNPATH\fR entries exist.
+.Ip "7." 8
+The default directories, normally \fI/lib\fR and \fI/usr/lib\fR.
+.Ip "8." 8
+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.
+.Sp
+If the required shared library is not found, the linker will issue a
+warning and continue with the link.
+.Ip "\f(CW-shared\fR" 4
+.Ip "\f(CW-Bshareable\fR" 4
+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-e\fR option is not used and there are
+undefined symbols in the link.
+.Ip "\f(CW--sort-common\fR" 4
+This option tells \f(CWld\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--split-by-file [\fIsize\fR]\fR" 4
+Similar to \f(CW--split-by-reloc\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--split-by-reloc [\fIcount\fR]\fR" 4
+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 \fIcount\fR relocations one output section will contain that
+many relocations. \fIcount\fR defaults to a value of 32768.
+.Ip "\f(CW--stats\fR" 4
+Compute and display statistics about the operation of the linker, such
+as execution time and memory usage.
+.Ip "\f(CW--traditional-format\fR" 4
+For some targets, the output of \f(CWld\fR is different in some ways from
+the output of some existing linker. This switch requests \f(CWld\fR to
+use the traditional format instead.
+.Sp
+For example, on SunOS, \f(CWld\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(CWdbx\fR program can not read the resulting program (\f(CWgdb\fR has no
+trouble). The \fB--traditional-format\fR switch tells \f(CWld\fR to not
+combine duplicate entries.
+.Ip "\f(CW--section-start \fIsectionname\fR=\fIorg\fR\fR" 4
+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-Tbss \fIorg\fR\fR" 4
+.Ip "\f(CW-Tdata \fIorg\fR\fR" 4
+.Ip "\f(CW-Ttext \fIorg\fR\fR" 4
+Use \fIorg\fR as the starting address for---respectively---the
+\f(CWbss\fR, \f(CWdata\fR, or the \f(CWtext\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--dll-verbose\fR" 4
+.Ip "\f(CW--verbose\fR" 4
+Display the version number for \f(CWld\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--version-script=\fIversion-scriptfile\fR\fR" 4
+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--warn-common\fR" 4
+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.
+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:
+.Ip "\fBint i = 1;\fR" 8
+A definition, which goes in the initialized data section of the output
+file.
+.Ip "\fBextern int i;\fR" 8
+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" 8
+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.
+.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.
+.Ip "1." 8
+Turning a common symbol into a reference, because there is already a
+definition for the symbol.
+
+ \fIfile\fR(\fIsection\fR): warning: common of `\fIsymbol\fR\*(R'
+ overridden by definition
+ \fIfile\fR(\fIsection\fR): warning: defined here
+.Ip "2." 8
+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.
+
+ \fIfile\fR(\fIsection\fR): warning: definition of `\fIsymbol\fR\*(R'
+ overriding common
+ \fIfile\fR(\fIsection\fR): warning: common is here
+.Ip "3." 8
+Merging a common symbol with a previous same-sized common symbol.
+
+ \fIfile\fR(\fIsection\fR): warning: multiple common
+ of `\fIsymbol\fR\*(R'
+ \fIfile\fR(\fIsection\fR): warning: previous common is here
+.Ip "4." 8
+Merging a common symbol with a previous larger common symbol.
+
+ \fIfile\fR(\fIsection\fR): warning: common of `\fIsymbol\fR\*(R'
+ overridden by larger common
+ \fIfile\fR(\fIsection\fR): warning: larger common is here
+.Ip "5." 8
+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.
+
+ \fIfile\fR(\fIsection\fR): warning: common of `\fIsymbol\fR\*(R'
+ overriding smaller common
+ \fIfile\fR(\fIsection\fR): warning: smaller common is here
+.Ip "\f(CW--warn-constructors\fR" 4
+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--warn-multiple-gp\fR" 4
+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--warn-once\fR" 4
+Only warn once for each undefined symbol, rather than once per module
+which refers to it.
+.Ip "\f(CW--warn-section-align\fR" 4
+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(CWSECTIONS\fR command does not specify a start address for
+the section.
+.Ip "\f(CW--whole-archive\fR" 4
+For each archive mentioned on the command line after the
+\f(CW--whole-archive\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-Wl,-whole-archive\fR.
+Second, don't forget to use \f(CW-Wl,-no-whole-archive\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--wrap \fIsymbol\fR\fR" 4
+Use a wrapper function for \fIsymbol\fR. Any undefined reference to
+\fIsymbol\fR will be resolved to \f(CW__wrap_\fIsymbol\fR\fR. Any
+undefined reference to \f(CW__real_\fIsymbol\fR\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__wrap_\fIsymbol\fR\fR. If it
+wishes to call the system function, it should call
+\f(CW__real_\fIsymbol\fR\fR.
+.Sp
+Here is a trivial example:
+.Sp
+.Vb 7
+\&
+\& 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--wrap malloc\fR, then
+all calls to \f(CWmalloc\fR will call the function \f(CW__wrap_malloc\fR
+instead. The call to \f(CW__real_malloc\fR in \f(CW__wrap_malloc\fR will
+call the real \f(CWmalloc\fR function.
+.Sp
+You may wish to provide a \f(CW__real_malloc\fR function as well, so that
+links without the \f(CW--wrap\fR option will succeed. If you do this,
+you should not put the definition of \f(CW__real_malloc\fR in the same
+file as \f(CW__wrap_malloc\fR; if you do, the assembler may resolve the
+call before the linker has a chance to wrap it to \f(CWmalloc\fR.
+.Ip "\f(CW--enable-new-dtags\fR" 4
+.Ip "\f(CW--disable-new-dtags\fR" 4
+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--enable-new-dtags\fR, the dynamic tags will be created as needed.
+If you specify \f(CW--disable-new-dtags\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-shared\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*.dll\fR when you
+use this option. In addition, the linker fully supports the standard
+\f(CW*.def\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--add-stdcall-alias\fR" 4
+If given, symbols with a stdcall suffix (@\fInn\fR) will be exported
+as-is and also with the suffix stripped.
+.Ip "\f(CW--base-file \fIfile\fR\fR" 4
+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--dll\fR" 4
+Create a \s-1DLL\s0 instead of a regular executable. You may also use
+\f(CW-shared\fR or specify a \f(CWLIBRARY\fR in a given \f(CW.def\fR
+file.
+.Ip "\f(CW--enable-stdcall-fixup\fR" 4
+.Ip "\f(CW--disable-stdcall-fixup\fR" 4
+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_foo\fR might be linked to the function
+\f(CW_foo@12\fR, or the undefined symbol \f(CW_bar@16\fR might be linked
+to the function \f(CW_bar\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--enable-stdcall-fixup\fR, this
+feature is fully enabled and warnings are not printed. If you specify
+\f(CW--disable-stdcall-fixup\fR, this feature is disabled and such
+mismatches are considered to be errors.
+.Ip "\f(CW--export-all-symbols\fR" 4
+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(CWDllMain@12\fR,
+\f(CWDllEntryPoint@0\fR, and \f(CWimpure_ptr\fR will not be automatically
+exported.
+.Ip "\f(CW--exclude-symbols \fIsymbol\fR,\fIsymbol\fR,...\fR" 4
+Specifies a list of symbols which should not be automatically
+exported. The symbol names may be delimited by commas or colons.
+.Ip "\f(CW--file-alignment\fR" 4
+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--heap \fIreserve\fR\fR" 4
+.Ip "\f(CW--heap \fIreserve\fR,\fIcommit\fR\fR" 4
+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--image-base \fIvalue\fR\fR" 4
+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--kill-at\fR" 4
+If given, the stdcall suffixes (@\fInn\fR) will be stripped from
+symbols before they are exported.
+.Ip "\f(CW--major-image-version \fIvalue\fR\fR" 4
+Sets the major number of the \*(L"image version\*(R". Defaults to 1.
+.Ip "\f(CW--major-os-version \fIvalue\fR\fR" 4
+Sets the major number of the \*(L"os version\*(R". Defaults to 4.
+.Ip "\f(CW--major-subsystem-version \fIvalue\fR\fR" 4
+Sets the major number of the \*(L"subsystem version\*(R". Defaults to 4.
+.Ip "\f(CW--minor-image-version \fIvalue\fR\fR" 4
+Sets the minor number of the \*(L"image version\*(R". Defaults to 0.
+.Ip "\f(CW--minor-os-version \fIvalue\fR\fR" 4
+Sets the minor number of the \*(L"os version\*(R". Defaults to 0.
+.Ip "\f(CW--minor-subsystem-version \fIvalue\fR\fR" 4
+Sets the minor number of the \*(L"subsystem version\*(R". Defaults to 0.
+.Ip "\f(CW--output-def \fIfile\fR\fR" 4
+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*.def\fR) may be used to create an import
+library with \f(CWdlltool\fR or may be used as a reference to
+automatically or implicitly exported symbols.
+.Ip "\f(CW--section-alignment\fR" 4
+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--stack \fIreserve\fR\fR" 4
+.Ip "\f(CW--stack \fIreserve\fR,\fIcommit\fR\fR" 4
+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--subsystem \fIwhich\fR\fR" 4
+.Ip "\f(CW--subsystem \fIwhich\fR:\fImajor\fR\fR" 4
+.Ip "\f(CW--subsystem \fIwhich\fR:\fImajor\fR.\fIminor\fR\fR" 4
+Specifies the subsystem under which your program will execute. The
+legal values for \fIwhich\fR are \f(CWnative\fR, \f(CWwindows\fR,
+\f(CWconsole\fR, and \f(CWposix\fR. You may optionally set the
+subsystem version also.
+.SH "ENVIRONMENT"
+You can change the behavior of \f(CWld\fR with the environment variables
+\f(CWGNUTARGET\fR, \f(CWLDEMULATION\fR, and \f(CWCOLLECT_NO_DEMANGLE\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(CWGNUTARGET\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 BFD names for an input format. If there is no
+\f(CWGNUTARGET\fR in the environment, \f(CWld\fR uses the natural format
+of the target. If \f(CWGNUTARGET\fR is set to \f(CWdefault\fR 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 specify
+object-file formats is unique. However, the configuration procedure for
+BFD on each system places the conventional format for that system first
+in the search-list, so ambiguities are resolved in favor of convention.
+.PP
+\f(CWLDEMULATION\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(CWLDEMULATION\fR environment
+variable is not defined, the default emulation depends upon how the
+linker was configured.
.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.
+Normally, the linker will default to demangling symbols. However, if
+\f(CWCOLLECT_NO_DEMANGLE\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(CWgcc\fR linker wrapper program. The default
+may be overridden by the \fB--demangle\fR and \fB--no-demangle\fR
+options.
+.SH "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"
+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 GNU 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"GNU Free Documentation License\*(R".
+
+.rn }` ''
+.IX Title "LD 1"
+.IX Name "ld - Using LD, the GNU linker"
+
+.IX Header "NAME"
+
+.IX Header "SYNOPSIS"
+
+.IX Header "DESCRIPTION"
+
+.IX Header "OPTIONS"
+
+.IX Item "\f(CW-a\fIkeyword\fR\fR"
+
+.IX Item "\f(CW-A\fIarchitecture\fR\fR"
+
+.IX Item "\f(CW--architecture=\fIarchitecture\fR\fR"
+
+.IX Item "\f(CW-b \fIinput-format\fR\fR"
+
+.IX Item "\f(CW--format=\fIinput-format\fR\fR"
+
+.IX Item "\f(CW-c \fIMRI-commandfile\fR\fR"
+
+.IX Item "\f(CW--mri-script=\fIMRI-commandfile\fR\fR"
+
+.IX Item "\f(CW-d\fR"
+
+.IX Item "\f(CW-dc\fR"
+
+.IX Item "\f(CW-dp\fR"
+
+.IX Item "\f(CW-e \fIentry\fR\fR"
+
+.IX Item "\f(CW--entry=\fIentry\fR\fR"
+
+.IX Item "\f(CW-E\fR"
+
+.IX Item "\f(CW--export-dynamic\fR"
+
+.IX Item "\f(CW-EB\fR"
+
+.IX Item "\f(CW-EL\fR"
+
+.IX Item "\f(CW-f\fR"
+
+.IX Item "\f(CW--auxiliary \fIname\fR\fR"
+
+.IX Item "\f(CW-F \fIname\fR\fR"
+
+.IX Item "\f(CW--filter \fIname\fR\fR"
+
+.IX Item "\f(CW-fini \fIname\fR\fR"
+
+.IX Item "\f(CW-g\fR"
+
+.IX Item "\f(CW-G\fIvalue\fR\fR"
+
+.IX Item "\f(CW--gpsize=\fIvalue\fR\fR"
+
+.IX Item "\f(CW-h\fIname\fR\fR"
+
+.IX Item "\f(CW-soname=\fIname\fR\fR"
+
+.IX Item "\f(CW-i\fR"
+
+.IX Item "\f(CW-init \fIname\fR\fR"
+
+.IX Item "\f(CW-l\fIarchive\fR\fR"
+
+.IX Item "\f(CW--library=\fIarchive\fR\fR"
+
+.IX Item "\f(CW-L\fIsearchdir\fR\fR"
+
+.IX Item "\f(CW--library-path=\fIsearchdir\fR\fR"
+
+.IX Item "\f(CW-m\fIemulation\fR\fR"
+
+.IX Item "\f(CW-M\fR"
+
+.IX Item "\f(CW--print-map\fR"
+
+.IX Item "\(bu"
+
+.IX Item "\(bu"
+
+.IX Item "\(bu"
+
+.IX Item "\f(CW-n\fR"
+
+.IX Item "\f(CW--nmagic\fR"
+
+.IX Item "\f(CW-N\fR"
+
+.IX Item "\f(CW--omagic\fR"
+
+.IX Item "\f(CW-o \fIoutput\fR\fR"
+
+.IX Item "\f(CW--output=\fIoutput\fR\fR"
+
+.IX Item "\f(CW-O \fIlevel\fR\fR"
+
+.IX Item "\f(CW-q\fR"
+
+.IX Item "\f(CW--emit-relocs\fR"
+
+.IX Item "\f(CW-r\fR"
+
+.IX Item "\f(CW--relocateable\fR"
+
+.IX Item "\f(CW-R \fIfilename\fR\fR"
+
+.IX Item "\f(CW--just-symbols=\fIfilename\fR\fR"
+
+.IX Item "\f(CW-s\fR"
+
+.IX Item "\f(CW--strip-all\fR"
+
+.IX Item "\f(CW-S\fR"
+
+.IX Item "\f(CW--strip-debug\fR"
+
+.IX Item "\f(CW-t\fR"
+
+.IX Item "\f(CW--trace\fR"
+
+.IX Item "\f(CW-T \fIscriptfile\fR\fR"
+
+.IX Item "\f(CW--script=\fIscriptfile\fR\fR"
+
+.IX Item "\f(CW-u \fIsymbol\fR\fR"
+
+.IX Item "\f(CW--undefined=\fIsymbol\fR\fR"
+
+.IX Item "\f(CW-Ur\fR"
+
+.IX Item "\f(CW--unique[=\fISECTION\fR]\fR"
+
+.IX Item "\f(CW-v\fR"
+
+.IX Item "\f(CW--version\fR"
+
+.IX Item "\f(CW-V\fR"
+
+.IX Item "\f(CW-x\fR"
+
+.IX Item "\f(CW--discard-all\fR"
+
+.IX Item "\f(CW-X\fR"
+
+.IX Item "\f(CW--discard-locals\fR"
+
+.IX Item "\f(CW-y \fIsymbol\fR\fR"
+
+.IX Item "\f(CW--trace-symbol=\fIsymbol\fR\fR"
+
+.IX Item "\f(CW-Y \fIpath\fR\fR"
+
+.IX Item "\f(CW-z \fIkeyword\fR\fR"
+
+.IX Item "\f(CW-( \fIarchives\fR -)\fR"
+
+.IX Item "\f(CW--start-group \fIarchives\fR --end-group\fR"
+
+.IX Item "\f(CW-assert \fIkeyword\fR\fR"
+
+.IX Item "\f(CW-Bdynamic\fR"
+
+.IX Item "\f(CW-dy\fR"
+
+.IX Item "\f(CW-call_shared\fR"
+
+.IX Item "\f(CW-Bgroup\fR"
+
+.IX Item "\f(CW-Bstatic\fR"
+
+.IX Item "\f(CW-dn\fR"
+
+.IX Item "\f(CW-non_shared\fR"
+
+.IX Item "\f(CW-static\fR"
+
+.IX Item "\f(CW-Bsymbolic\fR"
+
+.IX Item "\f(CW--check-sections\fR"
+
+.IX Item "\f(CW--no-check-sections\fR"
+
+.IX Item "\f(CW--cref\fR"
+
+.IX Item "\f(CW--defsym \fIsymbol\fR=\fIexpression\fR\fR"
+
+.IX Item "\f(CW--demangle[=\fIstyle\fR]\fR"
+
+.IX Item "\f(CW--no-demangle\fR"
+
+.IX Item "\f(CW--dynamic-linker \fIfile\fR\fR"
+
+.IX Item "\f(CW--embedded-relocs\fR"
+
+.IX Item "\f(CW--force-exe-suffix\fR"
+
+.IX Item "\f(CW--no-gc-sections\fR"
+
+.IX Item "\f(CW--gc-sections\fR"
+
+.IX Item "\f(CW--help\fR"
+
+.IX Item "\f(CW--target-help\fR"
+
+.IX Item "\f(CW-Map \fImapfile\fR\fR"
+
+.IX Item "\f(CW--no-keep-memory\fR"
+
+.IX Item "\f(CW--no-undefined\fR"
+
+.IX Item "\f(CW-z defs\fR"
+
+.IX Item "\f(CW--allow-shlib-undefined\fR"
+
+.IX Item "\f(CW--no-warn-mismatch\fR"
+
+.IX Item "\f(CW--no-whole-archive\fR"
+
+.IX Item "\f(CW--noinhibit-exec\fR"
+
+.IX Item "\f(CW--oformat \fIoutput-format\fR\fR"
+
+.IX Item "\f(CW-qmagic\fR"
+
+.IX Item "\f(CW-Qy\fR"
+
+.IX Item "\f(CW--relax\fR"
+
+.IX Item "\f(CW--retain-symbols-file \fIfilename\fR\fR"
+
+.IX Item "\f(CW-rpath \fIdir\fR\fR"
+
+.IX Item "\f(CW-rpath-link \fIDIR\fR\fR"
+
+.IX Item "1."
+
+.IX Item "2."
+
+.IX Item "3."
+
+.IX Item "4."
+
+.IX Item "5."
+
+.IX Item "6."
+
+.IX Item "7."
+
+.IX Item "8."
+
+.IX Item "\f(CW-shared\fR"
+
+.IX Item "\f(CW-Bshareable\fR"
+
+.IX Item "\f(CW--sort-common\fR"
+
+.IX Item "\f(CW--split-by-file [\fIsize\fR]\fR"
+
+.IX Item "\f(CW--split-by-reloc [\fIcount\fR]\fR"
+
+.IX Item "\f(CW--stats\fR"
+
+.IX Item "\f(CW--traditional-format\fR"
+
+.IX Item "\f(CW--section-start \fIsectionname\fR=\fIorg\fR\fR"
+
+.IX Item "\f(CW-Tbss \fIorg\fR\fR"
+
+.IX Item "\f(CW-Tdata \fIorg\fR\fR"
+
+.IX Item "\f(CW-Ttext \fIorg\fR\fR"
+
+.IX Item "\f(CW--dll-verbose\fR"
+
+.IX Item "\f(CW--verbose\fR"
+
+.IX Item "\f(CW--version-script=\fIversion-scriptfile\fR\fR"
+
+.IX Item "\f(CW--warn-common\fR"
+
+.IX Item "\fBint i = 1;\fR"
+
+.IX Item "\fBextern int i;\fR"
+
+.IX Item "\fBint i;\fR"
+
+.IX Item "1."
+
+.IX Item "2."
+
+.IX Item "3."
+
+.IX Item "4."
+
+.IX Item "5."
+
+.IX Item "\f(CW--warn-constructors\fR"
+
+.IX Item "\f(CW--warn-multiple-gp\fR"
+
+.IX Item "\f(CW--warn-once\fR"
+
+.IX Item "\f(CW--warn-section-align\fR"
+
+.IX Item "\f(CW--whole-archive\fR"
+
+.IX Item "\f(CW--wrap \fIsymbol\fR\fR"
+
+.IX Item "\f(CW--enable-new-dtags\fR"
+
+.IX Item "\f(CW--disable-new-dtags\fR"
+
+.IX Item "\f(CW--add-stdcall-alias\fR"
+
+.IX Item "\f(CW--base-file \fIfile\fR\fR"
+
+.IX Item "\f(CW--dll\fR"
+
+.IX Item "\f(CW--enable-stdcall-fixup\fR"
+
+.IX Item "\f(CW--disable-stdcall-fixup\fR"
+
+.IX Item "\f(CW--export-all-symbols\fR"
+
+.IX Item "\f(CW--exclude-symbols \fIsymbol\fR,\fIsymbol\fR,...\fR"
+
+.IX Item "\f(CW--file-alignment\fR"
+
+.IX Item "\f(CW--heap \fIreserve\fR\fR"
+
+.IX Item "\f(CW--heap \fIreserve\fR,\fIcommit\fR\fR"
+
+.IX Item "\f(CW--image-base \fIvalue\fR\fR"
+
+.IX Item "\f(CW--kill-at\fR"
+
+.IX Item "\f(CW--major-image-version \fIvalue\fR\fR"
+
+.IX Item "\f(CW--major-os-version \fIvalue\fR\fR"
+
+.IX Item "\f(CW--major-subsystem-version \fIvalue\fR\fR"
+
+.IX Item "\f(CW--minor-image-version \fIvalue\fR\fR"
+
+.IX Item "\f(CW--minor-os-version \fIvalue\fR\fR"
+
+.IX Item "\f(CW--minor-subsystem-version \fIvalue\fR\fR"
+
+.IX Item "\f(CW--output-def \fIfile\fR\fR"
+
+.IX Item "\f(CW--section-alignment\fR"
+
+.IX Item "\f(CW--stack \fIreserve\fR\fR"
+
+.IX Item "\f(CW--stack \fIreserve\fR,\fIcommit\fR\fR"
+
+.IX Item "\f(CW--subsystem \fIwhich\fR\fR"
+
+.IX Item "\f(CW--subsystem \fIwhich\fR:\fImajor\fR\fR"
+
+.IX Item "\f(CW--subsystem \fIwhich\fR:\fImajor\fR.\fIminor\fR\fR"
+
+.IX Header "ENVIRONMENT"
+
+.IX Header "SEE ALSO"
+
+.IX Header "COPYRIGHT"
+
projects / deliverable / binutils-gdb.git / blobdiff