-diff -urN binutils-2.11.90.0.19.org/bfd/doc/bfd.texinfo binutils-2.11.90.0.19/bfd/doc/bfd.texinfo
---- binutils-2.11.90.0.19.org/bfd/doc/bfd.texinfo Fri Jun 22 13:48:05 2001
-+++ binutils-2.11.90.0.19/bfd/doc/bfd.texinfo Fri Jun 22 13:48:45 2001
+diff -urN binutils-2.12.90.0.1.org/bfd/doc/bfd.texinfo binutils-2.12.90.0.1/bfd/doc/bfd.texinfo
+--- binutils-2.12.90.0.1.org/bfd/doc/bfd.texinfo Mon Mar 11 22:37:36 2002
++++ binutils-2.12.90.0.1/bfd/doc/bfd.texinfo Mon Mar 11 22:37:52 2002
@@ -21,9 +21,10 @@
@ifinfo
@end format
@end ifinfo
-diff -urN binutils-2.11.90.0.19.org/binutils/doc/binutils.texi binutils-2.11.90.0.19/binutils/doc/binutils.texi
---- binutils-2.11.90.0.19.org/binutils/doc/binutils.texi Fri Jun 22 13:48:07 2001
-+++ binutils-2.11.90.0.19/binutils/doc/binutils.texi Fri Jun 22 14:44:43 2001
+diff -urN binutils-2.12.90.0.1.org/binutils/doc/binutils.texi binutils-2.12.90.0.1/binutils/doc/binutils.texi
+--- binutils-2.12.90.0.1.org/binutils/doc/binutils.texi Mon Mar 11 22:37:37 2002
++++ binutils-2.12.90.0.1/binutils/doc/binutils.texi Mon Mar 11 22:37:52 2002
@@ -6,24 +6,26 @@
@ifinfo
@end format
@end ifinfo
-diff -urN binutils-2.11.90.0.19.org/etc/configure.texi binutils-2.11.90.0.19/etc/configure.texi
---- binutils-2.11.90.0.19.org/etc/configure.texi Fri Jun 22 13:48:06 2001
-+++ binutils-2.11.90.0.19/etc/configure.texi Fri Jun 22 13:48:45 2001
+diff -urN binutils-2.12.90.0.1.org/etc/configure.texi binutils-2.12.90.0.1/etc/configure.texi
+--- binutils-2.12.90.0.1.org/etc/configure.texi Mon Mar 11 22:37:37 2002
++++ binutils-2.12.90.0.1/etc/configure.texi Mon Mar 11 22:37:52 2002
@@ -5,9 +5,9 @@
@setchapternewpage off
@c %**end of header
@end direntry
@ifinfo
-diff -urN binutils-2.11.90.0.19.org/etc/standards.texi binutils-2.11.90.0.19/etc/standards.texi
---- binutils-2.11.90.0.19.org/etc/standards.texi Fri Jun 22 13:48:06 2001
-+++ binutils-2.11.90.0.19/etc/standards.texi Fri Jun 22 13:48:45 2001
+diff -urN binutils-2.12.90.0.1.org/etc/standards.texi binutils-2.12.90.0.1/etc/standards.texi
+--- binutils-2.12.90.0.1.org/etc/standards.texi Mon Mar 11 22:37:37 2002
++++ binutils-2.12.90.0.1/etc/standards.texi Mon Mar 11 22:37:52 2002
@@ -8,9 +8,10 @@
@ifinfo
@end format
@end ifinfo
-diff -urN binutils-2.11.90.0.19.org/gas/doc/as.texinfo binutils-2.11.90.0.19/gas/doc/as.texinfo
---- binutils-2.11.90.0.19.org/gas/doc/as.texinfo Fri Jun 22 13:48:08 2001
-+++ binutils-2.11.90.0.19/gas/doc/as.texinfo Fri Jun 22 13:48:46 2001
-@@ -108,9 +108,10 @@
+diff -urN binutils-2.12.90.0.1.org/gas/doc/as.texinfo binutils-2.12.90.0.1/gas/doc/as.texinfo
+--- binutils-2.12.90.0.1.org/gas/doc/as.texinfo Mon Mar 11 22:37:38 2002
++++ binutils-2.12.90.0.1/gas/doc/as.texinfo Mon Mar 11 22:40:25 2002
+@@ -117,10 +117,11 @@
@ifinfo
@format
-START-INFO-DIR-ENTRY
--* As: (as). The GNU assembler.
--END-INFO-DIR-ENTRY
+@dircategory Programming tools:
+@direntry
-+* As: (as). The GNU assembler
+ * As: (as). The GNU assembler.
+ * Gas: (as). The GNU assembler.
+-END-INFO-DIR-ENTRY
+@end direntry
@end format
@end ifinfo
-diff -urN binutils-2.11.90.0.19.org/gas/doc/gasp.texi binutils-2.11.90.0.19/gas/doc/gasp.texi
---- binutils-2.11.90.0.19.org/gas/doc/gasp.texi Fri Jun 22 13:48:08 2001
-+++ binutils-2.11.90.0.19/gas/doc/gasp.texi Fri Jun 22 13:48:46 2001
+diff -urN binutils-2.12.90.0.1.org/gas/doc/gasp.texi binutils-2.12.90.0.1/gas/doc/gasp.texi
+--- binutils-2.12.90.0.1.org/gas/doc/gasp.texi Mon Mar 11 22:37:38 2002
++++ binutils-2.12.90.0.1/gas/doc/gasp.texi Mon Mar 11 22:37:52 2002
@@ -14,9 +14,10 @@
@ifinfo
@end format
@end ifinfo
-diff -urN binutils-2.11.90.0.19.org/gprof/gprof.texi binutils-2.11.90.0.19/gprof/gprof.texi
---- binutils-2.11.90.0.19.org/gprof/gprof.texi Fri Jun 22 13:48:22 2001
-+++ binutils-2.11.90.0.19/gprof/gprof.texi Fri Jun 22 13:48:46 2001
+diff -urN binutils-2.12.90.0.1.org/gprof/gprof.texi binutils-2.12.90.0.1/gprof/gprof.texi
+--- binutils-2.12.90.0.1.org/gprof/gprof.texi Mon Mar 11 22:37:40 2002
++++ binutils-2.12.90.0.1/gprof/gprof.texi Mon Mar 11 22:37:52 2002
@@ -9,9 +9,10 @@
@c This is a dir.info fragment to support semi-automated addition of
@c manuals to an info tree. zoo@cygnus.com is developing this facility.
@end format
@end ifinfo
-diff -urN binutils-2.11.90.0.19.org/ld/ld.texinfo binutils-2.11.90.0.19/ld/ld.texinfo
---- binutils-2.11.90.0.19.org/ld/ld.texinfo Fri Jun 22 13:48:24 2001
-+++ binutils-2.11.90.0.19/ld/ld.texinfo Fri Jun 22 13:48:46 2001
-@@ -43,9 +43,10 @@
+diff -urN binutils-2.12.90.0.1.org/ld/ld.texinfo binutils-2.12.90.0.1/ld/ld.texinfo
+--- binutils-2.12.90.0.1.org/ld/ld.texinfo Mon Mar 11 22:37:41 2002
++++ binutils-2.12.90.0.1/ld/ld.texinfo Mon Mar 11 22:37:52 2002
+@@ -48,9 +48,10 @@
@ifinfo
@format
@end format
@end ifinfo
-@@ -4283,7 +4284,7 @@
+@@ -4590,7 +4591,7 @@
@node BFD outline
@section How it works: an outline of BFD
@cindex opening object files
@end ifclear
@node Reporting Bugs
+diff -urN binutils-2.12.90.0.1.org/ld/ld.texinfo.orig binutils-2.12.90.0.1/ld/ld.texinfo.orig
+--- binutils-2.12.90.0.1.org/ld/ld.texinfo.orig Thu Jan 1 01:00:00 1970
++++ binutils-2.12.90.0.1/ld/ld.texinfo.orig Thu Mar 7 20:52:39 2002
+@@ -0,0 +1,5325 @@
++\input texinfo
++@setfilename ld.info
++@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
++@c 2001, 2002 Free Software Foundation, Inc.
++@syncodeindex ky cp
++@include configdoc.texi
++@c (configdoc.texi is generated by the Makefile)
++@include ldver.texi
++
++@c @smallbook
++
++@macro gcctabopt{body}
++@code{\body\}
++@end macro
++
++@c man begin NAME
++@ifset man
++@c Configure for the generation of man pages
++@set UsesEnvVars
++@set GENERIC
++@set A29K
++@set ARC
++@set ARM
++@set D10V
++@set D30V
++@set H8/300
++@set H8/500
++@set HPPA
++@set I370
++@set I80386
++@set I860
++@set I960
++@set M32R
++@set M68HC11
++@set M680X0
++@set MCORE
++@set MIPS
++@set MMIX
++@set PDP11
++@set PJ
++@set SH
++@set SPARC
++@set C54X
++@set V850
++@set VAX
++@end ifset
++@c man end
++
++@ifinfo
++@format
++START-INFO-DIR-ENTRY
++* Ld: (ld). The GNU linker.
++END-INFO-DIR-ENTRY
++@end format
++@end ifinfo
++
++@ifinfo
++This file documents the @sc{gnu} linker LD version @value{VERSION}.
++
++Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
++2001, 2002 Free Software Foundation, Inc.
++
++@ignore
++
++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 "GNU Free Documentation License".
++
++Permission is granted to process this file through Tex and print the
++results, provided the printed document carries copying permission
++notice identical to this one except for the removal of this paragraph
++(this paragraph not being relevant to the printed manual).
++
++@end ignore
++@end ifinfo
++@iftex
++@finalout
++@setchapternewpage odd
++@settitle Using LD, the GNU linker
++@titlepage
++@title Using ld
++@subtitle The GNU linker
++@sp 1
++@subtitle @code{ld} version 2
++@subtitle Version @value{VERSION}
++@author Steve Chamberlain
++@author Ian Lance Taylor
++@page
++
++@tex
++{\parskip=0pt
++\hfill Red Hat Inc\par
++\hfill nickc\@credhat.com, doc\@redhat.com\par
++\hfill {\it Using LD, the GNU linker}\par
++\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
++}
++\global\parindent=0pt % Steve likes it this way.
++@end tex
++
++@vskip 0pt plus 1filll
++@c man begin COPYRIGHT
++Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
++
++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 "GNU Free Documentation License".
++@c man end
++
++@end titlepage
++@end iftex
++@c FIXME: Talk about importance of *order* of args, cmds to linker!
++
++@ifinfo
++@node Top
++@top Using ld
++This file documents the @sc{gnu} linker ld version @value{VERSION}.
++
++This document is distributed under the terms of the GNU Free
++Documentation License. A copy of the license is included in the
++section entitled "GNU Free Documentation License".
++
++@menu
++* Overview:: Overview
++* Invocation:: Invocation
++* Scripts:: Linker Scripts
++@ifset GENERIC
++* Machine Dependent:: Machine Dependent Features
++@end ifset
++@ifclear GENERIC
++@ifset H8300
++* H8/300:: ld and the H8/300
++@end ifset
++@ifset Hitachi
++* Hitachi:: ld and other Hitachi micros
++@end ifset
++@ifset I960
++* i960:: ld and the Intel 960 family
++@end ifset
++@ifset TICOFF
++* TI COFF:: ld and the TI COFF
++@end ifset
++@end ifclear
++@ifclear SingleFormat
++* BFD:: BFD
++@end ifclear
++@c Following blank line required for remaining bug in makeinfo conds/menus
++
++* Reporting Bugs:: Reporting Bugs
++* MRI:: MRI Compatible Script Files
++* GNU Free Documentation License:: GNU Free Documentation License
++* Index:: Index
++@end menu
++@end ifinfo
++
++@node Overview
++@chapter Overview
++
++@cindex @sc{gnu} linker
++@cindex what is this?
++
++@ifset man
++@c man begin SYNOPSIS
++ld [@b{options}] @var{objfile} @dots{}
++@c man end
++
++@c man begin SEEALSO
++ar(1), nm(1), objcopy(1), objdump(1), readelf(1) and
++the Info entries for @file{binutils} and
++@file{ld}.
++@c man end
++@end ifset
++
++@c man begin DESCRIPTION
++
++@command{ld} 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 @command{ld}.
++
++@command{ld} 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.
++
++@ifset man
++@c For the man only
++This man page does not describe the command language; see the
++@command{ld} entry in @code{info}, or the manual
++ld: the GNU linker, for full details on the command language and
++on other aspects of the GNU linker.
++@end ifset
++
++@ifclear SingleFormat
++This version of @command{ld} uses the general purpose BFD libraries
++to operate on object files. This allows @command{ld} to read, combine, and
++write object files in many different formats---for example, COFF or
++@code{a.out}. Different formats may be linked together to produce any
++available kind of object file. @xref{BFD}, for more information.
++@end ifclear
++
++Aside from its flexibility, the @sc{gnu} linker is more helpful than other
++linkers in providing diagnostic information. Many linkers abandon
++execution immediately upon encountering an error; whenever possible,
++@command{ld} continues executing, allowing you to identify other errors
++(or, in some cases, to get an output file in spite of the error).
++
++@c man end
++
++@node Invocation
++@chapter Invocation
++
++@c man begin DESCRIPTION
++
++The @sc{gnu} linker @command{ld} 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.
++
++@c man end
++
++@ifset UsesEnvVars
++@menu
++* Options:: Command Line Options
++* Environment:: Environment Variables
++@end menu
++
++@node Options
++@section Command Line Options
++@end ifset
++
++@cindex command line
++@cindex options
++
++@c man begin OPTIONS
++
++The linker supports a plethora of command-line options, but in actual
++practice few of them are used in any particular context.
++@cindex standard Unix system
++For instance, a frequent use of @command{ld} is to link standard Unix
++object files on a standard, supported Unix system. On such a system, to
++link a file @code{hello.o}:
++
++@smallexample
++ld -o @var{output} /lib/crt0.o hello.o -lc
++@end smallexample
++
++This tells @command{ld} to produce a file called @var{output} as the
++result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
++the library @code{libc.a}, which will come from the standard search
++directories. (See the discussion of the @samp{-l} option below.)
++
++Some of the command-line options to @command{ld} may be specified at any
++point in the command line. However, options which refer to files, such
++as @samp{-l} or @samp{-T}, 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 that
++option. Options which may be meaningfully specified more than once are
++noted in the descriptions below.
++
++@cindex object files
++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.
++
++Usually the linker is invoked with at least one object file, but you can
++specify other forms of binary input files using @samp{-l}, @samp{-R},
++and the script command language. If @emph{no} binary input files at all
++are specified, the linker does not produce any output, and issues the
++message @samp{No input files}.
++
++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 @samp{-T}). 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
++@code{INPUT} or @code{GROUP} to load other objects. Note that
++specifying a script in this way merely augments the main linker script;
++use the @samp{-T} option to replace the default linker script entirely.
++@xref{Scripts}.
++
++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.
++
++For options whose names are multiple letters, either one dash or two can
++precede the option name; for example, @samp{-trace-symbol} and
++@samp{--trace-symbol} 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
++@samp{-o} option. So for example @samp{-omagic} sets the output file
++name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the
++output.
++
++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,
++@samp{--trace-symbol foo} and @samp{--trace-symbol=foo} are equivalent.
++Unique abbreviations of the names of multiple-letter options are
++accepted.
++
++Note - if the linker is being invoked indirectly, via a compiler driver
++(eg @samp{gcc}) then all the linker command line options should be
++prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
++compiler driver) like this:
++
++@smallexample
++ gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
++@end smallexample
++
++This is important, because otherwise the compiler driver program may
++silently drop the linker options, resulting in a bad link.
++
++Here is a table of the generic command line switches accepted by the GNU
++linker:
++
++@table @gcctabopt
++@kindex -a@var{keyword}
++@item -a@var{keyword}
++This option is supported for HP/UX compatibility. The @var{keyword}
++argument must be one of the strings @samp{archive}, @samp{shared}, or
++@samp{default}. @samp{-aarchive} is functionally equivalent to
++@samp{-Bstatic}, and the other two keywords are functionally equivalent
++to @samp{-Bdynamic}. This option may be used any number of times.
++
++@ifset I960
++@cindex architectures
++@kindex -A@var{arch}
++@item -A@var{architecture}
++@kindex --architecture=@var{arch}
++@itemx --architecture=@var{architecture}
++In the current release of @command{ld}, this option is useful only for the
++Intel 960 family of architectures. In that @command{ld} configuration, the
++@var{architecture} argument identifies the particular architecture in
++the 960 family, enabling some safeguards and modifying the
++archive-library search path. @xref{i960,,@command{ld} and the Intel 960
++family}, for details.
++
++Future releases of @command{ld} may support similar functionality for
++other architecture families.
++@end ifset
++
++@ifclear SingleFormat
++@cindex binary input format
++@kindex -b @var{format}
++@kindex --format=@var{format}
++@cindex input format
++@cindex input format
++@item -b @var{input-format}
++@itemx --format=@var{input-format}
++@command{ld} may be configured to support more than one kind of object
++file. If your @command{ld} is configured this way, you can use the
++@samp{-b} option to specify the binary format for input object files
++that follow this option on the command line. Even when @command{ld} is
++configured to support alternative object formats, you don't usually need
++to specify this, as @command{ld} should be configured to expect as a
++default input format the most usual format on each machine.
++@var{input-format} is a text string, the name of a particular format
++supported by the BFD libraries. (You can list the available binary
++formats with @samp{objdump -i}.)
++@xref{BFD}.
++
++You may want to use this option if you are linking files with an unusual
++binary format. You can also use @samp{-b} to switch formats explicitly (when
++linking object files of different formats), by including
++@samp{-b @var{input-format}} before each group of object files in a
++particular format.
++
++The default format is taken from the environment variable
++@code{GNUTARGET}.
++@ifset UsesEnvVars
++@xref{Environment}.
++@end ifset
++You can also define the input format from a script, using the command
++@code{TARGET};
++@ifclear man
++see @ref{Format Commands}.
++@end ifclear
++@end ifclear
++
++@kindex -c @var{MRI-cmdfile}
++@kindex --mri-script=@var{MRI-cmdfile}
++@cindex compatibility, MRI
++@item -c @var{MRI-commandfile}
++@itemx --mri-script=@var{MRI-commandfile}
++For compatibility with linkers produced by MRI, @command{ld} accepts script
++files written in an alternate, restricted command language, described in
++@ifclear man
++@ref{MRI,,MRI Compatible Script Files}.
++@end ifclear
++@ifset man
++the MRI Compatible Script Files section of GNU ld documentation.
++@end ifset
++Introduce MRI script files with
++the option @samp{-c}; use the @samp{-T} option to run linker
++scripts written in the general-purpose @command{ld} scripting language.
++If @var{MRI-cmdfile} does not exist, @command{ld} looks for it in the directories
++specified by any @samp{-L} options.
++
++@cindex common allocation
++@kindex -d
++@kindex -dc
++@kindex -dp
++@item -d
++@itemx -dc
++@itemx -dp
++These three options are equivalent; multiple forms are supported for
++compatibility with other linkers. They assign space to common symbols
++even if a relocatable output file is specified (with @samp{-r}). The
++script command @code{FORCE_COMMON_ALLOCATION} has the same effect.
++@xref{Miscellaneous Commands}.
++
++@cindex entry point, from command line
++@kindex -e @var{entry}
++@kindex --entry=@var{entry}
++@item -e @var{entry}
++@itemx --entry=@var{entry}
++Use @var{entry} as the explicit symbol for beginning execution of your
++program, rather than the default entry point. If there is no symbol
++named @var{entry}, the linker will try to parse @var{entry} as a number,
++and use that as the entry address (the number will be interpreted in
++base 10; you may use a leading @samp{0x} for base 16, or a leading
++@samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults
++and other ways of specifying the entry point.
++
++@cindex dynamic symbol table
++@kindex -E
++@kindex --export-dynamic
++@item -E
++@itemx --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.
++
++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.
++
++If you use @code{dlopen} 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.
++
++You can also use the version script to control what symbols should
++be added to the dynamic symbol table if the output format supports it.
++See the description of @samp{--version-script} in @ref{VERSION}.
++
++@cindex big-endian objects
++@cindex endianness
++@kindex -EB
++@item -EB
++Link big-endian objects. This affects the default output format.
++
++@cindex little-endian objects
++@kindex -EL
++@item -EL
++Link little-endian objects. This affects the default output format.
++
++@kindex -f
++@kindex --auxiliary
++@item -f
++@itemx --auxiliary @var{name}
++When creating an ELF shared object, set the internal DT_AUXILIARY 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 @var{name}.
++
++If you later link a program against this filter object, then, when you
++run the program, the dynamic linker will see the DT_AUXILIARY 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
++@var{name}. If there is one, it will be used instead of the definition
++in the filter object. The shared object @var{name} need not exist.
++Thus the shared object @var{name} may be used to provide an alternative
++implementation of certain functions, perhaps for debugging or for
++machine specific performance.
++
++This option may be specified more than once. The DT_AUXILIARY entries
++will be created in the order in which they appear on the command line.
++
++@kindex -F
++@kindex --filter
++@item -F @var{name}
++@itemx --filter @var{name}
++When creating an ELF shared object, set the internal DT_FILTER 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 @var{name}.
++
++If you later link a program against this filter object, then, when you
++run the program, the dynamic linker will see the DT_FILTER 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 @var{name}. Thus the filter object can be
++used to select a subset of the symbols provided by the object
++@var{name}.
++
++Some older linkers used the @option{-F} option throughout a compilation
++toolchain for specifying object-file format for both input and output
++object files. The @sc{gnu} linker uses other mechanisms for this
++purpose: the @option{-b}, @option{--format}, @option{--oformat} options, the
++@code{TARGET} command in linker scripts, and the @code{GNUTARGET}
++environment variable. The @sc{gnu} linker will ignore the @option{-F}
++option when not creating an ELF shared object.
++
++@cindex finalization function
++@kindex -fini
++@item -fini @var{name}
++When creating an ELF executable or shared object, call NAME when the
++executable or shared object is unloaded, by setting DT_FINI to the
++address of the function. By default, the linker uses @code{_fini} as
++the function to call.
++
++@kindex -g
++@item -g
++Ignored. Provided for compatibility with other tools.
++
++@kindex -G
++@kindex --gpsize
++@cindex object size
++@item -G@var{value}
++@itemx --gpsize=@var{value}
++Set the maximum size of objects to be optimized using the GP register to
++@var{size}. This is only meaningful for object file formats such as
++MIPS ECOFF which supports putting large and small objects into different
++sections. This is ignored for other object file formats.
++
++@cindex runtime library name
++@kindex -h@var{name}
++@kindex -soname=@var{name}
++@item -h@var{name}
++@itemx -soname=@var{name}
++When creating an ELF shared object, set the internal DT_SONAME field to
++the specified name. When an executable is linked with a shared object
++which has a DT_SONAME field, then when the executable is run the dynamic
++linker will attempt to load the shared object specified by the DT_SONAME
++field rather than the using the file name given to the linker.
++
++@kindex -i
++@cindex incremental link
++@item -i
++Perform an incremental link (same as option @samp{-r}).
++
++@cindex initialization function
++@kindex -init
++@item -init @var{name}
++When creating an ELF executable or shared object, call NAME when the
++executable or shared object is loaded, by setting DT_INIT to the address
++of the function. By default, the linker uses @code{_init} as the
++function to call.
++
++@cindex archive files, from cmd line
++@kindex -l@var{archive}
++@kindex --library=@var{archive}
++@item -l@var{archive}
++@itemx --library=@var{archive}
++Add archive file @var{archive} to the list of files to link. This
++option may be used any number of times. @command{ld} will search its
++path-list for occurrences of @code{lib@var{archive}.a} for every
++@var{archive} specified.
++
++On systems which support shared libraries, @command{ld} may also search for
++libraries with extensions other than @code{.a}. Specifically, on ELF
++and SunOS systems, @command{ld} will search a directory for a library with
++an extension of @code{.so} before searching for one with an extension of
++@code{.a}. By convention, a @code{.so} extension indicates a shared
++library.
++
++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 file(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.
++
++See the @option{-(} option for a way to force the linker to search
++archives multiple times.
++
++You may list the same archive multiple times on the command line.
++
++@ifset GENERIC
++This type of archive searching is standard for Unix linkers. However,
++if you are using @command{ld} on AIX, note that it is different from the
++behaviour of the AIX linker.
++@end ifset
++
++@cindex search directory, from cmd line
++@kindex -L@var{dir}
++@kindex --library-path=@var{dir}
++@item -L@var{searchdir}
++@itemx --library-path=@var{searchdir}
++Add path @var{searchdir} to the list of paths that @command{ld} will search
++for archive libraries and @command{ld} 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
++@option{-L} options apply to all @option{-l} options, regardless of the
++order in which the options appear.
++
++@ifset UsesEnvVars
++The default set of paths searched (without being specified with
++@samp{-L}) depends on which emulation mode @command{ld} is using, and in
++some cases also on how it was configured. @xref{Environment}.
++@end ifset
++
++The paths can also be specified in a link script with the
++@code{SEARCH_DIR} command. Directories specified this way are searched
++at the point in which the linker script appears in the command line.
++
++@cindex emulation
++@kindex -m @var{emulation}
++@item -m@var{emulation}
++Emulate the @var{emulation} linker. You can list the available
++emulations with the @samp{--verbose} or @samp{-V} options.
++
++If the @samp{-m} option is not used, the emulation is taken from the
++@code{LDEMULATION} environment variable, if that is defined.
++
++Otherwise, the default emulation depends upon how the linker was
++configured.
++
++@cindex link map
++@kindex -M
++@kindex --print-map
++@item -M
++@itemx --print-map
++Print a link map to the standard output. A link map provides
++information about the link, including the following:
++
++@itemize @bullet
++@item
++Where object files and symbols are mapped into memory.
++@item
++How common symbols are allocated.
++@item
++All archive members included in the link, with a mention of the symbol
++which caused the archive member to be brought in.
++@end itemize
++
++@kindex -n
++@cindex read-only text
++@cindex NMAGIC
++@kindex --nmagic
++@item -n
++@itemx --nmagic
++Turn off page alignment of sections, and mark the output as
++@code{NMAGIC} if possible.
++
++@kindex -N
++@kindex --omagic
++@cindex read/write from cmd line
++@cindex OMAGIC
++@item -N
++@itemx --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 @code{OMAGIC}.
++
++@kindex -o @var{output}
++@kindex --output=@var{output}
++@cindex naming the output file
++@item -o @var{output}
++@itemx --output=@var{output}
++Use @var{output} as the name for the program produced by @command{ld}; if this
++option is not specified, the name @file{a.out} is used by default. The
++script command @code{OUTPUT} can also specify the output file name.
++
++@kindex -O @var{level}
++@cindex generating optimized output
++@item -O @var{level}
++If @var{level} is a numeric values greater than zero @command{ld} optimizes
++the output. This might take significantly longer and therefore probably
++should only be enabled for the final binary.
++
++@kindex -q
++@kindex --emit-relocs
++@cindex retain relocations in final executable
++@item -q
++@itemx --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.
++
++This option is currently only supported on ELF platforms.
++
++@cindex partial link
++@cindex relocatable output
++@kindex -r
++@kindex --relocateable
++@item -r
++@itemx --relocateable
++Generate relocatable output---i.e., generate an output file that can in
++turn serve as input to @command{ld}. This is often called @dfn{partial
++linking}. As a side effect, in environments that support standard Unix
++magic numbers, this option also sets the output file's magic number to
++@code{OMAGIC}.
++@c ; see @option{-N}.
++If this option is not specified, an absolute file is produced. When
++linking C++ programs, this option @emph{will not} resolve references to
++constructors; to do that, use @samp{-Ur}.
++
++When an input file does not have the same format as the output file,
++partial linking is only supported if that input file does not contain any
++relocations. Different output formats can have further restrictions; for
++example some @code{a.out}-based formats do not support partial linking
++with input files in other formats at all.
++
++This option does the same thing as @samp{-i}.
++
++@kindex -R @var{file}
++@kindex --just-symbols=@var{file}
++@cindex symbol-only input
++@item -R @var{filename}
++@itemx --just-symbols=@var{filename}
++Read symbol names and their addresses from @var{filename}, 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.
++
++For compatibility with other ELF linkers, if the @option{-R} option is
++followed by a directory name, rather than a file name, it is treated as
++the @option{-rpath} option.
++
++@kindex -s
++@kindex --strip-all
++@cindex strip all symbols
++@item -s
++@itemx --strip-all
++Omit all symbol information from the output file.
++
++@kindex -S
++@kindex --strip-debug
++@cindex strip debugger symbols
++@item -S
++@itemx --strip-debug
++Omit debugger symbol information (but not all symbols) from the output file.
++
++@kindex -t
++@kindex --trace
++@cindex input files, displaying
++@item -t
++@itemx --trace
++Print the names of the input files as @command{ld} processes them.
++
++@kindex -T @var{script}
++@kindex --script=@var{script}
++@cindex script files
++@item -T @var{scriptfile}
++@itemx --script=@var{scriptfile}
++Use @var{scriptfile} as the linker script. This script replaces
++@command{ld}'s default linker script (rather than adding to it), so
++@var{commandfile} must specify everything necessary to describe the
++output file. @xref{Scripts}. If @var{scriptfile} does not exist in
++the current directory, @code{ld} looks for it in the directories
++specified by any preceding @samp{-L} options. Multiple @samp{-T}
++options accumulate.
++
++@kindex -u @var{symbol}
++@kindex --undefined=@var{symbol}
++@cindex undefined symbol
++@item -u @var{symbol}
++@itemx --undefined=@var{symbol}
++Force @var{symbol} to be entered in the output file as an undefined
++symbol. Doing this may, for example, trigger linking of additional
++modules from standard libraries. @samp{-u} may be repeated with
++different option arguments to enter additional undefined symbols. This
++option is equivalent to the @code{EXTERN} linker script command.
++
++@kindex -Ur
++@cindex constructors
++@item -Ur
++For anything other than C++ programs, this option is equivalent to
++@samp{-r}: it generates relocatable output---i.e., an output file that can in
++turn serve as input to @command{ld}. When linking C++ programs, @samp{-Ur}
++@emph{does} resolve references to constructors, unlike @samp{-r}.
++It does not work to use @samp{-Ur} on files that were themselves linked
++with @samp{-Ur}; once the constructor table has been built, it cannot
++be added to. Use @samp{-Ur} only for the last partial link, and
++@samp{-r} for the others.
++
++@kindex --unique[=@var{SECTION}]
++@item --unique[=@var{SECTION}]
++Creates a separate output section for every input section matching
++@var{SECTION}, or if the optional wildcard @var{SECTION} 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.
++
++@kindex -v
++@kindex -V
++@kindex --version
++@cindex version
++@item -v
++@itemx --version
++@itemx -V
++Display the version number for @command{ld}. The @option{-V} option also
++lists the supported emulations.
++
++@kindex -x
++@kindex --discard-all
++@cindex deleting local symbols
++@item -x
++@itemx --discard-all
++Delete all local symbols.
++
++@kindex -X
++@kindex --discard-locals
++@cindex local symbols, deleting
++@cindex L, deleting symbols beginning
++@item -X
++@itemx --discard-locals
++Delete all temporary local symbols. For most targets, this is all local
++symbols whose names begin with @samp{L}.
++
++@kindex -y @var{symbol}
++@kindex --trace-symbol=@var{symbol}
++@cindex symbol tracing
++@item -y @var{symbol}
++@itemx --trace-symbol=@var{symbol}
++Print the name of each linked file in which @var{symbol} appears. This
++option may be given any number of times. On many systems it is necessary
++to prepend an underscore.
++
++This option is useful when you have an undefined symbol in your link but
++don't know where the reference is coming from.
++
++@kindex -Y @var{path}
++@item -Y @var{path}
++Add @var{path} to the default library search path. This option exists
++for Solaris compatibility.
++
++@kindex -z @var{keyword}
++@item -z @var{keyword}
++The recognized keywords are @code{initfirst}, @code{interpose},
++@code{loadfltr}, @code{nodefaultlib}, @code{nodelete}, @code{nodlopen},
++@code{nodump}, @code{now}, @code{origin}, @code{combreloc}, @code{nocombreloc}
++and @code{nocopyreloc}.
++The other keywords are
++ignored for Solaris compatibility. @code{initfirst} marks the object
++to be initialized first at runtime before any other objects.
++@code{interpose} marks the object that its symbol table interposes
++before all symbols but the primary executable. @code{loadfltr} marks
++the object that its filtees be processed immediately at runtime.
++@code{nodefaultlib} marks the object that the search for dependencies
++of this object will ignore any default library search paths.
++@code{nodelete} marks the object shouldn't be unloaded at runtime.
++@code{nodlopen} marks the object not available to @code{dlopen}.
++@code{nodump} marks the object can not be dumped by @code{dldump}.
++@code{now} marks the object with the non-lazy runtime binding.
++@code{origin} marks the object may contain $ORIGIN.
++@code{defs} disallows undefined symbols.
++@code{combreloc} combines multiple reloc sections and sorts them
++to make dynamic symbol lookup caching possible.
++@code{nocombreloc} disables multiple reloc sections combining.
++@code{nocopyreloc} disables production of copy relocs.
++
++@kindex -(
++@cindex groups of archives
++@item -( @var{archives} -)
++@itemx --start-group @var{archives} --end-group
++The @var{archives} should be a list of archive files. They may be
++either explicit file names, or @samp{-l} options.
++
++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.
++
++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.
++
++@kindex -assert @var{keyword}
++@item -assert @var{keyword}
++This option is ignored for SunOS compatibility.
++
++@kindex -Bdynamic
++@kindex -dy
++@kindex -call_shared
++@item -Bdynamic
++@itemx -dy
++@itemx -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
++@option{-l} options which follow it.
++
++@kindex -Bgroup
++@item -Bgroup
++Set the @code{DF_1_GROUP} flag in the @code{DT_FLAGS_1} 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.
++@option{--no-undefined} is implied. This option is only meaningful on ELF
++platforms which support shared libraries.
++
++@kindex -Bstatic
++@kindex -dn
++@kindex -non_shared
++@kindex -static
++@item -Bstatic
++@itemx -dn
++@itemx -non_shared
++@itemx -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 @option{-l} options which follow it.
++
++@kindex -Bsymbolic
++@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 ELF
++platforms which support shared libraries.
++
++@kindex --check-sections
++@kindex --no-check-sections
++@item --check-sections
++@itemx --no-check-sections
++Asks the linker @emph{not} 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 @samp{--check-sections}.
++
++@cindex cross reference table
++@kindex --cref
++@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.
++
++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.
++
++@cindex common allocation
++@kindex --no-define-common
++@item --no-define-common
++This option inhibits the assignment of addresses to common symbols.
++The script command @code{INHIBIT_COMMON_ALLOCATION} has the same effect.
++@xref{Miscellaneous Commands}.
++
++The @samp{--no-define-common} option allows decoupling
++the decision to assign addresses to Common symbols from the choice
++of the output file type; otherwise a non-Relocatable output type
++forces assigning addresses to Common symbols.
++Using @samp{--no-define-common} allows Common symbols that are referenced
++from a shared library to be assigned addresses only in the main program.
++This eliminates the unused duplicate space in the shared library,
++and also prevents any possible confusion over resolving to the wrong
++duplicate when there are many dynamic modules with specialized search
++paths for runtime symbol resolution.
++
++@cindex symbols, from command line
++@kindex --defsym @var{symbol}=@var{exp}
++@item --defsym @var{symbol}=@var{expression}
++Create a global symbol in the output file, containing the absolute
++address given by @var{expression}. 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 @var{expression} in this
++context: you may give a hexadecimal constant or the name of an existing
++symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
++constants or symbols. If you need more elaborate expressions, consider
++using the linker command language from a script (@pxref{Assignments,,
++Assignment: Symbol Definitions}). @emph{Note:} there should be no white
++space between @var{symbol}, the equals sign (``@key{=}''), and
++@var{expression}.
++
++@cindex demangling, from command line
++@kindex --demangle[=@var{style}]
++@kindex --no-demangle
++@item --demangle[=@var{style}]
++@itemx --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 @samp{COLLECT_NO_DEMANGLE}
++is set. These options may be used to override the default.
++
++@cindex dynamic linker, from command line
++@kindex -I@var{file}
++@kindex --dynamic-linker @var{file}
++@item --dynamic-linker @var{file}
++Set the name of the dynamic linker. This is only meaningful when
++generating dynamically linked ELF executables. The default dynamic
++linker is normally correct; don't use this unless you know what you are
++doing.
++
++@cindex MIPS embedded PIC code
++@kindex --embedded-relocs
++@item --embedded-relocs
++This option is only meaningful when linking MIPS embedded PIC code,
++generated by the -membedded-pic option to the @sc{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.
++
++
++@kindex --fatal-warnings
++@item --fatal-warnings
++Treat all warnings as errors.
++
++@kindex --force-exe-suffix
++@item --force-exe-suffix
++Make sure that an output file has a .exe suffix.
++
++If a successfully built fully linked output file does not have a
++@code{.exe} or @code{.dll} suffix, this option forces the linker to copy
++the output file to one of the same name with a @code{.exe} 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 @code{.exe} suffix.
++
++@kindex --gc-sections
++@kindex --no-gc-sections
++@cindex garbage collection
++@item --no-gc-sections
++@itemx --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 @samp{-r}, nor should it be used with dynamic linking. The default
++behaviour (of not performing this garbage collection) can be restored by
++specifying @samp{--no-gc-sections} on the command line.
++
++@cindex help
++@cindex usage
++@kindex --help
++@item --help
++Print a summary of the command-line options on the standard output and exit.
++
++@kindex --target-help
++@item --target-help
++Print a summary of all target specific options on the standard output and exit.
++
++@kindex -Map
++@item -Map @var{mapfile}
++Print a link map to the file @var{mapfile}. See the description of the
++@samp{-M} option, above.
++
++@cindex memory usage
++@kindex --no-keep-memory
++@item --no-keep-memory
++@command{ld} normally optimizes for speed over memory usage by caching the
++symbol tables of input files in memory. This option tells @command{ld} to
++instead optimize for memory usage, by rereading the symbol tables as
++necessary. This may be required if @command{ld} runs out of memory space
++while linking a large executable.
++
++@kindex --no-undefined
++@kindex -z defs
++@item --no-undefined
++@itemx -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.
++
++@kindex --allow-shlib-undefined
++@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 HPPA shared libraries to have undefined symbols.
++
++@kindex --no-warn-mismatch
++@item --no-warn-mismatch
++Normally @command{ld} 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 @command{ld} 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.
++
++@kindex --no-whole-archive
++@item --no-whole-archive
++Turn off the effect of the @option{--whole-archive} option for subsequent
++archive files.
++
++@cindex output file after errors
++@kindex --noinhibit-exec
++@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; it exits without writing an output file
++when it issues any error whatsoever.
++
++@kindex -nostdlib
++@item -nostdlib
++Only search library directories explicitly specified on the
++command line. Library directories specified in linker scripts
++(including linker scripts specified on the command line) are ignored.
++
++@ifclear SingleFormat
++@kindex --oformat
++@item --oformat @var{output-format}
++@command{ld} may be configured to support more than one kind of object
++file. If your @command{ld} is configured this way, you can use the
++@samp{--oformat} option to specify the binary format for the output
++object file. Even when @command{ld} is configured to support alternative
++object formats, you don't usually need to specify this, as @command{ld}
++should be configured to produce as a default output format the most
++usual format on each machine. @var{output-format} is a text string, the
++name of a particular format supported by the BFD libraries. (You can
++list the available binary formats with @samp{objdump -i}.) The script
++command @code{OUTPUT_FORMAT} can also specify the output format, but
++this option overrides it. @xref{BFD}.
++@end ifclear
++
++@kindex -qmagic
++@item -qmagic
++This option is ignored for Linux compatibility.
++
++@kindex -Qy
++@item -Qy
++This option is ignored for SVR4 compatibility.
++
++@kindex --relax
++@cindex synthesizing linker
++@cindex relaxing addressing modes
++@item --relax
++An option with machine dependent effects.
++@ifset GENERIC
++This option is only supported on a few targets.
++@end ifset
++@ifset H8300
++@xref{H8/300,,@command{ld} and the H8/300}.
++@end ifset
++@ifset I960
++@xref{i960,, @command{ld} and the Intel 960 family}.
++@end ifset
++
++
++On some platforms, the @samp{--relax} 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.
++
++On some platforms these link time global optimizations may make symbolic
++debugging of the resulting executable impossible.
++@ifset GENERIC
++This is known to be
++the case for the Matsushita MN10200 and MN10300 family of processors.
++@end ifset
++
++@ifset GENERIC
++On platforms where this is not supported, @samp{--relax} is accepted,
++but ignored.
++@end ifset
++
++@cindex retaining specified symbols
++@cindex stripping all but some symbols
++@cindex symbols, retaining selectively
++@item --retain-symbols-file @var{filename}
++Retain @emph{only} the symbols listed in the file @var{filename},
++discarding all others. @var{filename} is simply a flat file, with one
++symbol name per line. This option is especially useful in environments
++@ifset GENERIC
++(such as VxWorks)
++@end ifset
++where a large global symbol table is accumulated gradually, to conserve
++run-time memory.
++
++@samp{--retain-symbols-file} does @emph{not} discard undefined symbols,
++or symbols needed for relocations.
++
++You may only specify @samp{--retain-symbols-file} once in the command
++line. It overrides @samp{-s} and @samp{-S}.
++
++@ifset GENERIC
++@item -rpath @var{dir}
++@cindex runtime library search path
++@kindex -rpath
++Add a directory to the runtime library search path. This is used when
++linking an ELF executable with shared objects. All @option{-rpath}
++arguments are concatenated and passed to the runtime linker, which uses
++them to locate shared objects at runtime. The @option{-rpath} option is
++also used when locating shared objects which are needed by shared
++objects explicitly included in the link; see the description of the
++@option{-rpath-link} option. If @option{-rpath} is not used when linking an
++ELF executable, the contents of the environment variable
++@code{LD_RUN_PATH} will be used if it is defined.
++
++The @option{-rpath} option may also be used on SunOS. By default, on
++SunOS, the linker will form a runtime search patch out of all the
++@option{-L} options it is given. If a @option{-rpath} option is used, the
++runtime search path will be formed exclusively using the @option{-rpath}
++options, ignoring the @option{-L} options. This can be useful when using
++gcc, which adds many @option{-L} options which may be on NFS mounted
++filesystems.
++
++For compatibility with other ELF linkers, if the @option{-R} option is
++followed by a directory name, rather than a file name, it is treated as
++the @option{-rpath} option.
++@end ifset
++
++@ifset GENERIC
++@cindex link-time runtime library search path
++@kindex -rpath-link
++@item -rpath-link @var{DIR}
++When using ELF or SunOS, one shared library may require another. This
++happens when an @code{ld -shared} link includes a shared library as one
++of the input files.
++
++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 @option{-rpath-link} option
++specifies the first set of directories to search. The
++@option{-rpath-link} option may specify a sequence of directory names
++either by specifying a list of names separated by colons, or by
++appearing multiple times.
++
++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.
++
++The linker uses the following search paths to locate required shared
++libraries.
++@enumerate
++@item
++Any directories specified by @option{-rpath-link} options.
++@item
++Any directories specified by @option{-rpath} options. The difference
++between @option{-rpath} and @option{-rpath-link} is that directories
++specified by @option{-rpath} options are included in the executable and
++used at runtime, whereas the @option{-rpath-link} option is only effective
++at link time. It is for the native linker only.
++@item
++On an ELF system, if the @option{-rpath} and @code{rpath-link} options
++were not used, search the contents of the environment variable
++@code{LD_RUN_PATH}. It is for the native linker only.
++@item
++On SunOS, if the @option{-rpath} option was not used, search any
++directories specified using @option{-L} options.
++@item
++For a native linker, the contents of the environment variable
++@code{LD_LIBRARY_PATH}.
++@item
++For a native ELF linker, the directories in @code{DT_RUNPATH} or
++@code{DT_RPATH} of a shared library are searched for shared
++libraries needed by it. The @code{DT_RPATH} entries are ignored if
++@code{DT_RUNPATH} entries exist.
++@item
++The default directories, normally @file{/lib} and @file{/usr/lib}.
++@item
++For a native linker on an ELF system, if the file @file{/etc/ld.so.conf}
++exists, the list of directories found in that file.
++@end enumerate
++
++If the required shared library is not found, the linker will issue a
++warning and continue with the link.
++@end ifset
++
++@kindex -shared
++@kindex -Bshareable
++@item -shared
++@itemx -Bshareable
++@cindex shared libraries
++Create a shared library. This is currently only supported on ELF, XCOFF
++and SunOS platforms. On SunOS, the linker will automatically create a
++shared library if the @option{-e} option is not used and there are
++undefined symbols in the link.
++
++@item --sort-common
++@kindex --sort-common
++This option tells @command{ld} 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 byte, then all the four byte, and then
++everything else. This is to prevent gaps between symbols due to
++alignment constraints.
++
++@kindex --split-by-file
++@item --split-by-file [@var{size}]
++Similar to @option{--split-by-reloc} but creates a new output section for
++each input file when @var{size} is reached. @var{size} defaults to a
++size of 1 if not given.
++
++@kindex --split-by-reloc
++@item --split-by-reloc [@var{count}]
++Tries to creates extra sections in the output file so that no single
++output section in the file contains more than @var{count} relocations.
++This is useful when generating huge relocatable files 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
++support arbitrary sections. The linker will not split up individual
++input sections for redistribution, so if a single input section contains
++more than @var{count} relocations one output section will contain that
++many relocations. @var{count} defaults to a value of 32768.
++
++@kindex --stats
++@item --stats
++Compute and display statistics about the operation of the linker, such
++as execution time and memory usage.
++
++@kindex --traditional-format
++@cindex traditional format
++@item --traditional-format
++For some targets, the output of @command{ld} is different in some ways from
++the output of some existing linker. This switch requests @command{ld} to
++use the traditional format instead.
++
++@cindex dbx
++For example, on SunOS, @command{ld} 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
++@code{dbx} program can not read the resulting program (@code{gdb} has no
++trouble). The @samp{--traditional-format} switch tells @command{ld} to not
++combine duplicate entries.
++
++@kindex --section-start @var{sectionname}=@var{org}
++@item --section-start @var{sectionname}=@var{org}
++Locate a section in the output file at the absolute
++address given by @var{org}. You may use this option as many
++times as necessary to locate multiple sections in the command
++line.
++@var{org} must be a single hexadecimal integer;
++for compatibility with other linkers, you may omit the leading
++@samp{0x} usually associated with hexadecimal values. @emph{Note:} there
++should be no white space between @var{sectionname}, the equals
++sign (``@key{=}''), and @var{org}.
++
++@kindex -Tbss @var{org}
++@kindex -Tdata @var{org}
++@kindex -Ttext @var{org}
++@cindex segment origins, cmd line
++@item -Tbss @var{org}
++@itemx -Tdata @var{org}
++@itemx -Ttext @var{org}
++Use @var{org} as the starting address for---respectively---the
++@code{bss}, @code{data}, or the @code{text} segment of the output file.
++@var{org} must be a single hexadecimal integer;
++for compatibility with other linkers, you may omit the leading
++@samp{0x} usually associated with hexadecimal values.
++
++@kindex --verbose
++@cindex verbose
++@item --dll-verbose
++@itemx --verbose
++Display the version number for @command{ld} and list the linker emulations
++supported. Display which input files can and cannot be opened. Display
++the linker script being used by the linker.
++
++@kindex --version-script=@var{version-scriptfile}
++@cindex version script, symbol versions
++@itemx --version-script=@var{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 ELF platforms which support shared libraries.
++@xref{VERSION}.
++
++@kindex --warn-common
++@cindex warnings, on combining symbols
++@cindex combining symbols, warnings on
++@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.
++Unfortunately, some C libraries use this practice, so you may get some
++warnings about symbols in the libraries as well as in your programs.
++
++There are three kinds of global symbols, illustrated here by C examples:
++
++@table @samp
++@item int i = 1;
++A definition, which goes in the initialized data section of the output
++file.
++
++@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.
++
++@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.
++@end table
++
++The @samp{--warn-common} 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.
++
++@enumerate
++@item
++Turning a common symbol into a reference, because there is already a
++definition for the symbol.
++@smallexample
++@var{file}(@var{section}): warning: common of `@var{symbol}'
++ overridden by definition
++@var{file}(@var{section}): warning: defined here
++@end smallexample
++
++@item
++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.
++@smallexample
++@var{file}(@var{section}): warning: definition of `@var{symbol}'
++ overriding common
++@var{file}(@var{section}): warning: common is here
++@end smallexample
++
++@item
++Merging a common symbol with a previous same-sized common symbol.
++@smallexample
++@var{file}(@var{section}): warning: multiple common
++ of `@var{symbol}'
++@var{file}(@var{section}): warning: previous common is here
++@end smallexample
++
++@item
++Merging a common symbol with a previous larger common symbol.
++@smallexample
++@var{file}(@var{section}): warning: common of `@var{symbol}'
++ overridden by larger common
++@var{file}(@var{section}): warning: larger common is here
++@end smallexample
++
++@item
++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.
++@smallexample
++@var{file}(@var{section}): warning: common of `@var{symbol}'
++ overriding smaller common
++@var{file}(@var{section}): warning: smaller common is here
++@end smallexample
++@end enumerate
++
++@kindex --warn-constructors
++@item --warn-constructors
++Warn if any global constructors are used. This is only useful for a few
++object file formats. For formats like COFF or ELF, the linker can not
++detect the use of global constructors.
++
++@kindex --warn-multiple-gp
++@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.
++
++@kindex --warn-once
++@cindex warnings, on undefined symbols
++@cindex undefined symbols, warnings on
++@item --warn-once
++Only warn once for each undefined symbol, rather than once per module
++which refers to it.
++
++@kindex --warn-section-align
++@cindex warnings, on section alignment
++@cindex section alignment, warnings on
++@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 @code{SECTIONS} command does not specify a start address for
++the section (@pxref{SECTIONS}).
++
++@kindex --whole-archive
++@cindex including an entire archive
++@item --whole-archive
++For each archive mentioned on the command line after the
++@option{--whole-archive} 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.
++
++Two notes when using this option from gcc: First, gcc doesn't know
++about this option, so you have to use @option{-Wl,-whole-archive}.
++Second, don't forget to use @option{-Wl,-no-whole-archive} 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.
++
++@kindex --wrap
++@item --wrap @var{symbol}
++Use a wrapper function for @var{symbol}. Any undefined reference to
++@var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any
++undefined reference to @code{__real_@var{symbol}} will be resolved to
++@var{symbol}.
++
++This can be used to provide a wrapper for a system function. The
++wrapper function should be called @code{__wrap_@var{symbol}}. If it
++wishes to call the system function, it should call
++@code{__real_@var{symbol}}.
++
++Here is a trivial example:
++
++@smallexample
++void *
++__wrap_malloc (int c)
++@{
++ printf ("malloc called with %ld\n", c);
++ return __real_malloc (c);
++@}
++@end smallexample
++
++If you link other code with this file using @option{--wrap malloc}, then
++all calls to @code{malloc} will call the function @code{__wrap_malloc}
++instead. The call to @code{__real_malloc} in @code{__wrap_malloc} will
++call the real @code{malloc} function.
++
++You may wish to provide a @code{__real_malloc} function as well, so that
++links without the @option{--wrap} option will succeed. If you do this,
++you should not put the definition of @code{__real_malloc} in the same
++file as @code{__wrap_malloc}; if you do, the assembler may resolve the
++call before the linker has a chance to wrap it to @code{malloc}.
++
++@kindex --enable-new-dtags
++@kindex --disable-new-dtags
++@item --enable-new-dtags
++@itemx --disable-new-dtags
++This linker can create the new dynamic tags in ELF. But the older ELF
++systems may not understand them. If you specify
++@option{--enable-new-dtags}, the dynamic tags will be created as needed.
++If you specify @option{--disable-new-dtags}, no new dynamic tags will be
++created. By default, the new dynamic tags are not created. Note that
++those options are only available for ELF systems.
++
++@end table
++
++@c man end
++
++@subsection Options specific to i386 PE targets
++
++@c man begin OPTIONS
++
++The i386 PE linker supports the @option{-shared} option, which causes
++the output to be a dynamically linked library (DLL) instead of a
++normal executable. You should name the output @code{*.dll} when you
++use this option. In addition, the linker fully supports the standard
++@code{*.def} 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).
++
++In addition to the options common to all targets, the i386 PE linker
++support additional command line options that are specific to the i386
++PE target. Options that take values may be separated from their
++values by either a space or an equals sign.
++
++@table @gcctabopt
++
++@kindex --add-stdcall-alias
++@item --add-stdcall-alias
++If given, symbols with a stdcall suffix (@@@var{nn}) will be exported
++as-is and also with the suffix stripped.
++
++@kindex --base-file
++@item --base-file @var{file}
++Use @var{file} as the name of a file in which to save the base
++addresses of all the relocations needed for generating DLLs with
++@file{dlltool}.
++
++@kindex --dll
++@item --dll
++Create a DLL instead of a regular executable. You may also use
++@option{-shared} or specify a @code{LIBRARY} in a given @code{.def}
++file.
++
++@kindex --enable-stdcall-fixup
++@kindex --disable-stdcall-fixup
++@item --enable-stdcall-fixup
++@itemx --disable-stdcall-fixup
++If the link finds a symbol that it cannot resolve, it will attempt to
++do "fuzzy linking" 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 @code{_foo} might be linked to the function
++@code{_foo@@12}, or the undefined symbol @code{_bar@@16} might be linked
++to the function @code{_bar}. 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 @option{--enable-stdcall-fixup}, this
++feature is fully enabled and warnings are not printed. If you specify
++@option{--disable-stdcall-fixup}, this feature is disabled and such
++mismatches are considered to be errors.
++
++@cindex DLLs, creating
++@kindex --export-all-symbols
++@item --export-all-symbols
++If given, all global symbols in the objects used to build a DLL will
++be exported by the DLL. Note that this is the default if there
++otherwise wouldn't be any exported symbols. When symbols are
++explicitly exported via DEF files or implicitly exported via function
++attributes, the default is to not export anything else unless this
++option is given. Note that the symbols @code{DllMain@@12},
++@code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and
++@code{impure_ptr} will not be automatically
++exported. Also, symbols imported from other DLLs will not be
++re-exported, nor will symbols specifying the DLL's internal layout
++such as those beginning with @code{_head_} or ending with
++@code{_iname}. In addition, no symbols from @code{libgcc},
++@code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported.
++Symbols whose names begin with @code{__rtti_} or @code{__builtin_} will
++not be exported, to help with C++ DLLs. Finally, there is an
++extensive list of cygwin-private symbols that are not exported
++(obviously, this applies on when building DLLs for cygwin targets).
++These cygwin-excludes are: @code{_cygwin_dll_entry@@12},
++@code{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12},
++@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
++@code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2},
++@code{cygwin_premain3}, and @code{environ}.
++
++@kindex --exclude-symbols
++@item --exclude-symbols @var{symbol},@var{symbol},...
++Specifies a list of symbols which should not be automatically
++exported. The symbol names may be delimited by commas or colons.
++
++@kindex --file-alignment
++@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.
++
++@cindex heap size
++@kindex --heap
++@item --heap @var{reserve}
++@itemx --heap @var{reserve},@var{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.
++
++@cindex image base
++@kindex --image-base
++@item --image-base @var{value}
++Use @var{value} 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.
++
++@kindex --kill-at
++@item --kill-at
++If given, the stdcall suffixes (@@@var{nn}) will be stripped from
++symbols before they are exported.
++
++@kindex --major-image-version
++@item --major-image-version @var{value}
++Sets the major number of the "image version". Defaults to 1.
++
++@kindex --major-os-version
++@item --major-os-version @var{value}
++Sets the major number of the "os version". Defaults to 4.
++
++@kindex --major-subsystem-version
++@item --major-subsystem-version @var{value}
++Sets the major number of the "subsystem version". Defaults to 4.
++
++@kindex --minor-image-version
++@item --minor-image-version @var{value}
++Sets the minor number of the "image version". Defaults to 0.
++
++@kindex --minor-os-version
++@item --minor-os-version @var{value}
++Sets the minor number of the "os version". Defaults to 0.
++
++@kindex --minor-subsystem-version
++@item --minor-subsystem-version @var{value}
++Sets the minor number of the "subsystem version". Defaults to 0.
++
++@cindex DEF files, creating
++@cindex DLLs, creating
++@kindex --output-def
++@item --output-def @var{file}
++The linker will create the file @var{file} which will contain a DEF
++file corresponding to the DLL the linker is generating. This DEF file
++(which should be called @code{*.def}) may be used to create an import
++library with @code{dlltool} or may be used as a reference to
++automatically or implicitly exported symbols.
++
++@cindex DLLs, creating
++@kindex --out-implib
++@item --out-implib @var{file}
++The linker will create the file @var{file} which will contain an
++import lib corresponding to the DLL the linker is generating. This
++import lib (which should be called @code{*.dll.a} or @code{*.a}
++may be used to link clients against the generated DLL; this behavior
++makes it possible to skip a separate @code{dlltool} import library
++creation step.
++
++@kindex --enable-auto-image-base
++@item --enable-auto-image-base
++Automatically choose the image base for DLLs, unless one is specified
++using the @code{--image-base} argument. By using a hash generated
++from the dllname to create unique image bases for each DLL, in-memory
++collisions and relocations which can delay program execution are
++avoided.
++
++@kindex --disable-auto-image-base
++@item --disable-auto-image-base
++Do not automatically generate a unique image base. If there is no
++user-specified image base (@code{--image-base}) then use the platform
++default.
++
++@cindex DLLs, linking to
++@kindex --dll-search-prefix
++@item --dll-search-prefix @var{string}
++When linking dynamically to a dll without an import library, i
++search for @code{<string><basename>.dll} in preference to
++@code{lib<basename>.dll}. This behavior allows easy distinction
++between DLLs built for the various "subplatforms": native, cygwin,
++uwin, pw, etc. For instance, cygwin DLLs typically use
++@code{--dll-search-prefix=cyg}.
++
++@kindex --enable-auto-import
++@item --enable-auto-import
++Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for
++DATA imports from DLLs, and create the necessary thunking symbols when
++building the DLLs with those DATA exports. This generally will 'just
++work' -- but sometimes you may see this message:
++
++"variable '<var>' can't be auto-imported. Please read the
++documentation for ld's @code{--enable-auto-import} for details."
++
++This message occurs when some (sub)expression accesses an address
++ultimately given by the sum of two constants (Win32 import tables only
++allow one). Instances where this may occur include accesses to member
++fields of struct variables imported from a DLL, as well as using a
++constant index into an array variable imported from a DLL. Any
++multiword variable (arrays, structs, long long, etc) may trigger
++this error condition. However, regardless of the exact data type
++of the offending exported variable, ld will always detect it, issue
++the warning, and exit.
++
++There are several ways to address this difficulty, regardless of the
++data type of the exported variable:
++
++One solution is to force one of the 'constants' to be a variable --
++that is, unknown and un-optimizable at compile time. For arrays,
++there are two possibilities: a) make the indexee (the array's address)
++a variable, or b) make the 'constant' index a variable. Thus:
++
++@example
++extern type extern_array[];
++extern_array[1] -->
++ @{ volatile type *t=extern_array; t[1] @}
++@end example
++
++or
++
++@example
++extern type extern_array[];
++extern_array[1] -->
++ @{ volatile int t=1; extern_array[t] @}
++@end example
++
++For structs (and most other multiword data types) the only option
++is to make the struct itself (or the long long, or the ...) variable:
++
++@example
++extern struct s extern_struct;
++extern_struct.field -->
++ @{ volatile struct s *t=&extern_struct; t->field @}
++@end example
++
++or
++
++@example
++extern long long extern_ll;
++extern_ll -->
++ @{ volatile long long * local_ll=&extern_ll; *local_ll @}
++@end example
++
++A second method of dealing with this difficulty is to abandon
++'auto-import' for the offending symbol and mark it with
++@code{__declspec(dllimport)}. However, in practice that
++requires using compile-time #defines to indicate whether you are
++building a DLL, building client code that will link to the DLL, or
++merely building/linking to a static library. In making the choice
++between the various methods of resolving the 'direct address with
++constant offset' problem, you should consider typical real-world usage:
++
++Original:
++@example
++--foo.h
++extern int arr[];
++--foo.c
++#include "foo.h"
++void main(int argc, char **argv)@{
++ printf("%d\n",arr[1]);
++@}
++@end example
++
++Solution 1:
++@example
++--foo.h
++extern int arr[];
++--foo.c
++#include "foo.h"
++void main(int argc, char **argv)@{
++ /* This workaround is for win32 and cygwin; do not "optimize" */
++ volatile int *parr = arr;
++ printf("%d\n",parr[1]);
++@}
++@end example
++
++Solution 2:
++@example
++--foo.h
++/* Note: auto-export is assumed (no __declspec(dllexport)) */
++#if (defined(_WIN32) || defined(__CYGWIN__)) && \
++ !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
++#define FOO_IMPORT __declspec(dllimport)
++#else
++#define FOO_IMPORT
++#endif
++extern FOO_IMPORT int arr[];
++--foo.c
++#include "foo.h"
++void main(int argc, char **argv)@{
++ printf("%d\n",arr[1]);
++@}
++@end example
++
++A third way to avoid this problem is to re-code your
++library to use a functional interface rather than a data interface
++for the offending variables (e.g. set_foo() and get_foo() accessor
++functions).
++
++@kindex --disable-auto-import
++@item --disable-auto-import
++Do not attempt to do sophisticalted linking of @code{_symbol} to
++@code{__imp__symbol} for DATA imports from DLLs.
++
++@kindex --enable-extra-pe-debug
++@item --enable-extra-pe-debug
++Show additional debug info related to auto-import symbol thunking.
++
++@kindex --section-alignment
++@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.
++
++@cindex stack size
++@kindex --stack
++@item --stack @var{reserve}
++@itemx --stack @var{reserve},@var{commit}
++Specify the amount of memory to reserve (and optionally commit) to be
++used as stack for this program. The default is 2Mb reserved, 4K
++committed.
++
++@kindex --subsystem
++@item --subsystem @var{which}
++@itemx --subsystem @var{which}:@var{major}
++@itemx --subsystem @var{which}:@var{major}.@var{minor}
++Specifies the subsystem under which your program will execute. The
++legal values for @var{which} are @code{native}, @code{windows},
++@code{console}, and @code{posix}. You may optionally set the
++subsystem version also.
++
++@end table
++
++@c man end
++
++@ifset UsesEnvVars
++@node Environment
++@section Environment Variables
++
++@c man begin ENVIRONMENT
++
++You can change the behavior of @command{ld} with the environment variables
++@code{GNUTARGET}, @code{LDEMULATION}, and @code{COLLECT_NO_DEMANGLE}.
++
++@kindex GNUTARGET
++@cindex default input format
++@code{GNUTARGET} determines the input-file object format if you don't
++use @samp{-b} (or its synonym @samp{--format}). Its value should be one
++of the BFD names for an input format (@pxref{BFD}). If there is no
++@code{GNUTARGET} in the environment, @command{ld} uses the natural format
++of the target. If @code{GNUTARGET} is set to @code{default} 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.
++
++@kindex LDEMULATION
++@cindex default emulation
++@cindex emulation, default
++@code{LDEMULATION} determines the default emulation if you don't use the
++@samp{-m} option. The emulation can affect various aspects of linker
++behaviour, particularly the default linker script. You can list the
++available emulations with the @samp{--verbose} or @samp{-V} options. If
++the @samp{-m} option is not used, and the @code{LDEMULATION} environment
++variable is not defined, the default emulation depends upon how the
++linker was configured.
++
++@kindex COLLECT_NO_DEMANGLE
++@cindex demangling, default
++Normally, the linker will default to demangling symbols. However, if
++@code{COLLECT_NO_DEMANGLE} is set in the environment, then it will
++default to not demangling symbols. This environment variable is used in
++a similar fashion by the @code{gcc} linker wrapper program. The default
++may be overridden by the @samp{--demangle} and @samp{--no-demangle}
++options.
++
++@c man end
++@end ifset
++
++@node Scripts
++@chapter Linker Scripts
++
++@cindex scripts
++@cindex linker scripts
++@cindex command files
++Every link is controlled by a @dfn{linker script}. This script is
++written in the linker command language.
++
++The main purpose of the linker script is to describe how the sections in
++the input files should be mapped into the output file, and to control
++the memory layout of the output file. Most linker scripts do nothing
++more than this. However, when necessary, the linker script can also
++direct the linker to perform many other operations, using the commands
++described below.
++
++The linker always uses a linker script. If you do not supply one
++yourself, the linker will use a default script that is compiled into the
++linker executable. You can use the @samp{--verbose} command line option
++to display the default linker script. Certain command line options,
++such as @samp{-r} or @samp{-N}, will affect the default linker script.
++
++You may supply your own linker script by using the @samp{-T} command
++line option. When you do this, your linker script will replace the
++default linker script.
++
++You may also use linker scripts implicitly by naming them as input files
++to the linker, as though they were files to be linked. @xref{Implicit
++Linker Scripts}.
++
++@menu
++* Basic Script Concepts:: Basic Linker Script Concepts
++* Script Format:: Linker Script Format
++* Simple Example:: Simple Linker Script Example
++* Simple Commands:: Simple Linker Script Commands
++* Assignments:: Assigning Values to Symbols
++* SECTIONS:: SECTIONS Command
++* MEMORY:: MEMORY Command
++* PHDRS:: PHDRS Command
++* VERSION:: VERSION Command
++* Expressions:: Expressions in Linker Scripts
++* Implicit Linker Scripts:: Implicit Linker Scripts
++@end menu
++
++@node Basic Script Concepts
++@section Basic Linker Script Concepts
++@cindex linker script concepts
++We need to define some basic concepts and vocabulary in order to
++describe the linker script language.
++
++The linker combines input files into a single output file. The output
++file and each input file are in a special data format known as an
++@dfn{object file format}. Each file is called an @dfn{object file}.
++The output file is often called an @dfn{executable}, but for our
++purposes we will also call it an object file. Each object file has,
++among other things, a list of @dfn{sections}. We sometimes refer to a
++section in an input file as an @dfn{input section}; similarly, a section
++in the output file is an @dfn{output section}.
++
++Each section in an object file has a name and a size. Most sections
++also have an associated block of data, known as the @dfn{section
++contents}. A section may be marked as @dfn{loadable}, which mean that
++the contents should be loaded into memory when the output file is run.
++A section with no contents may be @dfn{allocatable}, which means that an
++area in memory should be set aside, but nothing in particular should be
++loaded there (in some cases this memory must be zeroed out). A section
++which is neither loadable nor allocatable typically contains some sort
++of debugging information.
++
++Every loadable or allocatable output section has two addresses. The
++first is the @dfn{VMA}, or virtual memory address. This is the address
++the section will have when the output file is run. The second is the
++@dfn{LMA}, or load memory address. This is the address at which the
++section will be loaded. In most cases the two addresses will be the
++same. An example of when they might be different is when a data section
++is loaded into ROM, and then copied into RAM when the program starts up
++(this technique is often used to initialize global variables in a ROM
++based system). In this case the ROM address would be the LMA, and the
++RAM address would be the VMA.
++
++You can see the sections in an object file by using the @code{objdump}
++program with the @samp{-h} option.
++
++Every object file also has a list of @dfn{symbols}, known as the
++@dfn{symbol table}. A symbol may be defined or undefined. Each symbol
++has a name, and each defined symbol has an address, among other
++information. If you compile a C or C++ program into an object file, you
++will get a defined symbol for every defined function and global or
++static variable. Every undefined function or global variable which is
++referenced in the input file will become an undefined symbol.
++
++You can see the symbols in an object file by using the @code{nm}
++program, or by using the @code{objdump} program with the @samp{-t}
++option.
++
++@node Script Format
++@section Linker Script Format
++@cindex linker script format
++Linker scripts are text files.
++
++You write a linker script as a series of commands. Each command is
++either a keyword, possibly followed by arguments, or an assignment to a
++symbol. You may separate commands using semicolons. Whitespace is
++generally ignored.
++
++Strings such as file or format names can normally be entered directly.
++If the file name contains a character such as a comma which would
++otherwise serve to separate file names, you may put the file name in
++double quotes. There is no way to use a double quote character in a
++file name.
++
++You may include comments in linker scripts just as in C, delimited by
++@samp{/*} and @samp{*/}. As in C, comments are syntactically equivalent
++to whitespace.
++
++@node Simple Example
++@section Simple Linker Script Example
++@cindex linker script example
++@cindex example of linker script
++Many linker scripts are fairly simple.
++
++The simplest possible linker script has just one command:
++@samp{SECTIONS}. You use the @samp{SECTIONS} command to describe the
++memory layout of the output file.
++
++The @samp{SECTIONS} command is a powerful command. Here we will
++describe a simple use of it. Let's assume your program consists only of
++code, initialized data, and uninitialized data. These will be in the
++@samp{.text}, @samp{.data}, and @samp{.bss} sections, respectively.
++Let's assume further that these are the only sections which appear in
++your input files.
++
++For this example, let's say that the code should be loaded at address
++0x10000, and that the data should start at address 0x8000000. Here is a
++linker script which will do that:
++@smallexample
++SECTIONS
++@{
++ . = 0x10000;
++ .text : @{ *(.text) @}
++ . = 0x8000000;
++ .data : @{ *(.data) @}
++ .bss : @{ *(.bss) @}
++@}
++@end smallexample
++
++You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS},
++followed by a series of symbol assignments and output section
++descriptions enclosed in curly braces.
++
++The first line inside the @samp{SECTIONS} command of the above example
++sets the value of the special symbol @samp{.}, which is the location
++counter. If you do not specify the address of an output section in some
++other way (other ways are described later), the address is set from the
++current value of the location counter. The location counter is then
++incremented by the size of the output section. At the start of the
++@samp{SECTIONS} command, the location counter has the value @samp{0}.
++
++The second line defines an output section, @samp{.text}. The colon is
++required syntax which may be ignored for now. Within the curly braces
++after the output section name, you list the names of the input sections
++which should be placed into this output section. The @samp{*} is a
++wildcard which matches any file name. The expression @samp{*(.text)}
++means all @samp{.text} input sections in all input files.
++
++Since the location counter is @samp{0x10000} when the output section
++@samp{.text} is defined, the linker will set the address of the
++@samp{.text} section in the output file to be @samp{0x10000}.
++
++The remaining lines define the @samp{.data} and @samp{.bss} sections in
++the output file. The linker will place the @samp{.data} output section
++at address @samp{0x8000000}. After the linker places the @samp{.data}
++output section, the value of the location counter will be
++@samp{0x8000000} plus the size of the @samp{.data} output section. The
++effect is that the linker will place the @samp{.bss} output section
++immediately after the @samp{.data} output section in memory
++
++The linker will ensure that each output section has the required
++alignment, by increasing the location counter if necessary. In this
++example, the specified addresses for the @samp{.text} and @samp{.data}
++sections will probably satisfy any alignment constraints, but the linker
++may have to create a small gap between the @samp{.data} and @samp{.bss}
++sections.
++
++That's it! That's a simple and complete linker script.
++
++@node Simple Commands
++@section Simple Linker Script Commands
++@cindex linker script simple commands
++In this section we describe the simple linker script commands.
++
++@menu
++* Entry Point:: Setting the entry point
++* File Commands:: Commands dealing with files
++@ifclear SingleFormat
++* Format Commands:: Commands dealing with object file formats
++@end ifclear
++
++* Miscellaneous Commands:: Other linker script commands
++@end menu
++
++@node Entry Point
++@subsection Setting the entry point
++@kindex ENTRY(@var{symbol})
++@cindex start of execution
++@cindex first instruction
++@cindex entry point
++The first instruction to execute in a program is called the @dfn{entry
++point}. You can use the @code{ENTRY} linker script command to set the
++entry point. The argument is a symbol name:
++@smallexample
++ENTRY(@var{symbol})
++@end smallexample
++
++There are several ways to set the entry point. The linker will set the
++entry point by trying each of the following methods in order, and
++stopping when one of them succeeds:
++@itemize @bullet
++@item
++the @samp{-e} @var{entry} command-line option;
++@item
++the @code{ENTRY(@var{symbol})} command in a linker script;
++@item
++the value of the symbol @code{start}, if defined;
++@item
++the address of the first byte of the @samp{.text} section, if present;
++@item
++The address @code{0}.
++@end itemize
++
++@node File Commands
++@subsection Commands dealing with files
++@cindex linker script file commands
++Several linker script commands deal with files.
++
++@table @code
++@item INCLUDE @var{filename}
++@kindex INCLUDE @var{filename}
++@cindex including a linker script
++Include the linker script @var{filename} at this point. The file will
++be searched for in the current directory, and in any directory specified
++with the @option{-L} option. You can nest calls to @code{INCLUDE} up to
++10 levels deep.
++
++@item INPUT(@var{file}, @var{file}, @dots{})
++@itemx INPUT(@var{file} @var{file} @dots{})
++@kindex INPUT(@var{files})
++@cindex input files in linker scripts
++@cindex input object files in linker scripts
++@cindex linker script input object files
++The @code{INPUT} command directs the linker to include the named files
++in the link, as though they were named on the command line.
++
++For example, if you always want to include @file{subr.o} any time you do
++a link, but you can't be bothered to put it on every link command line,
++then you can put @samp{INPUT (subr.o)} in your linker script.
++
++In fact, if you like, you can list all of your input files in the linker
++script, and then invoke the linker with nothing but a @samp{-T} option.
++
++The linker will first try to open the file in the current directory. If
++it is not found, the linker will search through the archive library
++search path. See the description of @samp{-L} in @ref{Options,,Command
++Line Options}.
++
++If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
++name to @code{lib@var{file}.a}, as with the command line argument
++@samp{-l}.
++
++When you use the @code{INPUT} command in an implicit linker script, the
++files will be included in the link at the point at which the linker
++script file is included. This can affect archive searching.
++
++@item GROUP(@var{file}, @var{file}, @dots{})
++@itemx GROUP(@var{file} @var{file} @dots{})
++@kindex GROUP(@var{files})
++@cindex grouping input files
++The @code{GROUP} command is like @code{INPUT}, except that the named
++files should all be archives, and they are searched repeatedly until no
++new undefined references are created. See the description of @samp{-(}
++in @ref{Options,,Command Line Options}.
++
++@item OUTPUT(@var{filename})
++@kindex OUTPUT(@var{filename})
++@cindex output file name in linker scripot
++The @code{OUTPUT} command names the output file. Using
++@code{OUTPUT(@var{filename})} in the linker script is exactly like using
++@samp{-o @var{filename}} on the command line (@pxref{Options,,Command
++Line Options}). If both are used, the command line option takes
++precedence.
++
++You can use the @code{OUTPUT} command to define a default name for the
++output file other than the usual default of @file{a.out}.
++
++@item SEARCH_DIR(@var{path})
++@kindex SEARCH_DIR(@var{path})
++@cindex library search path in linker script
++@cindex archive search path in linker script
++@cindex search path in linker script
++The @code{SEARCH_DIR} command adds @var{path} to the list of paths where
++@command{ld} looks for archive libraries. Using
++@code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}}
++on the command line (@pxref{Options,,Command Line Options}). If both
++are used, then the linker will search both paths. Paths specified using
++the command line option are searched first.
++
++@item STARTUP(@var{filename})
++@kindex STARTUP(@var{filename})
++@cindex first input file
++The @code{STARTUP} command is just like the @code{INPUT} command, except
++that @var{filename} will become the first input file to be linked, as
++though it were specified first on the command line. This may be useful
++when using a system in which the entry point is always the start of the
++first file.
++@end table
++
++@ifclear SingleFormat
++@node Format Commands
++@subsection Commands dealing with object file formats
++A couple of linker script commands deal with object file formats.
++
++@table @code
++@item OUTPUT_FORMAT(@var{bfdname})
++@itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little})
++@kindex OUTPUT_FORMAT(@var{bfdname})
++@cindex output file format in linker script
++The @code{OUTPUT_FORMAT} command names the BFD format to use for the
++output file (@pxref{BFD}). Using @code{OUTPUT_FORMAT(@var{bfdname})} is
++exactly like using @samp{-oformat @var{bfdname}} on the command line
++(@pxref{Options,,Command Line Options}). If both are used, the command
++line option takes precedence.
++
++You can use @code{OUTPUT_FORMAT} with three arguments to use different
++formats based on the @samp{-EB} and @samp{-EL} command line options.
++This permits the linker script to set the output format based on the
++desired endianness.
++
++If neither @samp{-EB} nor @samp{-EL} are used, then the output format
++will be the first argument, @var{default}. If @samp{-EB} is used, the
++output format will be the second argument, @var{big}. If @samp{-EL} is
++used, the output format will be the third argument, @var{little}.
++
++For example, the default linker script for the MIPS ELF target uses this
++command:
++@smallexample
++OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
++@end smallexample
++This says that the default format for the output file is
++@samp{elf32-bigmips}, but if the user uses the @samp{-EL} command line
++option, the output file will be created in the @samp{elf32-littlemips}
++format.
++
++@item TARGET(@var{bfdname})
++@kindex TARGET(@var{bfdname})
++@cindex input file format in linker script
++The @code{TARGET} command names the BFD format to use when reading input
++files. It affects subsequent @code{INPUT} and @code{GROUP} commands.
++This command is like using @samp{-b @var{bfdname}} on the command line
++(@pxref{Options,,Command Line Options}). If the @code{TARGET} command
++is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET}
++command is also used to set the format for the output file. @xref{BFD}.
++@end table
++@end ifclear
++
++@node Miscellaneous Commands
++@subsection Other linker script commands
++There are a few other linker scripts commands.
++
++@table @code
++@item ASSERT(@var{exp}, @var{message})
++@kindex ASSERT
++@cindex assertion in linker script
++Ensure that @var{exp} is non-zero. If it is zero, then exit the linker
++with an error code, and print @var{message}.
++
++@item EXTERN(@var{symbol} @var{symbol} @dots{})
++@kindex EXTERN
++@cindex undefined symbol in linker script
++Force @var{symbol} to be entered in the output file as an undefined
++symbol. Doing this may, for example, trigger linking of additional
++modules from standard libraries. You may list several @var{symbol}s for
++each @code{EXTERN}, and you may use @code{EXTERN} multiple times. This
++command has the same effect as the @samp{-u} command-line option.
++
++@item FORCE_COMMON_ALLOCATION
++@kindex FORCE_COMMON_ALLOCATION
++@cindex common allocation in linker script
++This command has the same effect as the @samp{-d} command-line option:
++to make @command{ld} assign space to common symbols even if a relocatable
++output file is specified (@samp{-r}).
++
++@item INHIBIT_COMMON_ALLOCATION
++@kindex INHIBIT_COMMON_ALLOCATION
++@cindex common allocation in linker script
++This command has the same effect as the @samp{--no-define-common}
++command-line option: to make @code{ld} omit the assignment of addresses
++to common symbols even for a non-relocatable output file.
++
++@item NOCROSSREFS(@var{section} @var{section} @dots{})
++@kindex NOCROSSREFS(@var{sections})
++@cindex cross references
++This command may be used to tell @command{ld} to issue an error about any
++references among certain output sections.
++
++In certain types of programs, particularly on embedded systems when
++using overlays, when one section is loaded into memory, another section
++will not be. Any direct references between the two sections would be
++errors. For example, it would be an error if code in one section called
++a function defined in the other section.
++
++The @code{NOCROSSREFS} command takes a list of output section names. If
++@command{ld} detects any cross references between the sections, it reports
++an error and returns a non-zero exit status. Note that the
++@code{NOCROSSREFS} command uses output section names, not input section
++names.
++
++@ifclear SingleFormat
++@item OUTPUT_ARCH(@var{bfdarch})
++@kindex OUTPUT_ARCH(@var{bfdarch})
++@cindex machine architecture
++@cindex architecture
++Specify a particular output machine architecture. The argument is one
++of the names used by the BFD library (@pxref{BFD}). You can see the
++architecture of an object file by using the @code{objdump} program with
++the @samp{-f} option.
++@end ifclear
++@end table
++
++@node Assignments
++@section Assigning Values to Symbols
++@cindex assignment in scripts
++@cindex symbol definition, scripts
++@cindex variables, defining
++You may assign a value to a symbol in a linker script. This will define
++the symbol as a global symbol.
++
++@menu
++* Simple Assignments:: Simple Assignments
++* PROVIDE:: PROVIDE
++@end menu
++
++@node Simple Assignments
++@subsection Simple Assignments
++
++You may assign to a symbol using any of the C assignment operators:
++
++@table @code
++@item @var{symbol} = @var{expression} ;
++@itemx @var{symbol} += @var{expression} ;
++@itemx @var{symbol} -= @var{expression} ;
++@itemx @var{symbol} *= @var{expression} ;
++@itemx @var{symbol} /= @var{expression} ;
++@itemx @var{symbol} <<= @var{expression} ;
++@itemx @var{symbol} >>= @var{expression} ;
++@itemx @var{symbol} &= @var{expression} ;
++@itemx @var{symbol} |= @var{expression} ;
++@end table
++
++The first case will define @var{symbol} to the value of
++@var{expression}. In the other cases, @var{symbol} must already be
++defined, and the value will be adjusted accordingly.
++
++The special symbol name @samp{.} indicates the location counter. You
++may only use this within a @code{SECTIONS} command.
++
++The semicolon after @var{expression} is required.
++
++Expressions are defined below; see @ref{Expressions}.
++
++You may write symbol assignments as commands in their own right, or as
++statements within a @code{SECTIONS} command, or as part of an output
++section description in a @code{SECTIONS} command.
++
++The section of the symbol will be set from the section of the
++expression; for more information, see @ref{Expression Section}.
++
++Here is an example showing the three different places that symbol
++assignments may be used:
++
++@smallexample
++floating_point = 0;
++SECTIONS
++@{
++ .text :
++ @{
++ *(.text)
++ _etext = .;
++ @}
++ _bdata = (. + 3) & ~ 3;
++ .data : @{ *(.data) @}
++@}
++@end smallexample
++@noindent
++In this example, the symbol @samp{floating_point} will be defined as
++zero. The symbol @samp{_etext} will be defined as the address following
++the last @samp{.text} input section. The symbol @samp{_bdata} will be
++defined as the address following the @samp{.text} output section aligned
++upward to a 4 byte boundary.
++
++@node PROVIDE
++@subsection PROVIDE
++@cindex PROVIDE
++In some cases, it is desirable for a linker script to define a symbol
++only if it is referenced and is not defined by any object included in
++the link. For example, traditional linkers defined the symbol
++@samp{etext}. However, ANSI C requires that the user be able to use
++@samp{etext} as a function name without encountering an error. The
++@code{PROVIDE} keyword may be used to define a symbol, such as
++@samp{etext}, only if it is referenced but not defined. The syntax is
++@code{PROVIDE(@var{symbol} = @var{expression})}.
++
++Here is an example of using @code{PROVIDE} to define @samp{etext}:
++@smallexample
++SECTIONS
++@{
++ .text :
++ @{
++ *(.text)
++ _etext = .;
++ PROVIDE(etext = .);
++ @}
++@}
++@end smallexample
++
++In this example, if the program defines @samp{_etext} (with a leading
++underscore), the linker will give a multiple definition error. If, on
++the other hand, the program defines @samp{etext} (with no leading
++underscore), the linker will silently use the definition in the program.
++If the program references @samp{etext} but does not define it, the
++linker will use the definition in the linker script.
++
++@node SECTIONS
++@section SECTIONS command
++@kindex SECTIONS
++The @code{SECTIONS} command tells the linker how to map input sections
++into output sections, and how to place the output sections in memory.
++
++The format of the @code{SECTIONS} command is:
++@smallexample
++SECTIONS
++@{
++ @var{sections-command}
++ @var{sections-command}
++ @dots{}
++@}
++@end smallexample
++
++Each @var{sections-command} may of be one of the following:
++
++@itemize @bullet
++@item
++an @code{ENTRY} command (@pxref{Entry Point,,Entry command})
++@item
++a symbol assignment (@pxref{Assignments})
++@item
++an output section description
++@item
++an overlay description
++@end itemize
++
++The @code{ENTRY} command and symbol assignments are permitted inside the
++@code{SECTIONS} command for convenience in using the location counter in
++those commands. This can also make the linker script easier to
++understand because you can use those commands at meaningful points in
++the layout of the output file.
++
++Output section descriptions and overlay descriptions are described
++below.
++
++If you do not use a @code{SECTIONS} command in your linker script, the
++linker will place each input section into an identically named output
++section in the order that the sections are first encountered in the
++input files. If all input sections are present in the first file, for
++example, the order of sections in the output file will match the order
++in the first input file. The first section will be at address zero.
++
++@menu
++* Output Section Description:: Output section description
++* Output Section Name:: Output section name
++* Output Section Address:: Output section address
++* Input Section:: Input section description
++* Output Section Data:: Output section data
++* Output Section Keywords:: Output section keywords
++* Output Section Discarding:: Output section discarding
++* Output Section Attributes:: Output section attributes
++* Overlay Description:: Overlay description
++@end menu
++
++@node Output Section Description
++@subsection Output section description
++The full description of an output section looks like this:
++@smallexample
++@group
++@var{section} [@var{address}] [(@var{type})] : [AT(@var{lma})]
++ @{
++ @var{output-section-command}
++ @var{output-section-command}
++ @dots{}
++ @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
++@end group
++@end smallexample
++
++Most output sections do not use most of the optional section attributes.
++
++The whitespace around @var{section} is required, so that the section
++name is unambiguous. The colon and the curly braces are also required.
++The line breaks and other white space are optional.
++
++Each @var{output-section-command} may be one of the following:
++
++@itemize @bullet
++@item
++a symbol assignment (@pxref{Assignments})
++@item
++an input section description (@pxref{Input Section})
++@item
++data values to include directly (@pxref{Output Section Data})
++@item
++a special output section keyword (@pxref{Output Section Keywords})
++@end itemize
++
++@node Output Section Name
++@subsection Output section name
++@cindex name, section
++@cindex section name
++The name of the output section is @var{section}. @var{section} must
++meet the constraints of your output format. In formats which only
++support a limited number of sections, such as @code{a.out}, the name
++must be one of the names supported by the format (@code{a.out}, for
++example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). If the
++output format supports any number of sections, but with numbers and not
++names (as is the case for Oasys), the name should be supplied as a
++quoted numeric string. A section name may consist of any sequence of
++characters, but a name which contains any unusual characters such as
++commas must be quoted.
++
++The output section name @samp{/DISCARD/} is special; @ref{Output Section
++Discarding}.
++
++@node Output Section Address
++@subsection Output section address
++@cindex address, section
++@cindex section address
++The @var{address} is an expression for the VMA (the virtual memory
++address) of the output section. If you do not provide @var{address},
++the linker will set it based on @var{region} if present, or otherwise
++based on the current value of the location counter.
++
++If you provide @var{address}, the address of the output section will be
++set to precisely that. If you provide neither @var{address} nor
++@var{region}, then the address of the output section will be set to the
++current value of the location counter aligned to the alignment
++requirements of the output section. The alignment requirement of the
++output section is the strictest alignment of any input section contained
++within the output section.
++
++For example,
++@smallexample
++.text . : @{ *(.text) @}
++@end smallexample
++@noindent
++and
++@smallexample
++.text : @{ *(.text) @}
++@end smallexample
++@noindent
++are subtly different. The first will set the address of the
++@samp{.text} output section to the current value of the location
++counter. The second will set it to the current value of the location
++counter aligned to the strictest alignment of a @samp{.text} input
++section.
++
++The @var{address} may be an arbitrary expression; @ref{Expressions}.
++For example, if you want to align the section on a 0x10 byte boundary,
++so that the lowest four bits of the section address are zero, you could
++do something like this:
++@smallexample
++.text ALIGN(0x10) : @{ *(.text) @}
++@end smallexample
++@noindent
++This works because @code{ALIGN} returns the current location counter
++aligned upward to the specified value.
++
++Specifying @var{address} for a section will change the value of the
++location counter.
++
++@node Input Section
++@subsection Input section description
++@cindex input sections
++@cindex mapping input sections to output sections
++The most common output section command is an input section description.
++
++The input section description is the most basic linker script operation.
++You use output sections to tell the linker how to lay out your program
++in memory. You use input section descriptions to tell the linker how to
++map the input files into your memory layout.
++
++@menu
++* Input Section Basics:: Input section basics
++* Input Section Wildcards:: Input section wildcard patterns
++* Input Section Common:: Input section for common symbols
++* Input Section Keep:: Input section and garbage collection
++* Input Section Example:: Input section example
++@end menu
++
++@node Input Section Basics
++@subsubsection Input section basics
++@cindex input section basics
++An input section description consists of a file name optionally followed
++by a list of section names in parentheses.
++
++The file name and the section name may be wildcard patterns, which we
++describe further below (@pxref{Input Section Wildcards}).
++
++The most common input section description is to include all input
++sections with a particular name in the output section. For example, to
++include all input @samp{.text} sections, you would write:
++@smallexample
++*(.text)
++@end smallexample
++@noindent
++Here the @samp{*} is a wildcard which matches any file name. To exclude a list
++of files from matching the file name wildcard, EXCLUDE_FILE may be used to
++match all files except the ones specified in the EXCLUDE_FILE list. For
++example:
++@smallexample
++(*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors))
++@end smallexample
++will cause all .ctors sections from all files except @file{crtend.o} and
++@file{otherfile.o} to be included.
++
++There are two ways to include more than one section:
++@smallexample
++*(.text .rdata)
++*(.text) *(.rdata)
++@end smallexample
++@noindent
++The difference between these is the order in which the @samp{.text} and
++@samp{.rdata} input sections will appear in the output section. In the
++first example, they will be intermingled, appearing in the same order as
++they are found in the linker input. In the second example, all
++@samp{.text} input sections will appear first, followed by all
++@samp{.rdata} input sections.
++
++You can specify a file name to include sections from a particular file.
++You would do this if one or more of your files contain special data that
++needs to be at a particular location in memory. For example:
++@smallexample
++data.o(.data)
++@end smallexample
++
++If you use a file name without a list of sections, then all sections in
++the input file will be included in the output section. This is not
++commonly done, but it may by useful on occasion. For example:
++@smallexample
++data.o
++@end smallexample
++
++When you use a file name which does not contain any wild card
++characters, the linker will first see if you also specified the file
++name on the linker command line or in an @code{INPUT} command. If you
++did not, the linker will attempt to open the file as an input file, as
++though it appeared on the command line. Note that this differs from an
++@code{INPUT} command, because the linker will not search for the file in
++the archive search path.
++
++@node Input Section Wildcards
++@subsubsection Input section wildcard patterns
++@cindex input section wildcards
++@cindex wildcard file name patterns
++@cindex file name wildcard patterns
++@cindex section name wildcard patterns
++In an input section description, either the file name or the section
++name or both may be wildcard patterns.
++
++The file name of @samp{*} seen in many examples is a simple wildcard
++pattern for the file name.
++
++The wildcard patterns are like those used by the Unix shell.
++
++@table @samp
++@item *
++matches any number of characters
++@item ?
++matches any single character
++@item [@var{chars}]
++matches a single instance of any of the @var{chars}; the @samp{-}
++character may be used to specify a range of characters, as in
++@samp{[a-z]} to match any lower case letter
++@item \
++quotes the following character
++@end table
++
++When a file name is matched with a wildcard, the wildcard characters
++will not match a @samp{/} character (used to separate directory names on
++Unix). A pattern consisting of a single @samp{*} character is an
++exception; it will always match any file name, whether it contains a
++@samp{/} or not. In a section name, the wildcard characters will match
++a @samp{/} character.
++
++File name wildcard patterns only match files which are explicitly
++specified on the command line or in an @code{INPUT} command. The linker
++does not search directories to expand wildcards.
++
++If a file name matches more than one wildcard pattern, or if a file name
++appears explicitly and is also matched by a wildcard pattern, the linker
++will use the first match in the linker script. For example, this
++sequence of input section descriptions is probably in error, because the
++@file{data.o} rule will not be used:
++@smallexample
++.data : @{ *(.data) @}
++.data1 : @{ data.o(.data) @}
++@end smallexample
++
++@cindex SORT
++Normally, the linker will place files and sections matched by wildcards
++in the order in which they are seen during the link. You can change
++this by using the @code{SORT} keyword, which appears before a wildcard
++pattern in parentheses (e.g., @code{SORT(.text*)}). When the
++@code{SORT} keyword is used, the linker will sort the files or sections
++into ascending order by name before placing them in the output file.
++
++If you ever get confused about where input sections are going, use the
++@samp{-M} linker option to generate a map file. The map file shows
++precisely how input sections are mapped to output sections.
++
++This example shows how wildcard patterns might be used to partition
++files. This linker script directs the linker to place all @samp{.text}
++sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}.
++The linker will place the @samp{.data} section from all files beginning
++with an upper case character in @samp{.DATA}; for all other files, the
++linker will place the @samp{.data} section in @samp{.data}.
++@smallexample
++@group
++SECTIONS @{
++ .text : @{ *(.text) @}
++ .DATA : @{ [A-Z]*(.data) @}
++ .data : @{ *(.data) @}
++ .bss : @{ *(.bss) @}
++@}
++@end group
++@end smallexample
++
++@node Input Section Common
++@subsubsection Input section for common symbols
++@cindex common symbol placement
++@cindex uninitialized data placement
++A special notation is needed for common symbols, because in many object
++file formats common symbols do not have a particular input section. The
++linker treats common symbols as though they are in an input section
++named @samp{COMMON}.
++
++You may use file names with the @samp{COMMON} section just as with any
++other input sections. You can use this to place common symbols from a
++particular input file in one section while common symbols from other
++input files are placed in another section.
++
++In most cases, common symbols in input files will be placed in the
++@samp{.bss} section in the output file. For example:
++@smallexample
++.bss @{ *(.bss) *(COMMON) @}
++@end smallexample
++
++@cindex scommon section
++@cindex small common symbols
++Some object file formats have more than one type of common symbol. For
++example, the MIPS ELF object file format distinguishes standard common
++symbols and small common symbols. In this case, the linker will use a
++different special section name for other types of common symbols. In
++the case of MIPS ELF, the linker uses @samp{COMMON} for standard common
++symbols and @samp{.scommon} for small common symbols. This permits you
++to map the different types of common symbols into memory at different
++locations.
++
++@cindex [COMMON]
++You will sometimes see @samp{[COMMON]} in old linker scripts. This
++notation is now considered obsolete. It is equivalent to
++@samp{*(COMMON)}.
++
++@node Input Section Keep
++@subsubsection Input section and garbage collection
++@cindex KEEP
++@cindex garbage collection
++When link-time garbage collection is in use (@samp{--gc-sections}),
++it is often useful to mark sections that should not be eliminated.
++This is accomplished by surrounding an input section's wildcard entry
++with @code{KEEP()}, as in @code{KEEP(*(.init))} or
++@code{KEEP(SORT(*)(.ctors))}.
++
++@node Input Section Example
++@subsubsection Input section example
++The following example is a complete linker script. It tells the linker
++to read all of the sections from file @file{all.o} and place them at the
++start of output section @samp{outputa} which starts at location
++@samp{0x10000}. All of section @samp{.input1} from file @file{foo.o}
++follows immediately, in the same output section. All of section
++@samp{.input2} from @file{foo.o} goes into output section
++@samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}.
++All of the remaining @samp{.input1} and @samp{.input2} sections from any
++files are written to output section @samp{outputc}.
++
++@smallexample
++@group
++SECTIONS @{
++ outputa 0x10000 :
++ @{
++ all.o
++ foo.o (.input1)
++ @}
++ outputb :
++ @{
++ foo.o (.input2)
++ foo1.o (.input1)
++ @}
++ outputc :
++ @{
++ *(.input1)
++ *(.input2)
++ @}
++@}
++@end group
++@end smallexample
++
++@node Output Section Data
++@subsection Output section data
++@cindex data
++@cindex section data
++@cindex output section data
++@kindex BYTE(@var{expression})
++@kindex SHORT(@var{expression})
++@kindex LONG(@var{expression})
++@kindex QUAD(@var{expression})
++@kindex SQUAD(@var{expression})
++You can include explicit bytes of data in an output section by using
++@code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as
++an output section command. Each keyword is followed by an expression in
++parentheses providing the value to store (@pxref{Expressions}). The
++value of the expression is stored at the current value of the location
++counter.
++
++The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands
++store one, two, four, and eight bytes (respectively). After storing the
++bytes, the location counter is incremented by the number of bytes
++stored.
++
++For example, this will store the byte 1 followed by the four byte value
++of the symbol @samp{addr}:
++@smallexample
++BYTE(1)
++LONG(addr)
++@end smallexample
++
++When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the
++same; they both store an 8 byte, or 64 bit, value. When both host and
++target are 32 bits, an expression is computed as 32 bits. In this case
++@code{QUAD} stores a 32 bit value zero extended to 64 bits, and
++@code{SQUAD} stores a 32 bit value sign extended to 64 bits.
++
++If the object file format of the output file has an explicit endianness,
++which is the normal case, the value will be stored in that endianness.
++When the object file format does not have an explicit endianness, as is
++true of, for example, S-records, the value will be stored in the
++endianness of the first input object file.
++
++Note - these commands only work inside a section description and not
++between them, so the following will produce an error from the linker:
++@smallexample
++SECTIONS @{@ .text : @{@ *(.text) @}@ LONG(1) .data : @{@ *(.data) @}@ @}@
++@end smallexample
++whereas this will work:
++@smallexample
++SECTIONS @{@ .text : @{@ *(.text) ; LONG(1) @}@ .data : @{@ *(.data) @}@ @}@
++@end smallexample
++
++@kindex FILL(@var{expression})
++@cindex holes, filling
++@cindex unspecified memory
++You may use the @code{FILL} command to set the fill pattern for the
++current section. It is followed by an expression in parentheses. Any
++otherwise unspecified regions of memory within the section (for example,
++gaps left due to the required alignment of input sections) are filled
++with the value of the expression, repeated as
++necessary. A @code{FILL} statement covers memory locations after the
++point at which it occurs in the section definition; by including more
++than one @code{FILL} statement, you can have different fill patterns in
++different parts of an output section.
++
++This example shows how to fill unspecified regions of memory with the
++value @samp{0x90}:
++@smallexample
++FILL(0x90909090)
++@end smallexample
++
++The @code{FILL} command is similar to the @samp{=@var{fillexp}} output
++section attribute, but it only affects the
++part of the section following the @code{FILL} command, rather than the
++entire section. If both are used, the @code{FILL} command takes
++precedence. @xref{Output Section Fill}, for details on the fill
++expression.
++
++@node Output Section Keywords
++@subsection Output section keywords
++There are a couple of keywords which can appear as output section
++commands.
++
++@table @code
++@kindex CREATE_OBJECT_SYMBOLS
++@cindex input filename symbols
++@cindex filename symbols
++@item CREATE_OBJECT_SYMBOLS
++The command tells the linker to create a symbol for each input file.
++The name of each symbol will be the name of the corresponding input
++file. The section of each symbol will be the output section in which
++the @code{CREATE_OBJECT_SYMBOLS} command appears.
++
++This is conventional for the a.out object file format. It is not
++normally used for any other object file format.
++
++@kindex CONSTRUCTORS
++@cindex C++ constructors, arranging in link
++@cindex constructors, arranging in link
++@item CONSTRUCTORS
++When linking using the a.out object file format, the linker uses an
++unusual set construct to support C++ global constructors and
++destructors. When linking object file formats which do not support
++arbitrary sections, such as ECOFF and XCOFF, the linker will
++automatically recognize C++ global constructors and destructors by name.
++For these object file formats, the @code{CONSTRUCTORS} command tells the
++linker to place constructor information in the output section where the
++@code{CONSTRUCTORS} command appears. The @code{CONSTRUCTORS} command is
++ignored for other object file formats.
++
++The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
++constructors, and the symbol @w{@code{__DTOR_LIST}} marks the end. The
++first word in the list is the number of entries, followed by the address
++of each constructor or destructor, followed by a zero word. The
++compiler must arrange to actually run the code. For these object file
++formats @sc{gnu} C++ normally calls constructors from a subroutine
++@code{__main}; a call to @code{__main} is automatically inserted into
++the startup code for @code{main}. @sc{gnu} C++ normally runs
++destructors either by using @code{atexit}, or directly from the function
++@code{exit}.
++
++For object file formats such as @code{COFF} or @code{ELF} which support
++arbitrary section names, @sc{gnu} C++ will normally arrange to put the
++addresses of global constructors and destructors into the @code{.ctors}
++and @code{.dtors} sections. Placing the following sequence into your
++linker script will build the sort of table which the @sc{gnu} C++
++runtime code expects to see.
++
++@smallexample
++ __CTOR_LIST__ = .;
++ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
++ *(.ctors)
++ LONG(0)
++ __CTOR_END__ = .;
++ __DTOR_LIST__ = .;
++ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
++ *(.dtors)
++ LONG(0)
++ __DTOR_END__ = .;
++@end smallexample
++
++If you are using the @sc{gnu} C++ support for initialization priority,
++which provides some control over the order in which global constructors
++are run, you must sort the constructors at link time to ensure that they
++are executed in the correct order. When using the @code{CONSTRUCTORS}
++command, use @samp{SORT(CONSTRUCTORS)} instead. When using the
++@code{.ctors} and @code{.dtors} sections, use @samp{*(SORT(.ctors))} and
++@samp{*(SORT(.dtors))} instead of just @samp{*(.ctors)} and
++@samp{*(.dtors)}.
++
++Normally the compiler and linker will handle these issues automatically,
++and you will not need to concern yourself with them. However, you may
++need to consider this if you are using C++ and writing your own linker
++scripts.
++
++@end table
++
++@node Output Section Discarding
++@subsection Output section discarding
++@cindex discarding sections
++@cindex sections, discarding
++@cindex removing sections
++The linker will not create output section which do not have any
++contents. This is for convenience when referring to input sections that
++may or may not be present in any of the input files. For example:
++@smallexample
++.foo @{ *(.foo) @}
++@end smallexample
++@noindent
++will only create a @samp{.foo} section in the output file if there is a
++@samp{.foo} section in at least one input file.
++
++If you use anything other than an input section description as an output
++section command, such as a symbol assignment, then the output section
++will always be created, even if there are no matching input sections.
++
++@cindex /DISCARD/
++The special output section name @samp{/DISCARD/} may be used to discard
++input sections. Any input sections which are assigned to an output
++section named @samp{/DISCARD/} are not included in the output file.
++
++@node Output Section Attributes
++@subsection Output section attributes
++@cindex output section attributes
++We showed above that the full description of an output section looked
++like this:
++@smallexample
++@group
++@var{section} [@var{address}] [(@var{type})] : [AT(@var{lma})]
++ @{
++ @var{output-section-command}
++ @var{output-section-command}
++ @dots{}
++ @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
++@end group
++@end smallexample
++We've already described @var{section}, @var{address}, and
++@var{output-section-command}. In this section we will describe the
++remaining section attributes.
++
++@menu
++* Output Section Type:: Output section type
++* Output Section LMA:: Output section LMA
++* Output Section Region:: Output section region
++* Output Section Phdr:: Output section phdr
++* Output Section Fill:: Output section fill
++@end menu
++
++@node Output Section Type
++@subsubsection Output section type
++Each output section may have a type. The type is a keyword in
++parentheses. The following types are defined:
++
++@table @code
++@item NOLOAD
++The section should be marked as not loadable, so that it will not be
++loaded into memory when the program is run.
++@item DSECT
++@itemx COPY
++@itemx INFO
++@itemx OVERLAY
++These type names are supported for backward compatibility, and are
++rarely used. They all have the same effect: the section should be
++marked as not allocatable, so that no memory is allocated for the
++section when the program is run.
++@end table
++
++@kindex NOLOAD
++@cindex prevent unnecessary loading
++@cindex loading, preventing
++The linker normally sets the attributes of an output section based on
++the input sections which map into it. You can override this by using
++the section type. For example, in the script sample below, the
++@samp{ROM} section is addressed at memory location @samp{0} and does not
++need to be loaded when the program is run. The contents of the
++@samp{ROM} section will appear in the linker output file as usual.
++@smallexample
++@group
++SECTIONS @{
++ ROM 0 (NOLOAD) : @{ @dots{} @}
++ @dots{}
++@}
++@end group
++@end smallexample
++
++@node Output Section LMA
++@subsubsection Output section LMA
++@kindex AT>@var{lma_region}
++@kindex AT(@var{lma})
++@cindex load address
++@cindex section load address
++Every section has a virtual address (VMA) and a load address (LMA); see
++@ref{Basic Script Concepts}. The address expression which may appear in
++an output section description sets the VMA (@pxref{Output Section
++Address}).
++
++The linker will normally set the LMA equal to the VMA. You can change
++that by using the @code{AT} keyword. The expression @var{lma} that
++follows the @code{AT} keyword specifies the load address of the
++section. Alternatively, with @samp{AT>@var{lma_region}} expression,
++you may specify a memory region for the section's load address. @xref{MEMORY}.
++
++@cindex ROM initialized data
++@cindex initialized data in ROM
++This feature is designed to make it easy to build a ROM image. For
++example, the following linker script creates three output sections: one
++called @samp{.text}, which starts at @code{0x1000}, one called
++@samp{.mdata}, which is loaded at the end of the @samp{.text} section
++even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold
++uninitialized data at address @code{0x3000}. The symbol @code{_data} is
++defined with the value @code{0x2000}, which shows that the location
++counter holds the VMA value, not the LMA value.
++
++@smallexample
++@group
++SECTIONS
++ @{
++ .text 0x1000 : @{ *(.text) _etext = . ; @}
++ .mdata 0x2000 :
++ AT ( ADDR (.text) + SIZEOF (.text) )
++ @{ _data = . ; *(.data); _edata = . ; @}
++ .bss 0x3000 :
++ @{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@}
++@}
++@end group
++@end smallexample
++
++The run-time initialization code for use with a program generated with
++this linker script would include something like the following, to copy
++the initialized data from the ROM image to its runtime address. Notice
++how this code takes advantage of the symbols defined by the linker
++script.
++
++@smallexample
++@group
++extern char _etext, _data, _edata, _bstart, _bend;
++char *src = &_etext;
++char *dst = &_data;
++
++/* ROM has data at end of text; copy it. */
++while (dst < &_edata) @{
++ *dst++ = *src++;
++@}
++
++/* Zero bss */
++for (dst = &_bstart; dst< &_bend; dst++)
++ *dst = 0;
++@end group
++@end smallexample
++
++@node Output Section Region
++@subsubsection Output section region
++@kindex >@var{region}
++@cindex section, assigning to memory region
++@cindex memory regions and sections
++You can assign a section to a previously defined region of memory by
++using @samp{>@var{region}}. @xref{MEMORY}.
++
++Here is a simple example:
++@smallexample
++@group
++MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @}
++SECTIONS @{ ROM : @{ *(.text) @} >rom @}
++@end group
++@end smallexample
++
++@node Output Section Phdr
++@subsubsection Output section phdr
++@kindex :@var{phdr}
++@cindex section, assigning to program header
++@cindex program headers and sections
++You can assign a section to a previously defined program segment by
++using @samp{:@var{phdr}}. @xref{PHDRS}. If a section is assigned to
++one or more segments, then all subsequent allocated sections will be
++assigned to those segments as well, unless they use an explicitly
++@code{:@var{phdr}} modifier. You can use @code{:NONE} to tell the
++linker to not put the section in any segment at all.
++
++Here is a simple example:
++@smallexample
++@group
++PHDRS @{ text PT_LOAD ; @}
++SECTIONS @{ .text : @{ *(.text) @} :text @}
++@end group
++@end smallexample
++
++@node Output Section Fill
++@subsubsection Output section fill
++@kindex =@var{fillexp}
++@cindex section fill pattern
++@cindex fill pattern, entire section
++You can set the fill pattern for an entire section by using
++@samp{=@var{fillexp}}. @var{fillexp} is an expression
++(@pxref{Expressions}). Any otherwise unspecified regions of memory
++within the output section (for example, gaps left due to the required
++alignment of input sections) will be filled with the value, repeated as
++necessary. If the fill expression is a simple hex number, ie. a string
++of hex digit starting with @samp{0x} and without a trailing @samp{k} or @samp{M}, then
++an arbitrarily long sequence of hex digits can be used to specify the
++fill pattern; Leading zeros become part of the pattern too. For all
++other cases, including extra parentheses or a unary @code{+}, the fill
++pattern is the four least significant bytes of the value of the
++expression. In all cases, the number is big-endian.
++
++You can also change the fill value with a @code{FILL} command in the
++output section commands; (@pxref{Output Section Data}).
++
++Here is a simple example:
++@smallexample
++@group
++SECTIONS @{ .text : @{ *(.text) @} =0x90909090 @}
++@end group
++@end smallexample
++
++@node Overlay Description
++@subsection Overlay description
++@kindex OVERLAY
++@cindex overlays
++An overlay description provides an easy way to describe sections which
++are to be loaded as part of a single memory image but are to be run at
++the same memory address. At run time, some sort of overlay manager will
++copy the overlaid sections in and out of the runtime memory address as
++required, perhaps by simply manipulating addressing bits. This approach
++can be useful, for example, when a certain region of memory is faster
++than another.
++
++Overlays are described using the @code{OVERLAY} command. The
++@code{OVERLAY} command is used within a @code{SECTIONS} command, like an
++output section description. The full syntax of the @code{OVERLAY}
++command is as follows:
++@smallexample
++@group
++OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )]
++ @{
++ @var{secname1}
++ @{
++ @var{output-section-command}
++ @var{output-section-command}
++ @dots{}
++ @} [:@var{phdr}@dots{}] [=@var{fill}]
++ @var{secname2}
++ @{
++ @var{output-section-command}
++ @var{output-section-command}
++ @dots{}
++ @} [:@var{phdr}@dots{}] [=@var{fill}]
++ @dots{}
++ @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}]
++@end group
++@end smallexample
++
++Everything is optional except @code{OVERLAY} (a keyword), and each
++section must have a name (@var{secname1} and @var{secname2} above). The
++section definitions within the @code{OVERLAY} construct are identical to
++those within the general @code{SECTIONS} contruct (@pxref{SECTIONS}),
++except that no addresses and no memory regions may be defined for
++sections within an @code{OVERLAY}.
++
++The sections are all defined with the same starting address. The load
++addresses of the sections are arranged such that they are consecutive in
++memory starting at the load address used for the @code{OVERLAY} as a
++whole (as with normal section definitions, the load address is optional,
++and defaults to the start address; the start address is also optional,
++and defaults to the current value of the location counter).
++
++If the @code{NOCROSSREFS} keyword is used, and there any references
++among the sections, the linker will report an error. Since the sections
++all run at the same address, it normally does not make sense for one
++section to refer directly to another. @xref{Miscellaneous Commands,
++NOCROSSREFS}.
++
++For each section within the @code{OVERLAY}, the linker automatically
++defines two symbols. The symbol @code{__load_start_@var{secname}} is
++defined as the starting load address of the section. The symbol
++@code{__load_stop_@var{secname}} is defined as the final load address of
++the section. Any characters within @var{secname} which are not legal
++within C identifiers are removed. C (or assembler) code may use these
++symbols to move the overlaid sections around as necessary.
++
++At the end of the overlay, the value of the location counter is set to
++the start address of the overlay plus the size of the largest section.
++
++Here is an example. Remember that this would appear inside a
++@code{SECTIONS} construct.
++@smallexample
++@group
++ OVERLAY 0x1000 : AT (0x4000)
++ @{
++ .text0 @{ o1/*.o(.text) @}
++ .text1 @{ o2/*.o(.text) @}
++ @}
++@end group
++@end smallexample
++@noindent
++This will define both @samp{.text0} and @samp{.text1} to start at
++address 0x1000. @samp{.text0} will be loaded at address 0x4000, and
++@samp{.text1} will be loaded immediately after @samp{.text0}. The
++following symbols will be defined: @code{__load_start_text0},
++@code{__load_stop_text0}, @code{__load_start_text1},
++@code{__load_stop_text1}.
++
++C code to copy overlay @code{.text1} into the overlay area might look
++like the following.
++
++@smallexample
++@group
++ extern char __load_start_text1, __load_stop_text1;
++ memcpy ((char *) 0x1000, &__load_start_text1,
++ &__load_stop_text1 - &__load_start_text1);
++@end group
++@end smallexample
++
++Note that the @code{OVERLAY} command is just syntactic sugar, since
++everything it does can be done using the more basic commands. The above
++example could have been written identically as follows.
++
++@smallexample
++@group
++ .text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
++ __load_start_text0 = LOADADDR (.text0);
++ __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
++ .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
++ __load_start_text1 = LOADADDR (.text1);
++ __load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1);
++ . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
++@end group
++@end smallexample
++
++@node MEMORY
++@section MEMORY command
++@kindex MEMORY
++@cindex memory regions
++@cindex regions of memory
++@cindex allocating memory
++@cindex discontinuous memory
++The linker's default configuration permits allocation of all available
++memory. You can override this by using the @code{MEMORY} command.
++
++The @code{MEMORY} command describes the location and size of blocks of
++memory in the target. You can use it to describe which memory regions
++may be used by the linker, and which memory regions it must avoid. You
++can then assign sections to particular memory regions. The linker will
++set section addresses based on the memory regions, and will warn about
++regions that become too full. The linker will not shuffle sections
++around to fit into the available regions.
++
++A linker script may contain at most one use of the @code{MEMORY}
++command. However, you can define as many blocks of memory within it as
++you wish. The syntax is:
++@smallexample
++@group
++MEMORY
++ @{
++ @var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len}
++ @dots{}
++ @}
++@end group
++@end smallexample
++
++The @var{name} is a name used in the linker script to refer to the
++region. The region name has no meaning outside of the linker script.
++Region names are stored in a separate name space, and will not conflict
++with symbol names, file names, or section names. Each memory region
++must have a distinct name.
++
++@cindex memory region attributes
++The @var{attr} string is an optional list of attributes that specify
++whether to use a particular memory region for an input section which is
++not explicitly mapped in the linker script. As described in
++@ref{SECTIONS}, if you do not specify an output section for some input
++section, the linker will create an output section with the same name as
++the input section. If you define region attributes, the linker will use
++them to select the memory region for the output section that it creates.
++
++The @var{attr} string must consist only of the following characters:
++@table @samp
++@item R
++Read-only section
++@item W
++Read/write section
++@item X
++Executable section
++@item A
++Allocatable section
++@item I
++Initialized section
++@item L
++Same as @samp{I}
++@item !
++Invert the sense of any of the preceding attributes
++@end table
++
++If a unmapped section matches any of the listed attributes other than
++@samp{!}, it will be placed in the memory region. The @samp{!}
++attribute reverses this test, so that an unmapped section will be placed
++in the memory region only if it does not match any of the listed
++attributes.
++
++@kindex ORIGIN =
++@kindex o =
++@kindex org =
++The @var{origin} is an expression for the start address of the memory
++region. The expression must evaluate to a constant before memory
++allocation is performed, which means that you may not use any section
++relative symbols. The keyword @code{ORIGIN} may be abbreviated to
++@code{org} or @code{o} (but not, for example, @code{ORG}).
++
++@kindex LENGTH =
++@kindex len =
++@kindex l =
++The @var{len} is an expression for the size in bytes of the memory
++region. As with the @var{origin} expression, the expression must
++evaluate to a constant before memory allocation is performed. The
++keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
++
++In the following example, we specify that there are two memory regions
++available for allocation: one starting at @samp{0} for 256 kilobytes,
++and the other starting at @samp{0x40000000} for four megabytes. The
++linker will place into the @samp{rom} memory region every section which
++is not explicitly mapped into a memory region, and is either read-only
++or executable. The linker will place other sections which are not
++explicitly mapped into a memory region into the @samp{ram} memory
++region.
++
++@smallexample
++@group
++MEMORY
++ @{
++ rom (rx) : ORIGIN = 0, LENGTH = 256K
++ ram (!rx) : org = 0x40000000, l = 4M
++ @}
++@end group
++@end smallexample
++
++Once you define a memory region, you can direct the linker to place
++specific output sections into that memory region by using the
++@samp{>@var{region}} output section attribute. For example, if you have
++a memory region named @samp{mem}, you would use @samp{>mem} in the
++output section definition. @xref{Output Section Region}. If no address
++was specified for the output section, the linker will set the address to
++the next available address within the memory region. If the combined
++output sections directed to a memory region are too large for the
++region, the linker will issue an error message.
++
++@node PHDRS
++@section PHDRS Command
++@kindex PHDRS
++@cindex program headers
++@cindex ELF program headers
++@cindex program segments
++@cindex segments, ELF
++The ELF object file format uses @dfn{program headers}, also knows as
++@dfn{segments}. The program headers describe how the program should be
++loaded into memory. You can print them out by using the @code{objdump}
++program with the @samp{-p} option.
++
++When you run an ELF program on a native ELF system, the system loader
++reads the program headers in order to figure out how to load the
++program. This will only work if the program headers are set correctly.
++This manual does not describe the details of how the system loader
++interprets program headers; for more information, see the ELF ABI.
++
++The linker will create reasonable program headers by default. However,
++in some cases, you may need to specify the program headers more
++precisely. You may use the @code{PHDRS} command for this purpose. When
++the linker sees the @code{PHDRS} command in the linker script, it will
++not create any program headers other than the ones specified.
++
++The linker only pays attention to the @code{PHDRS} command when
++generating an ELF output file. In other cases, the linker will simply
++ignore @code{PHDRS}.
++
++This is the syntax of the @code{PHDRS} command. The words @code{PHDRS},
++@code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords.
++
++@smallexample
++@group
++PHDRS
++@{
++ @var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ]
++ [ FLAGS ( @var{flags} ) ] ;
++@}
++@end group
++@end smallexample
++
++The @var{name} is used only for reference in the @code{SECTIONS} command
++of the linker script. It is not put into the output file. Program
++header names are stored in a separate name space, and will not conflict
++with symbol names, file names, or section names. Each program header
++must have a distinct name.
++
++Certain program header types describe segments of memory which the
++system loader will load from the file. In the linker script, you
++specify the contents of these segments by placing allocatable output
++sections in the segments. You use the @samp{:@var{phdr}} output section
++attribute to place a section in a particular segment. @xref{Output
++Section Phdr}.
++
++It is normal to put certain sections in more than one segment. This
++merely implies that one segment of memory contains another. You may
++repeat @samp{:@var{phdr}}, using it once for each segment which should
++contain the section.
++
++If you place a section in one or more segments using @samp{:@var{phdr}},
++then the linker will place all subsequent allocatable sections which do
++not specify @samp{:@var{phdr}} in the same segments. This is for
++convenience, since generally a whole set of contiguous sections will be
++placed in a single segment. You can use @code{:NONE} to override the
++default segment and tell the linker to not put the section in any
++segment at all.
++
++@kindex FILEHDR
++@kindex PHDRS
++You may use the @code{FILEHDR} and @code{PHDRS} keywords appear after
++the program header type to further describe the contents of the segment.
++The @code{FILEHDR} keyword means that the segment should include the ELF
++file header. The @code{PHDRS} keyword means that the segment should
++include the ELF program headers themselves.
++
++The @var{type} may be one of the following. The numbers indicate the
++value of the keyword.
++
++@table @asis
++@item @code{PT_NULL} (0)
++Indicates an unused program header.
++
++@item @code{PT_LOAD} (1)
++Indicates that this program header describes a segment to be loaded from
++the file.
++
++@item @code{PT_DYNAMIC} (2)
++Indicates a segment where dynamic linking information can be found.
++
++@item @code{PT_INTERP} (3)
++Indicates a segment where the name of the program interpreter may be
++found.
++
++@item @code{PT_NOTE} (4)
++Indicates a segment holding note information.
++
++@item @code{PT_SHLIB} (5)
++A reserved program header type, defined but not specified by the ELF
++ABI.
++
++@item @code{PT_PHDR} (6)
++Indicates a segment where the program headers may be found.
++
++@item @var{expression}
++An expression giving the numeric type of the program header. This may
++be used for types not defined above.
++@end table
++
++You can specify that a segment should be loaded at a particular address
++in memory by using an @code{AT} expression. This is identical to the
++@code{AT} command used as an output section attribute (@pxref{Output
++Section LMA}). The @code{AT} command for a program header overrides the
++output section attribute.
++
++The linker will normally set the segment flags based on the sections
++which comprise the segment. You may use the @code{FLAGS} keyword to
++explicitly specify the segment flags. The value of @var{flags} must be
++an integer. It is used to set the @code{p_flags} field of the program
++header.
++
++Here is an example of @code{PHDRS}. This shows a typical set of program
++headers used on a native ELF system.
++
++@example
++@group
++PHDRS
++@{
++ headers PT_PHDR PHDRS ;
++ interp PT_INTERP ;
++ text PT_LOAD FILEHDR PHDRS ;
++ data PT_LOAD ;
++ dynamic PT_DYNAMIC ;
++@}
++
++SECTIONS
++@{
++ . = SIZEOF_HEADERS;
++ .interp : @{ *(.interp) @} :text :interp
++ .text : @{ *(.text) @} :text
++ .rodata : @{ *(.rodata) @} /* defaults to :text */
++ @dots{}
++ . = . + 0x1000; /* move to a new page in memory */
++ .data : @{ *(.data) @} :data
++ .dynamic : @{ *(.dynamic) @} :data :dynamic
++ @dots{}
++@}
++@end group
++@end example
++
++@node VERSION
++@section VERSION Command
++@kindex VERSION @{script text@}
++@cindex symbol versions
++@cindex version script
++@cindex versions of symbols
++The linker supports symbol versions when using ELF. Symbol versions are
++only useful when using shared libraries. The dynamic linker can use
++symbol versions to select a specific version of a function when it runs
++a program that may have been linked against an earlier version of the
++shared library.
++
++You can include a version script directly in the main linker script, or
++you can supply the version script as an implicit linker script. You can
++also use the @samp{--version-script} linker option.
++
++The syntax of the @code{VERSION} command is simply
++@smallexample
++VERSION @{ version-script-commands @}
++@end smallexample
++
++The format of the version script commands is identical to that used by
++Sun's linker in Solaris 2.5. The version script defines a tree of
++version nodes. You specify the node names and interdependencies in the
++version script. You can specify which symbols are bound to which
++version nodes, and you can reduce a specified set of symbols to local
++scope so that they are not globally visible outside of the shared
++library.
++
++The easiest way to demonstrate the version script language is with a few
++examples.
++
++@smallexample
++VERS_1.1 @{
++ global:
++ foo1;
++ local:
++ old*;
++ original*;
++ new*;
++@};
++
++VERS_1.2 @{
++ foo2;
++@} VERS_1.1;
++
++VERS_2.0 @{
++ bar1; bar2;
++@} VERS_1.2;
++@end smallexample
++
++This example version script defines three version nodes. The first
++version node defined is @samp{VERS_1.1}; it has no other dependencies.
++The script binds the symbol @samp{foo1} to @samp{VERS_1.1}. It reduces
++a number of symbols to local scope so that they are not visible outside
++of the shared library; this is done using wildcard patterns, so that any
++symbol whose name begins with @samp{old}, @samp{original}, or @samp{new}
++is matched. The wildcard patterns available are the same as those used
++in the shell when matching filenames (also known as ``globbing'').
++
++Next, the version script defines node @samp{VERS_1.2}. This node
++depends upon @samp{VERS_1.1}. The script binds the symbol @samp{foo2}
++to the version node @samp{VERS_1.2}.
++
++Finally, the version script defines node @samp{VERS_2.0}. This node
++depends upon @samp{VERS_1.2}. The scripts binds the symbols @samp{bar1}
++and @samp{bar2} are bound to the version node @samp{VERS_2.0}.
++
++When the linker finds a symbol defined in a library which is not
++specifically bound to a version node, it will effectively bind it to an
++unspecified base version of the library. You can bind all otherwise
++unspecified symbols to a given version node by using @samp{global: *}
++somewhere in the version script.
++
++The names of the version nodes have no specific meaning other than what
++they might suggest to the person reading them. The @samp{2.0} version
++could just as well have appeared in between @samp{1.1} and @samp{1.2}.
++However, this would be a confusing way to write a version script.
++
++Node name can be omited, provided it is the only version node
++in the version script. Such version script doesn't assign any versions to
++symbols, only selects which symbols will be globally visible out and which
++won't.
++
++@smallexample
++@{ global: foo; bar; local: *; @}
++@end smallexample
++
++When you link an application against a shared library that has versioned
++symbols, the application itself knows which version of each symbol it
++requires, and it also knows which version nodes it needs from each
++shared library it is linked against. Thus at runtime, the dynamic
++loader can make a quick check to make sure that the libraries you have
++linked against do in fact supply all of the version nodes that the
++application will need to resolve all of the dynamic symbols. In this
++way it is possible for the dynamic linker to know with certainty that
++all external symbols that it needs will be resolvable without having to
++search for each symbol reference.
++
++The symbol versioning is in effect a much more sophisticated way of
++doing minor version checking that SunOS does. The fundamental problem
++that is being addressed here is that typically references to external
++functions are bound on an as-needed basis, and are not all bound when
++the application starts up. If a shared library is out of date, a
++required interface may be missing; when the application tries to use
++that interface, it may suddenly and unexpectedly fail. With symbol
++versioning, the user will get a warning when they start their program if
++the libraries being used with the application are too old.
++
++There are several GNU extensions to Sun's versioning approach. The
++first of these is the ability to bind a symbol to a version node in the
++source file where the symbol is defined instead of in the versioning
++script. This was done mainly to reduce the burden on the library
++maintainer. You can do this by putting something like:
++@smallexample
++__asm__(".symver original_foo,foo@@VERS_1.1");
++@end smallexample
++@noindent
++in the C source file. This renames the function @samp{original_foo} to
++be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}.
++The @samp{local:} directive can be used to prevent the symbol
++@samp{original_foo} from being exported.
++
++The second GNU extension is to allow multiple versions of the same
++function to appear in a given shared library. In this way you can make
++an incompatible change to an interface without increasing the major
++version number of the shared library, while still allowing applications
++linked against the old interface to continue to function.
++
++To do this, you must use multiple @samp{.symver} directives in the
++source file. Here is an example:
++
++@smallexample
++__asm__(".symver original_foo,foo@@");
++__asm__(".symver old_foo,foo@@VERS_1.1");
++__asm__(".symver old_foo1,foo@@VERS_1.2");
++__asm__(".symver new_foo,foo@@@@VERS_2.0");
++@end smallexample
++
++In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the
++unspecified base version of the symbol. The source file that contains this
++example would define 4 C functions: @samp{original_foo}, @samp{old_foo},
++@samp{old_foo1}, and @samp{new_foo}.
++
++When you have multiple definitions of a given symbol, there needs to be
++some way to specify a default version to which external references to
++this symbol will be bound. You can do this with the
++@samp{foo@@@@VERS_2.0} type of @samp{.symver} directive. You can only
++declare one version of a symbol as the default in this manner; otherwise
++you would effectively have multiple definitions of the same symbol.
++
++If you wish to bind a reference to a specific version of the symbol
++within the shared library, you can use the aliases of convenience
++(i.e. @samp{old_foo}), or you can use the @samp{.symver} directive to
++specifically bind to an external version of the function in question.
++
++You can also specify the language in the version script:
++
++@smallexample
++VERSION extern "lang" @{ version-script-commands @}
++@end smallexample
++
++The supported @samp{lang}s are @samp{C}, @samp{C++}, and @samp{Java}.
++The linker will iterate over the list of symbols at the link time and
++demangle them according to @samp{lang} before matching them to the
++patterns specified in @samp{version-script-commands}.
++
++@node Expressions
++@section Expressions in Linker Scripts
++@cindex expressions
++@cindex arithmetic
++The syntax for expressions in the linker script language is identical to
++that of C expressions. All expressions are evaluated as integers. All
++expressions are evaluated in the same size, which is 32 bits if both the
++host and target are 32 bits, and is otherwise 64 bits.
++
++You can use and set symbol values in expressions.
++
++The linker defines several special purpose builtin functions for use in
++expressions.
++
++@menu
++* Constants:: Constants
++* Symbols:: Symbol Names
++* Location Counter:: The Location Counter
++* Operators:: Operators
++* Evaluation:: Evaluation
++* Expression Section:: The Section of an Expression
++* Builtin Functions:: Builtin Functions
++@end menu
++
++@node Constants
++@subsection Constants
++@cindex integer notation
++@cindex constants in linker scripts
++All constants are integers.
++
++As in C, the linker considers an integer beginning with @samp{0} to be
++octal, and an integer beginning with @samp{0x} or @samp{0X} to be
++hexadecimal. The linker considers other integers to be decimal.
++
++@cindex scaled integers
++@cindex K and M integer suffixes
++@cindex M and K integer suffixes
++@cindex suffixes for integers
++@cindex integer suffixes
++In addition, you can use the suffixes @code{K} and @code{M} to scale a
++constant by
++@c TEXI2ROFF-KILL
++@ifinfo
++@c END TEXI2ROFF-KILL
++@code{1024} or @code{1024*1024}
++@c TEXI2ROFF-KILL
++@end ifinfo
++@tex
++${\rm 1024}$ or ${\rm 1024}^2$
++@end tex
++@c END TEXI2ROFF-KILL
++respectively. For example, the following all refer to the same quantity:
++@smallexample
++ _fourk_1 = 4K;
++ _fourk_2 = 4096;
++ _fourk_3 = 0x1000;
++@end smallexample
++
++@node Symbols
++@subsection Symbol Names
++@cindex symbol names
++@cindex names
++@cindex quoted symbol names
++@kindex "
++Unless quoted, symbol names start with a letter, underscore, or period
++and may include letters, digits, underscores, periods, and hyphens.
++Unquoted symbol names must not conflict with any keywords. You can
++specify a symbol which contains odd characters or has the same name as a
++keyword by surrounding the symbol name in double quotes:
++@smallexample
++ "SECTION" = 9;
++ "with a space" = "also with a space" + 10;
++@end smallexample
++
++Since symbols can contain many non-alphabetic characters, it is safest
++to delimit symbols with spaces. For example, @samp{A-B} is one symbol,
++whereas @samp{A - B} is an expression involving subtraction.
++
++@node Location Counter
++@subsection The Location Counter
++@kindex .
++@cindex dot
++@cindex location counter
++@cindex current output location
++The special linker variable @dfn{dot} @samp{.} always contains the
++current output location counter. Since the @code{.} always refers to a
++location in an output section, it may only appear in an expression
++within a @code{SECTIONS} command. The @code{.} symbol may appear
++anywhere that an ordinary symbol is allowed in an expression.
++
++@cindex holes
++Assigning a value to @code{.} will cause the location counter to be
++moved. This may be used to create holes in the output section. The
++location counter may never be moved backwards.
++
++@smallexample
++SECTIONS
++@{
++ output :
++ @{
++ file1(.text)
++ . = . + 1000;
++ file2(.text)
++ . += 1000;
++ file3(.text)
++ @} = 0x12345678;
++@}
++@end smallexample
++@noindent
++In the previous example, the @samp{.text} section from @file{file1} is
++located at the beginning of the output section @samp{output}. It is
++followed by a 1000 byte gap. Then the @samp{.text} section from
++@file{file2} appears, also with a 1000 byte gap following before the
++@samp{.text} section from @file{file3}. The notation @samp{= 0x12345678}
++specifies what data to write in the gaps (@pxref{Output Section Fill}).
++
++@cindex dot inside sections
++Note: @code{.} actually refers to the byte offset from the start of the
++current containing object. Normally this is the @code{SECTIONS}
++statement, whoes start address is 0, hence @code{.} can be used as an
++absolute address. If @code{.} is used inside a section description
++however, it refers to the byte offset from the start of that section,
++not an absolute address. Thus in a script like this:
++
++@smallexample
++SECTIONS
++@{
++ . = 0x100
++ .text: @{
++ *(.text)
++ . = 0x200
++ @}
++ . = 0x500
++ .data: @{
++ *(.data)
++ . += 0x600
++ @}
++@}
++@end smallexample
++
++The @samp{.text} section will be assigned a starting address of 0x100
++and a size of exactly 0x200 bytes, even if there is not enough data in
++the @samp{.text} input sections to fill this area. (If there is too
++much data, an error will be produced because this would be an attempt to
++move @code{.} backwards). The @samp{.data} section will start at 0x500
++and it will have an extra 0x600 bytes worth of space after the end of
++the values from the @samp{.data} input sections and before the end of
++the @samp{.data} output section itself.
++
++@need 2000
++@node Operators
++@subsection Operators
++@cindex operators for arithmetic
++@cindex arithmetic operators
++@cindex precedence in expressions
++The linker recognizes the standard C set of arithmetic operators, with
++the standard bindings and precedence levels:
++@c TEXI2ROFF-KILL
++@ifinfo
++@c END TEXI2ROFF-KILL
++@smallexample
++precedence associativity Operators Notes
++(highest)
++1 left ! - ~ (1)
++2 left * / %
++3 left + -
++4 left >> <<
++5 left == != > < <= >=
++6 left &
++7 left |
++8 left &&
++9 left ||
++10 right ? :
++11 right &= += -= *= /= (2)
++(lowest)
++@end smallexample
++Notes:
++(1) Prefix operators
++(2) @xref{Assignments}.
++@c TEXI2ROFF-KILL
++@end ifinfo
++@tex
++\vskip \baselineskip
++%"lispnarrowing" is the extra indent used generally for smallexample
++\hskip\lispnarrowing\vbox{\offinterlineskip
++\hrule
++\halign
++{\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
++height2pt&\omit&&\omit&&\omit&\cr
++&Precedence&& Associativity &&{\rm Operators}&\cr
++height2pt&\omit&&\omit&&\omit&\cr
++\noalign{\hrule}
++height2pt&\omit&&\omit&&\omit&\cr
++&highest&&&&&\cr
++% '176 is tilde, '~' in tt font
++&1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
++&2&&left&&* / \%&\cr
++&3&&left&&+ -&\cr
++&4&&left&&>> <<&\cr
++&5&&left&&== != > < <= >=&\cr
++&6&&left&&\&&\cr
++&7&&left&&|&\cr
++&8&&left&&{\&\&}&\cr
++&9&&left&&||&\cr
++&10&&right&&? :&\cr
++&11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
++&lowest&&&&&\cr
++height2pt&\omit&&\omit&&\omit&\cr}
++\hrule}
++@end tex
++@iftex
++{
++@obeylines@parskip=0pt@parindent=0pt
++@dag@quad Prefix operators.
++@ddag@quad @xref{Assignments}.
++}
++@end iftex
++@c END TEXI2ROFF-KILL
++
++@node Evaluation
++@subsection Evaluation
++@cindex lazy evaluation
++@cindex expression evaluation order
++The linker evaluates expressions lazily. It only computes the value of
++an expression when absolutely necessary.
++
++The linker needs some information, such as the value of the start
++address of the first section, and the origins and lengths of memory
++regions, in order to do any linking at all. These values are computed
++as soon as possible when the linker reads in the linker script.
++
++However, other values (such as symbol values) are not known or needed
++until after storage allocation. Such values are evaluated later, when
++other information (such as the sizes of output sections) is available
++for use in the symbol assignment expression.
++
++The sizes of sections cannot be known until after allocation, so
++assignments dependent upon these are not performed until after
++allocation.
++
++Some expressions, such as those depending upon the location counter
++@samp{.}, must be evaluated during section allocation.
++
++If the result of an expression is required, but the value is not
++available, then an error results. For example, a script like the
++following
++@smallexample
++@group
++SECTIONS
++ @{
++ .text 9+this_isnt_constant :
++ @{ *(.text) @}
++ @}
++@end group
++@end smallexample
++@noindent
++will cause the error message @samp{non constant expression for initial
++address}.
++
++@node Expression Section
++@subsection The Section of an Expression
++@cindex expression sections
++@cindex absolute expressions
++@cindex relative expressions
++@cindex absolute and relocatable symbols
++@cindex relocatable and absolute symbols
++@cindex symbols, relocatable and absolute
++When the linker evaluates an expression, the result is either absolute
++or relative to some section. A relative expression is expressed as a
++fixed offset from the base of a section.
++
++The position of the expression within the linker script determines
++whether it is absolute or relative. An expression which appears within
++an output section definition is relative to the base of the output
++section. An expression which appears elsewhere will be absolute.
++
++A symbol set to a relative expression will be relocatable if you request
++relocatable output using the @samp{-r} option. That means that a
++further link operation may change the value of the symbol. The symbol's
++section will be the section of the relative expression.
++
++A symbol set to an absolute expression will retain the same value
++through any further link operation. The symbol will be absolute, and
++will not have any particular associated section.
++
++You can use the builtin function @code{ABSOLUTE} to force an expression
++to be absolute when it would otherwise be relative. For example, to
++create an absolute symbol set to the address of the end of the output
++section @samp{.data}:
++@smallexample
++SECTIONS
++ @{
++ .data : @{ *(.data) _edata = ABSOLUTE(.); @}
++ @}
++@end smallexample
++@noindent
++If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the
++@samp{.data} section.
++
++@node Builtin Functions
++@subsection Builtin Functions
++@cindex functions in expressions
++The linker script language includes a number of builtin functions for
++use in linker script expressions.
++
++@table @code
++@item ABSOLUTE(@var{exp})
++@kindex ABSOLUTE(@var{exp})
++@cindex expression, absolute
++Return the absolute (non-relocatable, as opposed to non-negative) value
++of the expression @var{exp}. Primarily useful to assign an absolute
++value to a symbol within a section definition, where symbol values are
++normally section relative. @xref{Expression Section}.
++
++@item ADDR(@var{section})
++@kindex ADDR(@var{section})
++@cindex section address in expression
++Return the absolute address (the VMA) of the named @var{section}. Your
++script must previously have defined the location of that section. In
++the following example, @code{symbol_1} and @code{symbol_2} are assigned
++identical values:
++@smallexample
++@group
++SECTIONS @{ @dots{}
++ .output1 :
++ @{
++ start_of_output_1 = ABSOLUTE(.);
++ @dots{}
++ @}
++ .output :
++ @{
++ symbol_1 = ADDR(.output1);
++ symbol_2 = start_of_output_1;
++ @}
++@dots{} @}
++@end group
++@end smallexample
++
++@item ALIGN(@var{exp})
++@kindex ALIGN(@var{exp})
++@cindex round up location counter
++@cindex align location counter
++Return the location counter (@code{.}) aligned to the next @var{exp}
++boundary. @var{exp} must be an expression whose value is a power of
++two. This is equivalent to
++@smallexample
++(. + @var{exp} - 1) & ~(@var{exp} - 1)
++@end smallexample
++
++@code{ALIGN} doesn't change the value of the location counter---it just
++does arithmetic on it. Here is an example which aligns the output
++@code{.data} section to the next @code{0x2000} byte boundary after the
++preceding section and sets a variable within the section to the next
++@code{0x8000} boundary after the input sections:
++@smallexample
++@group
++SECTIONS @{ @dots{}
++ .data ALIGN(0x2000): @{
++ *(.data)
++ variable = ALIGN(0x8000);
++ @}
++@dots{} @}
++@end group
++@end smallexample
++@noindent
++The first use of @code{ALIGN} in this example specifies the location of
++a section because it is used as the optional @var{address} attribute of
++a section definition (@pxref{Output Section Address}). The second use
++of @code{ALIGN} is used to defines the value of a symbol.
++
++The builtin function @code{NEXT} is closely related to @code{ALIGN}.
++
++@item BLOCK(@var{exp})
++@kindex BLOCK(@var{exp})
++This is a synonym for @code{ALIGN}, for compatibility with older linker
++scripts. It is most often seen when setting the address of an output
++section.
++
++@item DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
++@kindex DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
++This is equivalent to either
++@smallexample
++(ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - 1)))
++@end smallexample
++or
++@smallexample
++(ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - @var{commonpagesize})))
++@end smallexample
++@noindent
++depending on whether the latter uses fewer @var{commonpagesize} sized pages
++for the data segment (area between the result of this expression and
++@code{DATA_SEGMENT_END}) than the former or not.
++If the latter form is used, it means @var{commonpagesize} bytes of runtime
++memory will be saved at the expense of up to @var{commonpagesize} wasted
++bytes in the on-disk file.
++
++This expression can only be used directly in @code{SECTIONS} commands, not in
++any output section descriptions and only once in the linker script.
++@var{commonpagesize} should be less or equal to @var{maxpagesize} and should
++be the system page size the object wants to be optimized for (while still
++working on system page sizes up to @var{maxpagesize}).
++
++@noindent
++Example:
++@smallexample
++ . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
++@end smallexample
++
++@item DATA_SEGMENT_END(@var{exp})
++@kindex DATA_SEGMENT_END(@var{exp})
++This defines the end of data segment for @code{DATA_SEGMENT_ALIGN}
++evaluation purposes.
++
++@smallexample
++ . = DATA_SEGMENT_END(.);
++@end smallexample
++
++@item DEFINED(@var{symbol})
++@kindex DEFINED(@var{symbol})
++@cindex symbol defaults
++Return 1 if @var{symbol} is in the linker global symbol table and is
++defined, otherwise return 0. You can use this function to provide
++default values for symbols. For example, the following script fragment
++shows how to set a global symbol @samp{begin} to the first location in
++the @samp{.text} section---but if a symbol called @samp{begin} already
++existed, its value is preserved:
++
++@smallexample
++@group
++SECTIONS @{ @dots{}
++ .text : @{
++ begin = DEFINED(begin) ? begin : . ;
++ @dots{}
++ @}
++ @dots{}
++@}
++@end group
++@end smallexample
++
++@item LOADADDR(@var{section})
++@kindex LOADADDR(@var{section})
++@cindex section load address in expression
++Return the absolute LMA of the named @var{section}. This is normally
++the same as @code{ADDR}, but it may be different if the @code{AT}
++attribute is used in the output section definition (@pxref{Output
++Section LMA}).
++
++@kindex MAX
++@item MAX(@var{exp1}, @var{exp2})
++Returns the maximum of @var{exp1} and @var{exp2}.
++
++@kindex MIN
++@item MIN(@var{exp1}, @var{exp2})
++Returns the minimum of @var{exp1} and @var{exp2}.
++
++@item NEXT(@var{exp})
++@kindex NEXT(@var{exp})
++@cindex unallocated address, next
++Return the next unallocated address that is a multiple of @var{exp}.
++This function is closely related to @code{ALIGN(@var{exp})}; unless you
++use the @code{MEMORY} command to define discontinuous memory for the
++output file, the two functions are equivalent.
++
++@item SIZEOF(@var{section})
++@kindex SIZEOF(@var{section})
++@cindex section size
++Return the size in bytes of the named @var{section}, if that section has
++been allocated. If the section has not been allocated when this is
++evaluated, the linker will report an error. In the following example,
++@code{symbol_1} and @code{symbol_2} are assigned identical values:
++@smallexample
++@group
++SECTIONS@{ @dots{}
++ .output @{
++ .start = . ;
++ @dots{}
++ .end = . ;
++ @}
++ symbol_1 = .end - .start ;
++ symbol_2 = SIZEOF(.output);
++@dots{} @}
++@end group
++@end smallexample
++
++@item SIZEOF_HEADERS
++@itemx sizeof_headers
++@kindex SIZEOF_HEADERS
++@cindex header size
++Return the size in bytes of the output file's headers. This is
++information which appears at the start of the output file. You can use
++this number when setting the start address of the first section, if you
++choose, to facilitate paging.
++
++@cindex not enough room for program headers
++@cindex program headers, not enough room
++When producing an ELF output file, if the linker script uses the
++@code{SIZEOF_HEADERS} builtin function, the linker must compute the
++number of program headers before it has determined all the section
++addresses and sizes. If the linker later discovers that it needs
++additional program headers, it will report an error @samp{not enough
++room for program headers}. To avoid this error, you must avoid using
++the @code{SIZEOF_HEADERS} function, or you must rework your linker
++script to avoid forcing the linker to use additional program headers, or
++you must define the program headers yourself using the @code{PHDRS}
++command (@pxref{PHDRS}).
++@end table
++
++@node Implicit Linker Scripts
++@section Implicit Linker Scripts
++@cindex implicit linker scripts
++If you specify a linker input file which the linker can not recognize as
++an object file or an archive file, it will try to read the file as a
++linker script. If the file can not be parsed as a linker script, the
++linker will report an error.
++
++An implicit linker script will not replace the default linker script.
++
++Typically an implicit linker script would contain only symbol
++assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION}
++commands.
++
++Any input files read because of an implicit linker script will be read
++at the position in the command line where the implicit linker script was
++read. This can affect archive searching.
++
++@ifset GENERIC
++@node Machine Dependent
++@chapter Machine Dependent Features
++
++@cindex machine dependencies
++@command{ld} has additional features on some platforms; the following
++sections describe them. Machines where @command{ld} has no additional
++functionality are not listed.
++
++@menu
++* H8/300:: @code{ld} and the H8/300
++* i960:: @code{ld} and the Intel 960 family
++* ARM:: @code{ld} and the ARM family
++* HPPA ELF32:: @code{ld} and HPPA 32-bit ELF
++@ifset MMIX
++* MMIX:: @code{ld} and MMIX
++@end ifset
++@ifset TICOFF
++* TI COFF:: @command{ld} and TI COFF
++@end ifset
++@end menu
++@end ifset
++
++@c FIXME! This could use @raisesections/@lowersections, but there seems to be a conflict
++@c between those and node-defaulting.
++@ifset H8300
++@ifclear GENERIC
++@raisesections
++@end ifclear
++
++@node H8/300
++@section @command{ld} and the H8/300
++
++@cindex H8/300 support
++For the H8/300, @command{ld} can perform these global optimizations when
++you specify the @samp{--relax} command-line option.
++
++@table @emph
++@cindex relaxing on H8/300
++@item relaxing address modes
++@command{ld} finds all @code{jsr} and @code{jmp} instructions whose
++targets are within eight bits, and turns them into eight-bit
++program-counter relative @code{bsr} and @code{bra} instructions,
++respectively.
++
++@cindex synthesizing on H8/300
++@item synthesizing instructions
++@c FIXME: specifically mov.b, or any mov instructions really?
++@command{ld} finds all @code{mov.b} instructions which use the
++sixteen-bit absolute address form, but refer to the top
++page of memory, and changes them to use the eight-bit address form.
++(That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
++@samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
++top page of memory).
++@end table
++
++@ifclear GENERIC
++@lowersections
++@end ifclear
++@end ifset
++
++@ifclear GENERIC
++@ifset Hitachi
++@c This stuff is pointless to say unless you're especially concerned
++@c with Hitachi chips; don't enable it for generic case, please.
++@node Hitachi
++@chapter @command{ld} and other Hitachi chips
++
++@command{ld} also supports the H8/300H, the H8/500, and the Hitachi SH. No
++special features, commands, or command-line options are required for
++these chips.
++@end ifset
++@end ifclear
++
++@ifset I960
++@ifclear GENERIC
++@raisesections
++@end ifclear
++
++@node i960
++@section @command{ld} and the Intel 960 family
++
++@cindex i960 support
++
++You can use the @samp{-A@var{architecture}} command line option to
++specify 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 @command{ld} command line included @w{@samp{-ACA}} as
++well as @w{@samp{-ltry}}, the linker would look (in its built-in search
++paths, and in any paths you specify with @samp{-L}) for a library with
++the names
++
++@smallexample
++@group
++try
++libtry.a
++tryca
++libtryca.a
++@end group
++@end smallexample
++
++@noindent
++The first two possibilities would be considered in any event; the last
++two are due to the use of @w{@samp{-ACA}}.
++
++You can meaningfully use @samp{-A} more than once on a command line, since
++the 960 architecture family allows combination of target architectures; each
++use will add another pair of name variants to search for when @w{@samp{-l}}
++specifies a library.
++
++@cindex @option{--relax} on i960
++@cindex relaxing on i960
++@command{ld} supports the @samp{--relax} option for the i960 family. If
++you specify @samp{--relax}, @command{ld} finds all @code{balx} and
++@code{calx} instructions whose targets are within 24 bits, and turns
++them into 24-bit program-counter relative @code{bal} and @code{cal}
++instructions, respectively. @command{ld} also turns @code{cal}
++instructions into @code{bal} instructions when it determines that the
++target subroutine is a leaf routine (that is, the target subroutine does
++not itself call any subroutines).
++
++@ifclear GENERIC
++@lowersections
++@end ifclear
++@end ifset
++
++@ifclear GENERIC
++@raisesections
++@end ifclear
++
++@node ARM
++@section @command{ld}'s support for interworking between ARM and Thumb code
++
++@cindex ARM interworking support
++@kindex --support-old-code
++For the ARM, @command{ld} will generate code stubs to allow functions calls
++betweem ARM and Thumb code. These stubs only work with code that has
++been compiled and assembled with the @samp{-mthumb-interwork} command
++line option. If it is necessary to link with old ARM object files or
++libraries, which have not been compiled with the -mthumb-interwork
++option then the @samp{--support-old-code} command line switch should be
++given to the linker. This will make it generate larger stub functions
++which will work with non-interworking aware ARM code. Note, however,
++the linker does not support generating stubs for function calls to
++non-interworking aware Thumb code.
++
++@cindex thumb entry point
++@cindex entry point, thumb
++@kindex --thumb-entry=@var{entry}
++The @samp{--thumb-entry} switch is a duplicate of the generic
++@samp{--entry} switch, in that it sets the program's starting address.
++But it also sets the bottom bit of the address, so that it can be
++branched to using a BX instruction, and the program will start
++executing in Thumb mode straight away.
++
++@node HPPA ELF32
++@section @command{ld} and HPPA 32-bit ELF support
++@cindex HPPA multiple sub-space stubs
++@kindex --multi-subspace
++When generating a shared library, @command{ld} will by default generate
++import stubs suitable for use with a single sub-space application.
++The @samp{--multi-subspace} switch causes @command{ld} to generate export
++stubs, and different (larger) import stubs suitable for use with
++multiple sub-spaces.
++
++@cindex HPPA stub grouping
++@kindex --stub-group-size=@var{N}
++Long branch stubs and import/export stubs are placed by @command{ld} in
++stub sections located between groups of input sections.
++@samp{--stub-group-size} specifies the maximum size of a group of input
++sections handled by one stub section. Since branch offsets are signed,
++a stub section may serve two groups of input sections, one group before
++the stub section, and one group after it. However, when using
++conditional branches that require stubs, it may be better (for branch
++prediction) that stub sections only serve one group of input sections.
++A negative value for @samp{N} chooses this scheme, ensuring that
++branches to stubs always use a negative offset. Two special values of
++@samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
++@command{ld} to automatically size input section groups for the branch types
++detected, with the same behaviour regarding stub placement as other
++positive or negative values of @samp{N} respectively.
++
++Note that @samp{--stub-group-size} does not split input sections. A
++single input section larger than the group size specified will of course
++create a larger group (of one section). If input sections are too
++large, it may not be possible for a branch to reach its stub.
++
++@ifset MMIX
++@node MMIX
++@section @code{ld} and MMIX
++For MMIX, there is choice of generating @code{ELF} object files or
++@code{mmo} object files when linking. The simulator @code{mmix}
++understands the @code{mmo} format. The binutils @code{objcopy} utility
++can translate between the two formats.
++
++There is one special section, the @samp{.MMIX.reg_contents} section.
++Contents in this section is assumed to correspond to that of global
++registers, and symbols referring to it are translated to special symbols,
++equal to registers. In a final link, the start address of the
++@samp{.MMIX.reg_contents} section corresponds to the first allocated
++global register multiplied by 8. Register @code{$255} is not included in
++this section; it is always set to the program entry, which is at the
++symbol @code{Main} for @code{mmo} files.
++
++Symbols with the prefix @code{__.MMIX.start.}, for example
++@code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special;
++there must be only one each, even if they are local. The default linker
++script uses these to set the default start address of a section.
++
++Initial and trailing multiples of zero-valued 32-bit words in a section,
++are left out from an mmo file.
++@end ifset
++
++@ifset TICOFF
++@node TI COFF
++@section @command{ld}'s support for various TI COFF versions
++@cindex TI COFF versions
++@kindex --format=@var{version}
++The @samp{--format} switch allows selection of one of the various
++TI COFF versions. The latest of this writing is 2; versions 0 and 1 are
++also supported. The TI COFF versions also vary in header byte-order
++format; @command{ld} will read any version or byte order, but the output
++header format depends on the default specified by the specific target.
++@end ifset
++
++@ifclear GENERIC
++@lowersections
++@end ifclear
++
++@ifclear SingleFormat
++@node BFD
++@chapter BFD
++
++@cindex back end
++@cindex object file management
++@cindex object formats available
++@kindex objdump -i
++The linker accesses object and archive files using the BFD libraries.
++These libraries allow the linker to use the same routines to operate on
++object files whatever the object file format. A different object file
++format can be supported simply by creating a new BFD back end and adding
++it to the library. To conserve runtime memory, however, the linker and
++associated tools are usually configured to support only a subset of the
++object file formats available. You can use @code{objdump -i}
++(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
++list all the formats available for your configuration.
++
++@cindex BFD requirements
++@cindex requirements for BFD
++As with most implementations, BFD is a compromise between
++several conflicting requirements. The major factor influencing
++BFD design was efficiency: any time used converting between
++formats is time which would not have been spent had BFD not
++been involved. This is partly offset by abstraction payback; since
++BFD simplifies applications and back ends, more time and care
++may be spent optimizing algorithms for a greater speed.
++
++One minor artifact of the BFD solution which you should bear in
++mind is the potential for information loss. There are two places where
++useful information can be lost using the BFD mechanism: during
++conversion and during output. @xref{BFD information loss}.
++
++@menu
++* BFD outline:: How it works: an outline of BFD
++@end menu
++
++@node BFD outline
++@section How it works: an outline of BFD
++@cindex opening object files
++@include bfdsumm.texi
++@end ifclear
++
++@node Reporting Bugs
++@chapter Reporting Bugs
++@cindex bugs in @command{ld}
++@cindex reporting bugs in @command{ld}
++
++Your bug reports play an essential role in making @command{ld} reliable.
++
++Reporting a bug may help you by bringing a solution to your problem, or
++it may not. But in any case the principal function of a bug report is
++to help the entire community by making the next version of @command{ld}
++work better. Bug reports are your contribution to the maintenance of
++@command{ld}.
++
++In order for a bug report to serve its purpose, you must include the
++information that enables us to fix the bug.
++
++@menu
++* Bug Criteria:: Have you found a bug?
++* Bug Reporting:: How to report bugs
++@end menu
++
++@node Bug Criteria
++@section Have you found a bug?
++@cindex bug criteria
++
++If you are not sure whether you have found a bug, here are some guidelines:
++
++@itemize @bullet
++@cindex fatal signal
++@cindex linker crash
++@cindex crash of linker
++@item
++If the linker gets a fatal signal, for any input whatever, that is a
++@command{ld} bug. Reliable linkers never crash.
++
++@cindex error on valid input
++@item
++If @command{ld} produces an error message for valid input, that is a bug.
++
++@cindex invalid input
++@item
++If @command{ld} does not produce an error message for invalid input, that
++may be a bug. In the general case, the linker can not verify that
++object files are correct.
++
++@item
++If you are an experienced user of linkers, your suggestions for
++improvement of @command{ld} are welcome in any case.
++@end itemize
++
++@node Bug Reporting
++@section How to report bugs
++@cindex bug reports
++@cindex @command{ld} bugs, reporting
++
++A number of companies and individuals offer support for @sc{gnu}
++products. If you obtained @command{ld} from a support organization, we
++recommend you contact that organization first.
++
++You can find contact information for many support companies and
++individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
++distribution.
++
++Otherwise, send bug reports for @command{ld} to
++@samp{bug-binutils@@gnu.org}.
++
++The fundamental principle of reporting bugs usefully is this:
++@strong{report all the facts}. If you are not sure whether to state a
++fact or leave it out, state it!
++
++Often people omit facts because they think they know what causes the
++problem and assume that some details do not matter. Thus, you might
++assume that the name of a symbol you use in an example does not matter.
++Well, probably it does not, but one cannot be sure. Perhaps the bug is
++a stray memory reference which happens to fetch from the location where
++that name is stored in memory; perhaps, if the name were different, the
++contents of that location would fool the linker into doing the right
++thing despite the bug. Play it safe and give a specific, complete
++example. That is the easiest thing for you to do, and the most helpful.
++
++Keep in mind that the purpose of a bug report is to enable us to fix the bug if
++it is new to us. Therefore, always write your bug reports on the assumption
++that the bug has not been reported previously.
++
++Sometimes people give a few sketchy facts and ask, ``Does this ring a
++bell?'' Those bug reports are useless, and we urge everyone to
++@emph{refuse to respond to them} except to chide the sender to report
++bugs properly.
++
++To enable us to fix the bug, you should include all these things:
++
++@itemize @bullet
++@item
++The version of @command{ld}. @command{ld} announces it if you start it with
++the @samp{--version} argument.
++
++Without this, we will not know whether there is any point in looking for
++the bug in the current version of @command{ld}.
++
++@item
++Any patches you may have applied to the @command{ld} source, including any
++patches made to the @code{BFD} library.
++
++@item
++The type of machine you are using, and the operating system name and
++version number.
++
++@item
++What compiler (and its version) was used to compile @command{ld}---e.g.
++``@code{gcc-2.7}''.
++
++@item
++The command arguments you gave the linker to link your example and
++observe the bug. To guarantee you will not omit something important,
++list them all. A copy of the Makefile (or the output from make) is
++sufficient.
++
++If we were to try to guess the arguments, we would probably guess wrong
++and then we might not encounter the bug.
++
++@item
++A complete input file, or set of input files, that will reproduce the
++bug. It is generally most helpful to send the actual object files,
++uuencoded if necessary to get them through the mail system. Making them
++available for anonymous FTP is not as good, but may be the only
++reasonable choice for large object files.
++
++If the source files were assembled using @code{gas} or compiled using
++@code{gcc}, then it may be OK to send the source files rather than the
++object files. In this case, be sure to say exactly what version of
++@code{gas} or @code{gcc} was used to produce the object files. Also say
++how @code{gas} or @code{gcc} were configured.
++
++@item
++A description of what behavior you observe that you believe is
++incorrect. For example, ``It gets a fatal signal.''
++
++Of course, if the bug is that @command{ld} gets a fatal signal, then we
++will certainly notice it. But if the bug is incorrect output, we might
++not notice unless it is glaringly wrong. You might as well not give us
++a chance to make a mistake.
++
++Even if the problem you experience is a fatal signal, you should still
++say so explicitly. Suppose something strange is going on, such as, your
++copy of @command{ld} is out of synch, or you have encountered a bug in the
++C library on your system. (This has happened!) Your copy might crash
++and ours would not. If you told us to expect a crash, then when ours
++fails to crash, we would know that the bug was not happening for us. If
++you had not told us to expect a crash, then we would not be able to draw
++any conclusion from our observations.
++
++@item
++If you wish to suggest changes to the @command{ld} source, send us context
++diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
++@samp{-p} option. Always send diffs from the old file to the new file.
++If you even discuss something in the @command{ld} source, refer to it by
++context, not by line number.
++
++The line numbers in our development sources will not match those in your
++sources. Your line numbers would convey no useful information to us.
++@end itemize
++
++Here are some things that are not necessary:
++
++@itemize @bullet
++@item
++A description of the envelope of the bug.
++
++Often people who encounter a bug spend a lot of time investigating
++which changes to the input file will make the bug go away and which
++changes will not affect it.
++
++This is often time consuming and not very useful, because the way we
++will find the bug is by running a single example under the debugger
++with breakpoints, not by pure deduction from a series of examples.
++We recommend that you save your time for something else.
++
++Of course, if you can find a simpler example to report @emph{instead}
++of the original one, that is a convenience for us. Errors in the
++output will be easier to spot, running under the debugger will take
++less time, and so on.
++
++However, simplification is not vital; if you do not want to do this,
++report the bug anyway and send us the entire test case you used.
++
++@item
++A patch for the bug.
++
++A patch for the bug does help us if it is a good one. But do not omit
++the necessary information, such as the test case, on the assumption that
++a patch is all we need. We might see problems with your patch and decide
++to fix the problem another way, or we might not understand it at all.
++
++Sometimes with a program as complicated as @command{ld} it is very hard to
++construct an example that will make the program follow a certain path
++through the code. If you do not send us the example, we will not be
++able to construct one, so we will not be able to verify that the bug is
++fixed.
++
++And if we cannot understand what bug you are trying to fix, or why your
++patch should be an improvement, we will not install it. A test case will
++help us to understand.
++
++@item
++A guess about what the bug is or what it depends on.
++
++Such guesses are usually wrong. Even we cannot guess right about such
++things without first using the debugger to find the facts.
++@end itemize
++
++@node MRI
++@appendix MRI Compatible Script Files
++@cindex MRI compatibility
++To aid users making the transition to @sc{gnu} @command{ld} from the MRI
++linker, @command{ld} can use MRI compatible linker scripts as an
++alternative to the more general-purpose linker scripting language
++described in @ref{Scripts}. MRI compatible linker scripts have a much
++simpler command set than the scripting language otherwise used with
++@command{ld}. @sc{gnu} @command{ld} supports the most commonly used MRI
++linker commands; these commands are described here.
++
++In general, MRI scripts aren't of much use with the @code{a.out} object
++file format, since it only has three sections and MRI scripts lack some
++features to make use of them.
++
++You can specify a file containing an MRI-compatible script using the
++@samp{-c} command-line option.
++
++Each command in an MRI-compatible script occupies its own line; each
++command line starts with the keyword that identifies the command (though
++blank lines are also allowed for punctuation). If a line of an
++MRI-compatible script begins with an unrecognized keyword, @command{ld}
++issues a warning message, but continues processing the script.
++
++Lines beginning with @samp{*} are comments.
++
++You can write these commands using all upper-case letters, or all
++lower case; for example, @samp{chip} is the same as @samp{CHIP}.
++The following list shows only the upper-case form of each command.
++
++@table @code
++@cindex @code{ABSOLUTE} (MRI)
++@item ABSOLUTE @var{secname}
++@itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
++Normally, @command{ld} includes in the output file all sections from all
++the input files. However, in an MRI-compatible script, you can use the
++@code{ABSOLUTE} command to restrict the sections that will be present in
++your output program. If the @code{ABSOLUTE} command is used at all in a
++script, then only the sections named explicitly in @code{ABSOLUTE}
++commands will appear in the linker output. You can still use other
++input sections (whatever you select on the command line, or using
++@code{LOAD}) to resolve addresses in the output file.
++
++@cindex @code{ALIAS} (MRI)
++@item ALIAS @var{out-secname}, @var{in-secname}
++Use this command to place the data from input section @var{in-secname}
++in a section called @var{out-secname} in the linker output file.
++
++@var{in-secname} may be an integer.
++
++@cindex @code{ALIGN} (MRI)
++@item ALIGN @var{secname} = @var{expression}
++Align the section called @var{secname} to @var{expression}. The
++@var{expression} should be a power of two.
++
++@cindex @code{BASE} (MRI)
++@item BASE @var{expression}
++Use the value of @var{expression} as the lowest address (other than
++absolute addresses) in the output file.
++
++@cindex @code{CHIP} (MRI)
++@item CHIP @var{expression}
++@itemx CHIP @var{expression}, @var{expression}
++This command does nothing; it is accepted only for compatibility.
++
++@cindex @code{END} (MRI)
++@item END
++This command does nothing whatever; it's only accepted for compatibility.
++
++@cindex @code{FORMAT} (MRI)
++@item FORMAT @var{output-format}
++Similar to the @code{OUTPUT_FORMAT} command in the more general linker
++language, but restricted to one of these output formats:
++
++@enumerate
++@item
++S-records, if @var{output-format} is @samp{S}
++
++@item
++IEEE, if @var{output-format} is @samp{IEEE}
++
++@item
++COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
++@samp{COFF}
++@end enumerate
++
++@cindex @code{LIST} (MRI)
++@item LIST @var{anything}@dots{}
++Print (to the standard output file) a link map, as produced by the
++@command{ld} command-line option @samp{-M}.
++
++The keyword @code{LIST} may be followed by anything on the
++same line, with no change in its effect.
++
++@cindex @code{LOAD} (MRI)
++@item LOAD @var{filename}
++@itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
++Include one or more object file @var{filename} in the link; this has the
++same effect as specifying @var{filename} directly on the @command{ld}
++command line.
++
++@cindex @code{NAME} (MRI)
++@item NAME @var{output-name}
++@var{output-name} is the name for the program produced by @command{ld}; the
++MRI-compatible command @code{NAME} is equivalent to the command-line
++option @samp{-o} or the general script language command @code{OUTPUT}.
++
++@cindex @code{ORDER} (MRI)
++@item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
++@itemx ORDER @var{secname} @var{secname} @var{secname}
++Normally, @command{ld} orders the sections in its output file in the
++order in which they first appear in the input files. In an MRI-compatible
++script, you can override this ordering with the @code{ORDER} command. The
++sections you list with @code{ORDER} will appear first in your output
++file, in the order specified.
++
++@cindex @code{PUBLIC} (MRI)
++@item PUBLIC @var{name}=@var{expression}
++@itemx PUBLIC @var{name},@var{expression}
++@itemx PUBLIC @var{name} @var{expression}
++Supply a value (@var{expression}) for external symbol
++@var{name} used in the linker input files.
++
++@cindex @code{SECT} (MRI)
++@item SECT @var{secname}, @var{expression}
++@itemx SECT @var{secname}=@var{expression}
++@itemx SECT @var{secname} @var{expression}
++You can use any of these three forms of the @code{SECT} command to
++specify the start address (@var{expression}) for section @var{secname}.
++If you have more than one @code{SECT} statement for the same
++@var{secname}, only the @emph{first} sets the start address.
++@end table
++
++@node GNU Free Documentation License
++@appendix GNU Free Documentation License
++@cindex GNU Free Documentation License
++
++ GNU Free Documentation License
++
++ Version 1.1, March 2000
++
++ Copyright (C) 2000 Free Software Foundation, Inc.
++ 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
++
++ Everyone is permitted to copy and distribute verbatim copies
++ of this license document, but changing it is not allowed.
++
++
++0. PREAMBLE
++
++The purpose of this License is to make a manual, textbook, or other
++written document "free" in the sense of freedom: to assure everyone
++the effective freedom to copy and redistribute it, with or without
++modifying it, either commercially or noncommercially. Secondarily,
++this License preserves for the author and publisher a way to get
++credit for their work, while not being considered responsible for
++modifications made by others.
++
++This License is a kind of "copyleft", which means that derivative
++works of the document must themselves be free in the same sense. It
++complements the GNU General Public License, which is a copyleft
++license designed for free software.
++
++We have designed this License in order to use it for manuals for free
++software, because free software needs free documentation: a free
++program should come with manuals providing the same freedoms that the
++software does. But this License is not limited to software manuals;
++it can be used for any textual work, regardless of subject matter or
++whether it is published as a printed book. We recommend this License
++principally for works whose purpose is instruction or reference.
++
++
++1. APPLICABILITY AND DEFINITIONS
++
++This License applies to any manual or other work that contains a
++notice placed by the copyright holder saying it can be distributed
++under the terms of this License. The "Document", below, refers to any
++such manual or work. Any member of the public is a licensee, and is
++addressed as "you".
++
++A "Modified Version" of the Document means any work containing the
++Document or a portion of it, either copied verbatim, or with
++modifications and/or translated into another language.
++
++A "Secondary Section" is a named appendix or a front-matter section of
++the Document that deals exclusively with the relationship of the
++publishers or authors of the Document to the Document's overall subject
++(or to related matters) and contains nothing that could fall directly
++within that overall subject. (For example, if the Document is in part a
++textbook of mathematics, a Secondary Section may not explain any
++mathematics.) The relationship could be a matter of historical
++connection with the subject or with related matters, or of legal,
++commercial, philosophical, ethical or political position regarding
++them.
++
++The "Invariant Sections" are certain Secondary Sections whose titles
++are designated, as being those of Invariant Sections, in the notice
++that says that the Document is released under this License.
++
++The "Cover Texts" are certain short passages of text that are listed,
++as Front-Cover Texts or Back-Cover Texts, in the notice that says that
++the Document is released under this License.
++
++A "Transparent" copy of the Document means a machine-readable copy,
++represented in a format whose specification is available to the
++general public, whose contents can be viewed and edited directly and
++straightforwardly with generic text editors or (for images composed of
++pixels) generic paint programs or (for drawings) some widely available
++drawing editor, and that is suitable for input to text formatters or
++for automatic translation to a variety of formats suitable for input
++to text formatters. A copy made in an otherwise Transparent file
++format whose markup has been designed to thwart or discourage
++subsequent modification by readers is not Transparent. A copy that is
++not "Transparent" is called "Opaque".
++
++Examples of suitable formats for Transparent copies include plain
++ASCII without markup, Texinfo input format, LaTeX input format, SGML
++or XML using a publicly available DTD, and standard-conforming simple
++HTML designed for human modification. Opaque formats include
++PostScript, PDF, proprietary formats that can be read and edited only
++by proprietary word processors, SGML or XML for which the DTD and/or
++processing tools are not generally available, and the
++machine-generated HTML produced by some word processors for output
++purposes only.
++
++The "Title Page" means, for a printed book, the title page itself,
++plus such following pages as are needed to hold, legibly, the material
++this License requires to appear in the title page. For works in
++formats which do not have any title page as such, "Title Page" means
++the text near the most prominent appearance of the work's title,
++preceding the beginning of the body of the text.
++
++
++2. VERBATIM COPYING
++
++You may copy and distribute the Document in any medium, either
++commercially or noncommercially, provided that this License, the
++copyright notices, and the license notice saying this License applies
++to the Document are reproduced in all copies, and that you add no other
++conditions whatsoever to those of this License. You may not use
++technical measures to obstruct or control the reading or further
++copying of the copies you make or distribute. However, you may accept
++compensation in exchange for copies. If you distribute a large enough
++number of copies you must also follow the conditions in section 3.
++
++You may also lend copies, under the same conditions stated above, and
++you may publicly display copies.
++
++
++3. COPYING IN QUANTITY
++
++If you publish printed copies of the Document numbering more than 100,
++and the Document's license notice requires Cover Texts, you must enclose
++the copies in covers that carry, clearly and legibly, all these Cover
++Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
++the back cover. Both covers must also clearly and legibly identify
++you as the publisher of these copies. The front cover must present
++the full title with all words of the title equally prominent and
++visible. You may add other material on the covers in addition.
++Copying with changes limited to the covers, as long as they preserve
++the title of the Document and satisfy these conditions, can be treated
++as verbatim copying in other respects.
++
++If the required texts for either cover are too voluminous to fit
++legibly, you should put the first ones listed (as many as fit
++reasonably) on the actual cover, and continue the rest onto adjacent
++pages.
++
++If you publish or distribute Opaque copies of the Document numbering
++more than 100, you must either include a machine-readable Transparent
++copy along with each Opaque copy, or state in or with each Opaque copy
++a publicly-accessible computer-network location containing a complete
++Transparent copy of the Document, free of added material, which the
++general network-using public has access to download anonymously at no
++charge using public-standard network protocols. If you use the latter
++option, you must take reasonably prudent steps, when you begin
++distribution of Opaque copies in quantity, to ensure that this
++Transparent copy will remain thus accessible at the stated location
++until at least one year after the last time you distribute an Opaque
++copy (directly or through your agents or retailers) of that edition to
++the public.
++
++It is requested, but not required, that you contact the authors of the
++Document well before redistributing any large number of copies, to give
++them a chance to provide you with an updated version of the Document.
++
++
++4. MODIFICATIONS
++
++You may copy and distribute a Modified Version of the Document under
++the conditions of sections 2 and 3 above, provided that you release
++the Modified Version under precisely this License, with the Modified
++Version filling the role of the Document, thus licensing distribution
++and modification of the Modified Version to whoever possesses a copy
++of it. In addition, you must do these things in the Modified Version:
++
++A. Use in the Title Page (and on the covers, if any) a title distinct
++ from that of the Document, and from those of previous versions
++ (which should, if there were any, be listed in the History section
++ of the Document). You may use the same title as a previous version
++ if the original publisher of that version gives permission.
++B. List on the Title Page, as authors, one or more persons or entities
++ responsible for authorship of the modifications in the Modified
++ Version, together with at least five of the principal authors of the
++ Document (all of its principal authors, if it has less than five).
++C. State on the Title page the name of the publisher of the
++ Modified Version, as the publisher.
++D. Preserve all the copyright notices of the Document.
++E. Add an appropriate copyright notice for your modifications
++ adjacent to the other copyright notices.
++F. Include, immediately after the copyright notices, a license notice
++ giving the public permission to use the Modified Version under the
++ terms of this License, in the form shown in the Addendum below.
++G. Preserve in that license notice the full lists of Invariant Sections
++ and required Cover Texts given in the Document's license notice.
++H. Include an unaltered copy of this License.
++I. Preserve the section entitled "History", and its title, and add to
++ it an item stating at least the title, year, new authors, and
++ publisher of the Modified Version as given on the Title Page. If
++ there is no section entitled "History" in the Document, create one
++ stating the title, year, authors, and publisher of the Document as
++ given on its Title Page, then add an item describing the Modified
++ Version as stated in the previous sentence.
++J. Preserve the network location, if any, given in the Document for
++ public access to a Transparent copy of the Document, and likewise
++ the network locations given in the Document for previous versions
++ it was based on. These may be placed in the "History" section.
++ You may omit a network location for a work that was published at
++ least four years before the Document itself, or if the original
++ publisher of the version it refers to gives permission.
++K. In any section entitled "Acknowledgements" or "Dedications",
++ preserve the section's title, and preserve in the section all the
++ substance and tone of each of the contributor acknowledgements
++ and/or dedications given therein.
++L. Preserve all the Invariant Sections of the Document,
++ unaltered in their text and in their titles. Section numbers
++ or the equivalent are not considered part of the section titles.
++M. Delete any section entitled "Endorsements". Such a section
++ may not be included in the Modified Version.
++N. Do not retitle any existing section as "Endorsements"
++ or to conflict in title with any Invariant Section.
++
++If the Modified Version includes new front-matter sections or
++appendices that qualify as Secondary Sections and contain no material
++copied from the Document, you may at your option designate some or all
++of these sections as invariant. To do this, add their titles to the
++list of Invariant Sections in the Modified Version's license notice.
++These titles must be distinct from any other section titles.
++
++You may add a section entitled "Endorsements", provided it contains
++nothing but endorsements of your Modified Version by various
++parties--for example, statements of peer review or that the text has
++been approved by an organization as the authoritative definition of a
++standard.
++
++You may add a passage of up to five words as a Front-Cover Text, and a
++passage of up to 25 words as a Back-Cover Text, to the end of the list
++of Cover Texts in the Modified Version. Only one passage of
++Front-Cover Text and one of Back-Cover Text may be added by (or
++through arrangements made by) any one entity. If the Document already
++includes a cover text for the same cover, previously added by you or
++by arrangement made by the same entity you are acting on behalf of,
++you may not add another; but you may replace the old one, on explicit
++permission from the previous publisher that added the old one.
++
++The author(s) and publisher(s) of the Document do not by this License
++give permission to use their names for publicity for or to assert or
++imply endorsement of any Modified Version.
++
++
++5. COMBINING DOCUMENTS
++
++You may combine the Document with other documents released under this
++License, under the terms defined in section 4 above for modified
++versions, provided that you include in the combination all of the
++Invariant Sections of all of the original documents, unmodified, and
++list them all as Invariant Sections of your combined work in its
++license notice.
++
++The combined work need only contain one copy of this License, and
++multiple identical Invariant Sections may be replaced with a single
++copy. If there are multiple Invariant Sections with the same name but
++different contents, make the title of each such section unique by
++adding at the end of it, in parentheses, the name of the original
++author or publisher of that section if known, or else a unique number.
++Make the same adjustment to the section titles in the list of
++Invariant Sections in the license notice of the combined work.
++
++In the combination, you must combine any sections entitled "History"
++in the various original documents, forming one section entitled
++"History"; likewise combine any sections entitled "Acknowledgements",
++and any sections entitled "Dedications". You must delete all sections
++entitled "Endorsements."
++
++
++6. COLLECTIONS OF DOCUMENTS
++
++You may make a collection consisting of the Document and other documents
++released under this License, and replace the individual copies of this
++License in the various documents with a single copy that is included in
++the collection, provided that you follow the rules of this License for
++verbatim copying of each of the documents in all other respects.
++
++You may extract a single document from such a collection, and distribute
++it individually under this License, provided you insert a copy of this
++License into the extracted document, and follow this License in all
++other respects regarding verbatim copying of that document.
++
++
++7. AGGREGATION WITH INDEPENDENT WORKS
++
++A compilation of the Document or its derivatives with other separate
++and independent documents or works, in or on a volume of a storage or
++distribution medium, does not as a whole count as a Modified Version
++of the Document, provided no compilation copyright is claimed for the
++compilation. Such a compilation is called an "aggregate", and this
++License does not apply to the other self-contained works thus compiled
++with the Document, on account of their being thus compiled, if they
++are not themselves derivative works of the Document.
++
++If the Cover Text requirement of section 3 is applicable to these
++copies of the Document, then if the Document is less than one quarter
++of the entire aggregate, the Document's Cover Texts may be placed on
++covers that surround only the Document within the aggregate.
++Otherwise they must appear on covers around the whole aggregate.
++
++
++8. TRANSLATION
++
++Translation is considered a kind of modification, so you may
++distribute translations of the Document under the terms of section 4.
++Replacing Invariant Sections with translations requires special
++permission from their copyright holders, but you may include
++translations of some or all Invariant Sections in addition to the
++original versions of these Invariant Sections. You may include a
++translation of this License provided that you also include the
++original English version of this License. In case of a disagreement
++between the translation and the original English version of this
++License, the original English version will prevail.
++
++
++9. TERMINATION
++
++You may not copy, modify, sublicense, or distribute the Document except
++as expressly provided for under this License. Any other attempt to
++copy, modify, sublicense or distribute the Document is void, and will
++automatically terminate your rights under this License. However,
++parties who have received copies, or rights, from you under this
++License will not have their licenses terminated so long as such
++parties remain in full compliance.
++
++
++10. FUTURE REVISIONS OF THIS LICENSE
++
++The Free Software Foundation may publish new, revised versions
++of the GNU Free Documentation License from time to time. Such new
++versions will be similar in spirit to the present version, but may
++differ in detail to address new problems or concerns. See
++http://www.gnu.org/copyleft/.
++
++Each version of the License is given a distinguishing version number.
++If the Document specifies that a particular numbered version of this
++License "or any later version" applies to it, you have the option of
++following the terms and conditions either of that specified version or
++of any later version that has been published (not as a draft) by the
++Free Software Foundation. If the Document does not specify a version
++number of this License, you may choose any version ever published (not
++as a draft) by the Free Software Foundation.
++
++
++ADDENDUM: How to use this License for your documents
++
++To use this License in a document you have written, include a copy of
++the License in the document and put the following copyright and
++license notices just after the title page:
++
++@smallexample
++ Copyright (c) YEAR YOUR NAME.
++ 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 the Invariant Sections being LIST THEIR TITLES, with the
++ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
++ A copy of the license is included in the section entitled "GNU
++ Free Documentation License".
++@end smallexample
++
++If you have no Invariant Sections, write "with no Invariant Sections"
++instead of saying which ones are invariant. If you have no
++Front-Cover Texts, write "no Front-Cover Texts" instead of
++"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
++
++If your document contains nontrivial examples of program code, we
++recommend releasing these examples in parallel under your choice of
++free software license, such as the GNU General Public License,
++to permit their use in free software.
++
++@node Index
++@unnumbered Index
++
++@printindex cp
++
++@tex
++% I think something like @colophon should be in texinfo. In the
++% meantime:
++\long\def\colophon{\hbox to0pt{}\vfill
++\centerline{The body of this manual is set in}
++\centerline{\fontname\tenrm,}
++\centerline{with headings in {\bf\fontname\tenbf}}
++\centerline{and examples in {\tt\fontname\tentt}.}
++\centerline{{\it\fontname\tenit\/} and}
++\centerline{{\sl\fontname\tensl\/}}
++\centerline{are used for emphasis.}\vfill}
++\page\colophon
++% Blame: doc@cygnus.com, 28mar91.
++@end tex
++
++
++@contents
++@bye
projects / packages / binutils.git / commitdiff