core/system/devel/binutils/files/binutils-gdb.git-e20365c.patch

diff -Nuar binutils-2.26.orig/ld/ld_ld.texinfo binutils-2.26/ld/ld_ld.texinfo
--- binutils-2.26.orig/ld/ld_ld.texinfo	1970-01-01 02:00:00.000000000 +0200
+++ binutils-2.26/ld/ld_ld.texinfo	2016-04-03 07:40:47.774751534 +0300
@@ -0,0 +1,8404 @@
+\input texinfo
+@setfilename ld.info
+@c Copyright (C) 1991-2016 Free Software Foundation, Inc.
+@syncodeindex ky cp
+@c man begin INCLUDE
+@include configdoc.texi
+@c (configdoc.texi is generated by the Makefile)
+@include bfdver.texi
+@c man end
+
+@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 ARM
+@set C6X
+@set H8300
+@set HPPA
+@set I960
+@set M68HC11
+@set M68K
+@set MIPS
+@set MMIX
+@set MSP430
+@set NDS32
+@set NIOSII
+@set POWERPC
+@set POWERPC64
+@set Renesas
+@set SPU
+@set TICOFF
+@set WIN32
+@set XTENSA
+@end ifset
+@c man end
+
+@ifnottex
+@dircategory Software development
+@direntry
+* Ld: (ld).                       The GNU linker.
+@end direntry
+@end ifnottex
+
+@copying
+This file documents the @sc{gnu} linker LD
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+version @value{VERSION}.
+
+Copyright @copyright{} 1991-2016 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.3
+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''.
+@end copying
+@iftex
+@finalout
+@setchapternewpage odd
+@settitle The GNU linker
+@titlepage
+@title The GNU linker
+@sp 1
+@subtitle @code{ld}
+@ifset VERSION_PACKAGE
+@subtitle @value{VERSION_PACKAGE}
+@end ifset
+@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 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-2016 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.3
+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
+@contents
+@c FIXME: Talk about importance of *order* of args, cmds to linker!
+
+@ifnottex
+@node Top
+@top LD
+This file documents the @sc{gnu} linker ld
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+version @value{VERSION}.
+
+This document is distributed under the terms of the GNU Free
+Documentation License version 1.3.  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 Renesas
+* Renesas::                     ld and other Renesas micros
+@end ifset
+@ifset I960
+* i960::                        ld and the Intel 960 family
+@end ifset
+@ifset ARM
+* ARM::				ld and the ARM family
+@end ifset
+@ifset M68HC11
+* M68HC11/68HC12::              ld and the Motorola 68HC11 and 68HC12 families
+@end ifset
+@ifset HPPA
+* HPPA ELF32::                  ld and HPPA 32-bit ELF
+@end ifset
+@ifset M68K
+* M68K::                        ld and Motorola 68K family
+@end ifset
+@ifset MIPS
+* MIPS::                        ld and MIPS family
+@end ifset
+@ifset POWERPC
+* PowerPC ELF32::               ld and PowerPC 32-bit ELF Support
+@end ifset
+@ifset POWERPC64
+* PowerPC64 ELF64::             ld and PowerPC64 64-bit ELF Support
+@end ifset
+@ifset SPU
+* SPU ELF::			ld and SPU ELF Support
+@end ifset
+@ifset TICOFF
+* TI COFF::                     ld and the TI COFF
+@end ifset
+@ifset WIN32
+* Win32::                       ld and WIN32 (cygwin/mingw)
+@end ifset
+@ifset XTENSA
+* Xtensa::                      ld and Xtensa Processors
+@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
+* LD Index::                       LD Index
+@end menu
+@end ifnottex
+
+@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} 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 cannot 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.  Specifying a
+script in this way merely augments the main linker script, with the
+extra commands placed after the main script; use the @samp{-T} option
+to replace the default linker script entirely, but note the effect of
+the @code{INSERT} command.  @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 preceded 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
+(e.g. @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,--start-group foo.o bar.o -Wl,--end-group
+@end smallexample
+
+This is important, because otherwise the compiler driver program may
+silently drop the linker options, resulting in a bad link.  Confusion
+may also arise when passing options that require values through a
+driver, as the use of a space between option and argument acts as
+a separator, and causes the driver to pass only the option to the linker
+and the argument to the compiler.  In this case, it is simplest to use
+the joined forms of both single- and multiple-letter options, such as:
+
+@smallexample
+  gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
+@end smallexample
+
+Here is a table of the generic command line switches accepted by the GNU
+linker:
+
+@table @gcctabopt
+@include at-file.texi
+
+@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.
+
+@kindex --audit @var{AUDITLIB}
+@item --audit @var{AUDITLIB}
+Adds @var{AUDITLIB} to the @code{DT_AUDIT} entry of the dynamic section.
+@var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
+specified in the library.  If specified multiple times @code{DT_AUDIT}
+will contain a colon separated list of audit interfaces to use. If the linker
+finds an object with an audit entry while searching for shared libraries,
+it will add a corresponding @code{DT_DEPAUDIT} entry in the output file.
+This option is only meaningful on ELF platforms supporting the rtld-audit
+interface.
+
+@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}.
+
+@kindex --depaudit @var{AUDITLIB}
+@kindex -P @var{AUDITLIB}
+@item --depaudit @var{AUDITLIB}
+@itemx -P @var{AUDITLIB}
+Adds @var{AUDITLIB} to the @code{DT_DEPAUDIT} entry of the dynamic section.
+@var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
+specified in the library.  If specified multiple times @code{DT_DEPAUDIT}
+will contain a colon separated list of audit interfaces to use.  This
+option is only meaningful on ELF platforms supporting the rtld-audit interface.
+The -P option is provided for Solaris compatibility.
+
+@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.
+
+@kindex --exclude-libs
+@item --exclude-libs @var{lib},@var{lib},...
+Specifies a list of archive libraries from which symbols should not be automatically
+exported.  The library names may be delimited by commas or colons.  Specifying
+@code{--exclude-libs ALL} excludes symbols in all archive libraries from
+automatic export.  This option is available only for the i386 PE targeted
+port of the linker and for ELF targeted ports.  For i386 PE, symbols
+explicitly listed in a .def file are still exported, regardless of this
+option.  For ELF targeted ports, symbols affected by this option will
+be treated as hidden.
+
+@kindex --exclude-modules-for-implib
+@item --exclude-modules-for-implib @var{module},@var{module},...
+Specifies a list of object files or archive members, from which symbols
+should not be automatically exported, but which should be copied wholesale
+into the import library being generated during the link.  The module names
+may be delimited by commas or colons, and must match exactly the filenames
+used by @command{ld} to open the files; for archive members, this is simply
+the member name, but for object files the name listed must include and
+match precisely any path used to specify the input file on the linker's
+command-line.  This option is available only for the i386 PE targeted port
+of the linker.  Symbols explicitly listed in a .def file are still exported,
+regardless of this option.
+
+@cindex dynamic symbol table
+@kindex -E
+@kindex --export-dynamic
+@kindex --no-export-dynamic
+@item -E
+@itemx --export-dynamic
+@itemx --no-export-dynamic
+When creating a dynamically linked executable, using the @option{-E}
+option or the @option{--export-dynamic} option causes the linker to 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 either of these options (or use the
+@option{--no-export-dynamic} option to restore the default behavior), 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 dynamic list to control what symbols should
+be added to the dynamic symbol table if the output format supports it.
+See the description of @samp{--dynamic-list}.
+
+Note that this option is specific to ELF targeted ports.  PE targets
+support a similar function to export all symbols from a DLL or EXE; see
+the description of @samp{--export-all-symbols} below.
+
+@ifclear SingleFormat
+@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.
+@end ifclear
+
+@kindex -f @var{name}
+@kindex --auxiliary=@var{name}
+@item -f @var{name}
+@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 @var{name}
+@kindex --filter=@var{name}
+@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.
+@ifclear SingleFormat
+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.
+@end ifclear
+The @sc{gnu} linker will ignore the @option{-F} option when not
+creating an ELF shared object.
+
+@cindex finalization function
+@kindex -fini=@var{name}
+@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 @var{value}
+@kindex --gpsize=@var{value}
+@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 ELF that support 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=@var{name}
+@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{namespec}
+@kindex --library=@var{namespec}
+@item -l @var{namespec}
+@itemx --library=@var{namespec}
+Add the archive or object file specified by @var{namespec} to the
+list of files to link.  This option may be used any number of times.
+If @var{namespec} is of the form @file{:@var{filename}}, @command{ld}
+will search the library path for a file called @var{filename}, otherwise it
+will search the library path for a file called @file{lib@var{namespec}.a}.
+
+On systems which support shared libraries, @command{ld} may also search for
+files other than @file{lib@var{namespec}.a}.  Specifically, on ELF
+and SunOS systems, @command{ld} will search a directory for a library
+called @file{lib@var{namespec}.so} before searching for one called
+@file{lib@var{namespec}.a}.  (By convention, a @code{.so} extension
+indicates a shared library.)  Note that this behavior does not apply
+to @file{:@var{filename}}, which always specifies a file called
+@var{filename}.
+
+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.  @option{-L} options do not affect
+how @command{ld} searches for a linker script unless @option{-T}
+option is specified.
+
+If @var{searchdir} begins with @code{=}, then the @code{=} will be replaced
+by the @dfn{sysroot prefix}, controlled by the @samp{--sysroot} option, or
+specified when the linker is configured.
+
+@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 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.
+@item
+The values assigned to symbols.
+
+Note - symbols whose values are computed by an expression which
+involves a reference to a previous value of the same symbol may not
+have correct result displayed in the link map.  This is because the
+linker discards intermediate results and only retains the final value
+of an expression.  Under such circumstances the linker will display
+the final value enclosed by square brackets.  Thus for example a
+linker script containing:
+
+@smallexample
+   foo = 1
+   foo = foo * 4
+   foo = foo + 8
+@end smallexample
+
+will produce the following output in the link map if the @option{-M}
+option is used:
+
+@smallexample
+   0x00000001                foo = 0x1
+   [0x0000000c]                foo = (foo * 0x4)
+   [0x0000000c]                foo = (foo + 0x8)
+@end smallexample
+
+See @ref{Expressions} for more information about expressions in linker
+scripts.
+@end itemize
+
+@kindex -n
+@cindex read-only text
+@cindex NMAGIC
+@kindex --nmagic
+@item -n
+@itemx --nmagic
+Turn off page alignment of sections, and disable linking against shared
+libraries.  If the output format supports Unix style magic numbers,
+mark the output as @code{NMAGIC}.
+
+@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, and disable linking against shared
+libraries.  If the output format supports Unix style magic numbers,
+mark the output as @code{OMAGIC}. Note: Although a writable text section
+is allowed for PE-COFF targets, it does not conform to the format
+specification published by Microsoft.
+
+@kindex --no-omagic
+@cindex OMAGIC
+@item --no-omagic
+This option negates most of the effects of the @option{-N} option.  It
+sets the text section to be read-only, and forces the data segment to
+be page-aligned.  Note - this option does not enable linking against
+shared libraries.  Use @option{-Bdynamic} for this.
+
+@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.  At the moment this
+option only affects ELF shared library generation.  Future releases of
+the linker may make more use of this option.  Also currently there is
+no difference in the linker's behaviour for different non-zero values
+of this option.  Again this may change with future releases.
+
+@kindex --push-state
+@cindex push state governing input file handling
+@item --push-state
+The @option{--push-state} allows to preserve the current state of the
+flags which govern the input file handling so that they can all be
+restored with one corresponding @option{--pop-state} option.
+
+The option which are covered are: @option{-Bdynamic}, @option{-Bstatic},
+@option{-dn}, @option{-dy}, @option{-call_shared}, @option{-non_shared},
+@option{-static}, @option{-N}, @option{-n}, @option{--whole-archive},
+@option{--no-whole-archive}, @option{-r}, @option{-Ur},
+@option{--copy-dt-needed-entries}, @option{--no-copy-dt-needed-entries},
+@option{--as-needed}, @option{--no-as-needed}, and @option{-a}.
+
+One target for this option are specifications for @file{pkg-config}.  When
+used with the @option{--libs} option all possibly needed libraries are
+listed and then possibly linked with all the time.  It is better to return
+something as follows:
+
+@smallexample
+-Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state
+@end smallexample
+
+@kindex --pop-state
+@cindex pop state governing input file handling
+Undoes the effect of --push-state, restores the previous values of the
+flags governing input file handling.
+
+@kindex -q
+@kindex --emit-relocs
+@cindex retain relocations in final executable
+@item -q
+@itemx --emit-relocs
+Leave relocation sections and contents in fully linked executables.
+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.
+
+@kindex --force-dynamic
+@cindex forcing the creation of dynamic sections
+@item --force-dynamic
+Force the output file to have dynamic sections.  This option is specific
+to VxWorks targets.
+
+@cindex partial link
+@cindex relocatable output
+@kindex -r
+@kindex --relocatable
+@item -r
+@itemx --relocatable
+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 -dT @var{script}
+@kindex --default-script=@var{script}
+@cindex script files
+@item -dT @var{scriptfile}
+@itemx --default-script=@var{scriptfile}
+Use @var{scriptfile} as the default linker script.  @xref{Scripts}.
+
+This option is similar to the @option{--script} option except that
+processing of the script is delayed until after the rest of the
+command line has been processed.  This allows options placed after the
+@option{--default-script} option on the command line to affect the
+behaviour of the linker script, which can be important when the linker
+command line cannot be directly controlled by the user.  (eg because
+the command line is being constructed by another tool, such as
+@samp{gcc}).
+
+@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.
+
+If this option is being used to force additional modules to be pulled
+into the link, and if it is an error for the symbol to remain
+undefined, then the option @option{--require-defined} should be used
+instead.
+
+@kindex --require-defined=@var{symbol}
+@cindex symbols, require defined
+@cindex defined symbol
+@item --require-defined=@var{symbol}
+Require that @var{symbol} is defined in the output file.  This option
+is the same as option @option{--undefined} except that if @var{symbol}
+is not defined in the output file then the linker will issue an error
+and exit.  The same effect can be achieved in a linker script by using
+@code{EXTERN}, @code{ASSERT} and @code{DEFINED} together.  This option
+can be used multiple times to require additional symbols.
+
+@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 --orphan-handling=@var{MODE}
+@cindex orphan sections
+@cindex sections, orphan
+@item --orphan-handling=@var{MODE}
+Control how orphan sections are handled.  An orphan section is one not
+specifically mentioned in a linker script.  @xref{Orphan Sections}.
+
+@var{MODE} can have any of the following values:
+
+@table @code
+@item place
+Orphan sections are placed into a suitable output section following
+the strategy described in @ref{Orphan Sections}.  The option
+@samp{--unique} also effects how sections are placed.
+
+@item discard
+All orphan sections are discarded, by placing them in the
+@samp{/DISCARD/} section (@pxref{Output Section Discarding}).
+
+@item warn
+The linker will place the orphan section as for @code{place} and also
+issue a warning.
+
+@item error
+The linker will exit with an error if any orphan section is found.
+@end table
+
+The default if @samp{--orphan-handling} is not given is @code{place}.
+
+@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
+@item -X
+@itemx --discard-locals
+Delete all temporary local symbols.  (These symbols start with
+system-specific local label prefixes, typically @samp{.L} for ELF systems
+or @samp{L} for traditional a.out systems.)
+
+@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:
+@table @samp
+
+@item combreloc
+Combines multiple reloc sections and sorts them to make dynamic symbol
+lookup caching possible.
+
+@item defs
+Disallows undefined symbols in object files.  Undefined symbols in
+shared libraries are still allowed.
+
+@item execstack
+Marks the object as requiring executable stack.
+
+@item global
+This option is only meaningful when building a shared object.  It makes
+the symbols defined by this shared object available for symbol resolution
+of subsequently loaded libraries.
+
+@item initfirst
+This option is only meaningful when building a shared object.
+It marks the object so that its runtime initialization will occur
+before the runtime initialization of any other objects brought into
+the process at the same time.  Similarly the runtime finalization of
+the object will occur after the runtime finalization of any other
+objects.
+
+@item interpose
+Marks the object that its symbol table interposes before all symbols
+but the primary executable.
+
+@item lazy
+When generating an executable or shared library, mark it to tell the
+dynamic linker to defer function call resolution to the point when
+the function is called (lazy binding), rather than at load time.
+Lazy binding is the default.
+
+@item loadfltr
+Marks  the object that its filters be processed immediately at
+runtime.
+
+@item muldefs
+Allows multiple definitions.
+
+@item nocombreloc
+Disables multiple reloc sections combining.
+
+@item nocopyreloc
+Disable linker generated .dynbss variables used in place of variables
+defined in shared libraries.  May result in dynamic text relocations.
+
+@item nodefaultlib
+Marks the object that the search for dependencies of this object will
+ignore any default library search paths.
+
+@item nodelete
+Marks the object shouldn't be unloaded at runtime.
+
+@item nodlopen
+Marks the object not available to @code{dlopen}.
+
+@item nodump
+Marks the object can not be dumped by @code{dldump}.
+
+@item noexecstack
+Marks the object as not requiring executable stack.
+
+@item text
+Treat DT_TEXTREL in shared object as error.
+
+@item notext
+Don't treat DT_TEXTREL in shared object as error.
+
+@item textoff
+Don't treat DT_TEXTREL in shared object as error.
+
+@item norelro
+Don't create an ELF @code{PT_GNU_RELRO} segment header in the object.
+
+@item now
+When generating an executable or shared library, mark it to tell the
+dynamic linker to resolve all symbols when the program is started, or
+when the shared library is linked to using dlopen, instead of
+deferring function call resolution to the point when the function is
+first called.
+
+@item origin
+Marks the object may contain $ORIGIN.
+
+@item relro
+Create an ELF @code{PT_GNU_RELRO} segment header in the object.
+
+@item max-page-size=@var{value}
+Set the emulation maximum page size to @var{value}.
+
+@item common-page-size=@var{value}
+Set the emulation common page size to @var{value}.
+
+@item stack-size=@var{value}
+Specify a stack size for in an ELF @code{PT_GNU_STACK} segment.
+Specifying zero will override any default non-zero sized
+@code{PT_GNU_STACK} segment creation.
+
+@item bndplt
+Always generate BND prefix in PLT entries. Supported for Linux/x86_64.
+
+@item noextern-protected-data
+Don't treat protected data symbol as external when building shared
+library.  This option overrides linker backend default.  It can be used
+to workaround incorrect relocations against protected data symbols
+generated by compiler.  Updates on protected data symbols by another
+module aren't visible to the resulting shared library.  Supported for
+i386 and x86-64.
+
+@item call-nop=prefix-addr
+@itemx call-nop=prefix-nop
+@itemx call-nop=suffix-nop
+@itemx call-nop=prefix-@var{byte}
+@itemx call-nop=suffix-@var{byte}
+Specify the 1-byte @code{NOP} padding when transforming indirect call
+to a locally defined function, foo, via its GOT slot.
+@option{call-nop=prefix-addr} generates @code{0x67 call foo}.
+@option{call-nop=prefix-nop} generates @code{0x90 call foo}.
+@option{call-nop=suffix-nop} generates @code{call foo 0x90}.
+@option{call-nop=prefix-@var{byte}} generates @code{@var{byte} call foo}.
+@option{call-nop=suffix-@var{byte}} generates @code{call foo @var{byte}}.
+Supported for i386 and x86_64.
+
+@end table
+
+Other keywords are ignored for Solaris compatibility.
+
+@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 --accept-unknown-input-arch
+@kindex --no-accept-unknown-input-arch
+@item --accept-unknown-input-arch
+@itemx --no-accept-unknown-input-arch
+Tells the linker to accept input files whose architecture cannot be
+recognised.  The assumption is that the user knows what they are doing
+and deliberately wants to link in these unknown input files.  This was
+the default behaviour of the linker, before release 2.14.  The default
+behaviour from release 2.14 onwards is to reject such input files, and
+so the @samp{--accept-unknown-input-arch} option has been added to
+restore the old behaviour.
+
+@kindex --as-needed
+@kindex --no-as-needed
+@item --as-needed
+@itemx --no-as-needed
+This option affects ELF DT_NEEDED tags for dynamic libraries mentioned
+on the command line after the @option{--as-needed} option.  Normally
+the linker will add a DT_NEEDED tag for each dynamic library mentioned
+on the command line, regardless of whether the library is actually
+needed or not.  @option{--as-needed} causes a DT_NEEDED tag to only be
+emitted for a library that @emph{at that point in the link} satisfies a
+non-weak undefined symbol reference from a regular object file or, if
+the library is not found in the DT_NEEDED lists of other needed libraries, a
+non-weak undefined symbol reference from another needed dynamic library.
+Object files or libraries appearing on the command line @emph{after}
+the library in question do not affect whether the library is seen as
+needed.  This is similar to the rules for extraction of object files
+from archives.  @option{--no-as-needed} restores the default behaviour.
+
+@kindex --add-needed
+@kindex --no-add-needed
+@item --add-needed
+@itemx --no-add-needed
+These two options have been deprecated because of the similarity of
+their names to the @option{--as-needed} and @option{--no-as-needed}
+options.  They have been replaced by @option{--copy-dt-needed-entries}
+and @option{--no-copy-dt-needed-entries}.
+
+@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{--unresolved-symbols=report-all} 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.  This
+option also implies @option{--unresolved-symbols=report-all}.  This
+option can be used with @option{-shared}.  Doing so means that a
+shared library is being created but that all of the library's external
+references must be resolved by pulling in entries from static
+libraries.
+
+@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 can also be used with the
+@option{--export-dynamic} option, when creating a position independent
+executable, to bind references to global symbols to the definition within
+the executable.  This option is only meaningful on ELF platforms which
+support shared libraries and position independent executables.
+
+@kindex -Bsymbolic-functions
+@item -Bsymbolic-functions
+When creating a shared library, bind references to global function
+symbols to the definition within the shared library, if any.
+This option can also be used with the @option{--export-dynamic} option,
+when creating a position independent executable, to bind references
+to global function symbols to the definition within the executable.
+This option is only meaningful on ELF platforms which support shared
+libraries and position independent executables.
+
+@kindex --dynamic-list=@var{dynamic-list-file}
+@item --dynamic-list=@var{dynamic-list-file}
+Specify the name of a dynamic list file to the linker.  This is
+typically used when creating shared libraries to specify a list of
+global symbols whose references shouldn't be bound to the definition
+within the shared library, or creating dynamically linked executables
+to specify a list of symbols which should be added to the symbol table
+in the executable.  This option is only meaningful on ELF platforms
+which support shared libraries.
+
+The format of the dynamic list is the same as the version node without
+scope and node name.  See @ref{VERSION} for more information.
+
+@kindex --dynamic-list-data
+@item --dynamic-list-data
+Include all global data symbols to the dynamic list.
+
+@kindex --dynamic-list-cpp-new
+@item --dynamic-list-cpp-new
+Provide the builtin dynamic list for C++ operator new and delete.  It
+is mainly useful for building shared libstdc++.
+
+@kindex --dynamic-list-cpp-typeinfo
+@item --dynamic-list-cpp-typeinfo
+Provide the builtin dynamic list for C++ runtime type identification.
+
+@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 are 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 @option{--check-sections}.
+Section overlap is not usually checked for relocatable links.  You can
+force checking in that case by using the @option{--check-sections}
+option.
+
+@kindex --copy-dt-needed-entries
+@kindex --no-copy-dt-needed-entries
+@item --copy-dt-needed-entries
+@itemx --no-copy-dt-needed-entries
+This option affects the treatment of dynamic libraries referred to
+by DT_NEEDED tags @emph{inside} ELF dynamic libraries mentioned on the
+command line.  Normally the linker won't add a DT_NEEDED tag to the
+output binary for each library mentioned in a DT_NEEDED tag in an
+input dynamic library.  With @option{--copy-dt-needed-entries}
+specified on the command line however any dynamic libraries that
+follow it will have their DT_NEEDED entries added.  The default
+behaviour can be restored with @option{--no-copy-dt-needed-entries}.
+
+This option also has an effect on the resolution of symbols in dynamic
+libraries.  With @option{--copy-dt-needed-entries} dynamic libraries
+mentioned on the command line will be recursively searched, following
+their DT_NEEDED tags to other libraries, in order to resolve symbols
+required by the output binary.  With the default setting however
+the searching of dynamic libraries that follow it will stop with the
+dynamic library itself.  No DT_NEEDED links will be traversed to resolve
+symbols.
+
+@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.  If the symbol is defined as a common value then any files
+where this happens appear next.  Finally any files that reference the
+symbol are listed.
+
+@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}).
+@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 -I@var{file}
+@itemx --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.
+
+@kindex --no-dynamic-linker
+@item --no-dynamic-linker
+When producing an executable file, omit the request for a dynamic
+linker to be used at load-time.  This is only meaningful for ELF
+executables that contain dynamic relocations, and usually requires
+entry point code that is capable of processing these relocations.
+
+@kindex --fatal-warnings
+@kindex --no-fatal-warnings
+@item --fatal-warnings
+@itemx --no-fatal-warnings
+Treat all warnings as errors.  The default behaviour can be restored
+with the option @option{--no-fatal-warnings}.
+
+@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 --gc-sections
+@itemx --no-gc-sections
+Enable garbage collection of unused input sections.  It is ignored on
+targets that do not support this option.  The default behaviour (of not
+performing this garbage collection) can be restored by specifying
+@samp{--no-gc-sections} on the command line.  Note that garbage
+collection for COFF and PE format targets is supported, but the
+implementation is currently considered to be experimental.
+
+@samp{--gc-sections} decides which input sections are used by
+examining symbols and relocations.  The section containing the entry
+symbol and all sections containing symbols undefined on the
+command-line will be kept, as will sections containing symbols
+referenced by dynamic objects.  Note that when building shared
+libraries, the linker must assume that any visible symbol is
+referenced.  Once this initial set of sections has been determined,
+the linker recursively marks as used any section referenced by their
+relocations.  See @samp{--entry} and @samp{--undefined}.
+
+This option can be set when doing a partial link (enabled with option
+@samp{-r}).  In this case the root of symbols kept must be explicitly
+specified either by an @samp{--entry} or @samp{--undefined} option or by
+a @code{ENTRY} command in the linker script.
+
+@kindex --print-gc-sections
+@kindex --no-print-gc-sections
+@cindex garbage collection
+@item --print-gc-sections
+@itemx --no-print-gc-sections
+List all sections removed by garbage collection.  The listing is
+printed on stderr.  This option is only effective if garbage
+collection has been enabled via the @samp{--gc-sections}) option.  The
+default behaviour (of not listing the sections that are removed) can
+be restored by specifying @samp{--no-print-gc-sections} on the command
+line.
+
+@kindex --print-output-format
+@cindex output format
+@item --print-output-format
+Print the name of the default output format (perhaps influenced by
+other command-line options).  This is the string that would appear
+in an @code{OUTPUT_FORMAT} linker script command (@pxref{File Commands}).
+
+@kindex --print-memory-usage
+@cindex memory usage
+@item --print-memory-usage
+Print used size, total size and used size of memory regions created with
+the @ref{MEMORY} command.  This is useful on embedded targets to have a
+quick view of amount of free memory.  The format of the output has one
+headline and one line per region.  It is both human readable and easily
+parsable by tools.  Here is an example of an output:
+
+@smallexample
+Memory region         Used Size  Region Size  %age Used
+             ROM:        256 KB         1 MB     25.00%
+             RAM:          32 B         2 GB      0.00%
+@end smallexample
+
+@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=@var{mapfile}
+@item -Map=@var{mapfile}
+Print a link map to the file @var{mapfile}.  See the description of the
+@option{-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
+Report unresolved symbol references from regular object files.  This
+is done even if the linker is creating a non-symbolic shared library.
+The switch @option{--[no-]allow-shlib-undefined} controls the
+behaviour for reporting unresolved references found in shared
+libraries being linked in.
+
+@kindex --allow-multiple-definition
+@kindex -z muldefs
+@item --allow-multiple-definition
+@itemx -z muldefs
+Normally when a symbol is defined multiple times, the linker will
+report a fatal error. These options allow multiple definitions and the
+first definition will be used.
+
+@kindex --allow-shlib-undefined
+@kindex --no-allow-shlib-undefined
+@item --allow-shlib-undefined
+@itemx --no-allow-shlib-undefined
+Allows or disallows undefined symbols in shared libraries.
+This switch is similar to @option{--no-undefined} except that it
+determines the behaviour when the undefined symbols are in a
+shared library rather than a regular object file.  It does not affect
+how undefined symbols in regular object files are handled.
+
+The default behaviour is to report errors for any undefined symbols
+referenced in shared libraries if the linker is being used to create
+an executable, but to allow them if the linker is being used to create
+a shared library.
+
+The reasons for allowing undefined symbol references in shared
+libraries specified at link time are that:
+
+@itemize @bullet
+@item
+A shared library specified at link time may not be the same as the one
+that is available at load time, so the symbol might actually be
+resolvable at load time.
+@item
+There are some operating systems, eg BeOS and HPPA, where undefined
+symbols in shared libraries are normal.
+
+The BeOS kernel for example patches shared libraries at load time to
+select whichever function is most appropriate for the current
+architecture.  This is used, for example, to dynamically select an
+appropriate memset function.
+@end itemize
+
+@kindex --no-undefined-version
+@item --no-undefined-version
+Normally when a symbol has an undefined version, the linker will ignore
+it. This option disallows symbols with undefined version and a fatal error
+will be issued instead.
+
+@kindex --default-symver
+@item --default-symver
+Create and use a default symbol version (the soname) for unversioned
+exported symbols.
+
+@kindex --default-imported-symver
+@item --default-imported-symver
+Create and use a default symbol version (the soname) for unversioned
+imported 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-warn-search-mismatch
+@item --no-warn-search-mismatch
+Normally @command{ld} will give a warning if it finds an incompatible
+library during a library search.  This option silences the warning.
+
+@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=@var{output-format}
+@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 -pie
+@kindex --pic-executable
+@item -pie
+@itemx --pic-executable
+@cindex position independent executables
+Create a position independent executable.  This is currently only supported on
+ELF platforms.  Position independent executables are similar to shared
+libraries in that they are relocated by the dynamic linker to the virtual
+address the OS chooses for them (which can vary between invocations).  Like
+normal dynamically linked executables they can be executed and symbols
+defined in the executable cannot be overridden by shared libraries.
+
+@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
+@cindex --no-relax
+@item --relax
+@itemx --no-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
+@ifset XTENSA
+@xref{Xtensa,, @command{ld} and Xtensa Processors}.
+@end ifset
+@ifset M68HC11
+@xref{M68HC11/68HC12,,@command{ld} and the 68HC11 and 68HC12}.
+@end ifset
+@ifset NIOSII
+@xref{Nios II,,@command{ld} and the Altera Nios II}.
+@end ifset
+@ifset POWERPC
+@xref{PowerPC ELF32,,@command{ld} and PowerPC 32-bit ELF Support}.
+@end ifset
+
+On some platforms the @samp{--relax} option performs target specific,
+global optimizations that become possible when the linker resolves
+addressing in the program, such as relaxing address modes,
+synthesizing new instructions, selecting shorter version of current
+instructions, and combining constant values.
+
+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
+
+On platforms where @samp{--relax} is accepted the option
+@samp{--no-relax} can be used to disable the feature.
+
+@cindex retaining specified symbols
+@cindex stripping all but some symbols
+@cindex symbols, retaining selectively
+@kindex --retain-symbols-file=@var{filename}
+@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=@var{dir}
+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 path 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
+file systems.
+
+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=@var{dir}
+@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. Searching @option{-rpath} in this way is only supported
+by native linkers and cross linkers which have been configured with
+the @option{--with-sysroot} option.
+@item
+On an ELF system, for native linkers, if the @option{-rpath} and
+@option{-rpath-link} options were not used, search the contents of the
+environment variable @code{LD_RUN_PATH}.
+@item
+On SunOS, if the @option{-rpath} option was not used, search any
+directories specified using @option{-L} options.
+@item
+For a native linker, search 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.
+
+@kindex --sort-common
+@item --sort-common
+@itemx --sort-common=ascending
+@itemx --sort-common=descending
+This option tells @command{ld} to sort the common symbols by alignment in
+ascending or descending order when it places them in the appropriate output
+sections.  The symbol alignments considered are sixteen-byte or larger,
+eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps
+between symbols due to alignment constraints.  If no sorting order is
+specified, then descending order is assumed.
+
+@kindex --sort-section=name
+@item --sort-section=name
+This option will apply @code{SORT_BY_NAME} to all wildcard section
+patterns in the linker script.
+
+@kindex --sort-section=alignment
+@item --sort-section=alignment
+This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
+patterns in the linker script.
+
+@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 --sysroot=@var{directory}
+@item --sysroot=@var{directory}
+Use @var{directory} as the location of the sysroot, overriding the
+configure-time default.  This option is only supported by linkers
+that were configured using @option{--with-sysroot}.
+
+@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}
+Same as @option{--section-start}, with @code{.bss}, @code{.data} or
+@code{.text} as the @var{sectionname}.
+
+@kindex -Ttext-segment=@var{org}
+@item -Ttext-segment=@var{org}
+@cindex text segment origin, cmd line
+When creating an ELF executable, it will set the address of the first
+byte of the text segment.
+
+@kindex -Trodata-segment=@var{org}
+@item -Trodata-segment=@var{org}
+@cindex rodata segment origin, cmd line
+When creating an ELF executable or shared object for a target where
+the read-only data is in its own segment separate from the executable
+text, it will set the address of the first byte of the read-only data segment.
+
+@kindex -Tldata-segment=@var{org}
+@item -Tldata-segment=@var{org}
+@cindex ldata segment origin, cmd line
+When creating an ELF executable or shared object for x86-64 medium memory
+model, it will set the address of the first byte of the ldata segment.
+
+@kindex --unresolved-symbols
+@item --unresolved-symbols=@var{method}
+Determine how to handle unresolved symbols.  There are four possible
+values for @samp{method}:
+
+@table @samp
+@item ignore-all
+Do not report any unresolved symbols.
+
+@item report-all
+Report all unresolved symbols.  This is the default.
+
+@item ignore-in-object-files
+Report unresolved symbols that are contained in shared libraries, but
+ignore them if they come from regular object files.
+
+@item ignore-in-shared-libs
+Report unresolved symbols that come from regular object files, but
+ignore them if they come from shared libraries.  This can be useful
+when creating a dynamic binary and it is known that all the shared
+libraries that it should be referencing are included on the linker's
+command line.
+@end table
+
+The behaviour for shared libraries on their own can also be controlled
+by the @option{--[no-]allow-shlib-undefined} option.
+
+Normally the linker will generate an error message for each reported
+unresolved symbol but the option @option{--warn-unresolved-symbols}
+can change this to a warning.
+
+@kindex --verbose[=@var{NUMBER}]
+@cindex verbose[=@var{NUMBER}]
+@item --dll-verbose
+@itemx --verbose[=@var{NUMBER}]
+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. If the optional @var{NUMBER}
+argument > 1, plugin symbol status will also be displayed.
+
+@kindex --version-script=@var{version-scriptfile}
+@cindex version script, symbol versions
+@item --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 hierarchy for the library being created.  This option
+is only fully supported on ELF platforms which support shared libraries;
+see @ref{VERSION}.  It is partially supported on PE platforms, which can
+use version scripts to filter symbol visibility in auto-export mode: any
+symbols marked @samp{local} in the version script will not be exported.
+@xref{WIN32}.
+
+@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 --warn-shared-textrel
+@item --warn-shared-textrel
+Warn if the linker adds a DT_TEXTREL to a shared object.
+
+@kindex --warn-alternate-em
+@item --warn-alternate-em
+Warn if an object has alternate ELF machine code.
+
+@kindex --warn-unresolved-symbols
+@item --warn-unresolved-symbols
+If the linker is going to report an unresolved symbol (see the option
+@option{--unresolved-symbols}) it will normally generate an error.
+This option makes it generate a warning instead.
+
+@kindex --error-unresolved-symbols
+@item --error-unresolved-symbols
+This restores the linker's default behaviour of generating errors when
+it is reporting unresolved symbols.
+
+@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=@var{symbol}
+@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 (size_t c)
+@{
+  printf ("malloc called with %zu\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 --eh-frame-hdr
+@item --eh-frame-hdr
+Request creation of @code{.eh_frame_hdr} section and ELF
+@code{PT_GNU_EH_FRAME} segment header.
+
+@kindex --ld-generated-unwind-info
+@item --no-ld-generated-unwind-info
+Request creation of @code{.eh_frame} unwind info for linker
+generated code sections like PLT.  This option is on by default
+if linker generated unwind info is supported.
+
+@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 new dynamic tags will be created as needed
+and older dynamic tags will be omitted.
+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.
+
+@kindex --hash-size=@var{number}
+@item --hash-size=@var{number}
+Set the default size of the linker's hash tables to a prime number
+close to @var{number}.  Increasing this value can reduce the length of
+time it takes the linker to perform its tasks, at the expense of
+increasing the linker's memory requirements.  Similarly reducing this
+value can reduce the memory requirements at the expense of speed.
+
+@kindex --hash-style=@var{style}
+@item --hash-style=@var{style}
+Set the type of linker's hash table(s).  @var{style} can be either
+@code{sysv} for classic ELF @code{.hash} section, @code{gnu} for
+new style GNU @code{.gnu.hash} section or @code{both} for both
+the classic ELF @code{.hash} and new style GNU @code{.gnu.hash}
+hash tables.  The default is @code{sysv}.
+
+@kindex --compress-debug-sections=none
+@kindex --compress-debug-sections=zlib
+@kindex --compress-debug-sections=zlib-gnu
+@kindex --compress-debug-sections=zlib-gabi
+@item --compress-debug-sections=none
+@itemx --compress-debug-sections=zlib
+@itemx --compress-debug-sections=zlib-gnu
+@itemx --compress-debug-sections=zlib-gabi
+On ELF platforms , these options control how DWARF debug sections are
+compressed using zlib.  @option{--compress-debug-sections=none} doesn't
+compress DWARF debug sections.
+@option{--compress-debug-sections=zlib-gnu} compresses DWARF debug
+sections and rename debug section names to begin with @samp{.zdebug}
+instead of @samp{.debug}.  @option{--compress-debug-sections=zlib}
+and @option{--compress-debug-sections=zlib-gabi}
+compress DWARF debug sections with SHF_COMPRESSED from the ELF ABI.
+The default behaviour varies depending upon the target involved and
+the configure options used to build the toolchain.  The default can be
+determined by examing the output from the linker's @option{--help} option.
+
+@kindex --reduce-memory-overheads
+@item --reduce-memory-overheads
+This option reduces memory requirements at ld runtime, at the expense of
+linking speed.  This was introduced to select the old O(n^2) algorithm
+for link map file generation, rather than the new O(n) algorithm which uses
+about 40% more memory for symbol storage.
+
+Another effect of the switch is to set the default hash table size to
+1021, which again saves memory at the cost of lengthening the linker's
+run time.  This is not done however if the @option{--hash-size} switch
+has been used.
+
+The @option{--reduce-memory-overheads} switch may be also be used to
+enable other tradeoffs in future versions of the linker.
+
+@kindex --build-id
+@kindex --build-id=@var{style}
+@item --build-id
+@itemx --build-id=@var{style}
+Request the creation of a @code{.note.gnu.build-id} ELF note section
+or a @code{.buildid} COFF section.  The contents of the note are
+unique bits identifying this linked file.  @var{style} can be
+@code{uuid} to use 128 random bits, @code{sha1} to use a 160-bit
+@sc{SHA1} hash on the normative parts of the output contents,
+@code{md5} to use a 128-bit @sc{MD5} hash on the normative parts of
+the output contents, or @code{0x@var{hexstring}} to use a chosen bit
+string specified as an even number of hexadecimal digits (@code{-} and
+@code{:} characters between digit pairs are ignored).  If @var{style}
+is omitted, @code{sha1} is used.
+
+The @code{md5} and @code{sha1} styles produces an identifier
+that is always the same in an identical output file, but will be
+unique among all nonidentical output files.  It is not intended
+to be compared as a checksum for the file's contents.  A linked
+file may be changed later by other tools, but the build ID bit
+string identifying the original linked file does not change.
+
+Passing @code{none} for @var{style} disables the setting from any
+@code{--build-id} options earlier on the command line.
+@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.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@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}.
+[This is an i386 PE specific option]
+
+@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.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --enable-long-section-names
+@kindex --disable-long-section-names
+@item --enable-long-section-names
+@itemx --disable-long-section-names
+The PE variants of the COFF object format add an extension that permits
+the use of section names longer than eight characters, the normal limit
+for COFF.  By default, these names are only allowed in object files, as
+fully-linked executable images do not carry the COFF string table required
+to support the longer names.  As a GNU extension, it is possible to
+allow their use in executable images as well, or to (probably pointlessly!)
+disallow it in object files, by using these two options.  Executable images
+generated with these long section names are slightly non-standard, carrying
+as they do a string table, and may generate confusing output when examined
+with non-GNU PE-aware tools, such as file viewers and dumpers.  However,
+GDB relies on the use of PE long section names to find Dwarf-2 debug
+information sections in an executable image at runtime, and so if neither
+option is specified on the command-line, @command{ld} will enable long
+section names, overriding the default and technically correct behaviour,
+when it finds the presence of debug information while linking an executable
+image and not stripping symbols.
+[This option is valid for all PE targeted ports of the linker]
+
+@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.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --leading-underscore
+@kindex --no-leading-underscore
+@item --leading-underscore
+@itemx --no-leading-underscore
+For most targets default symbol-prefix is an underscore and is defined
+in target's description. By this option it is possible to
+disable/enable the default underscore symbol-prefix.
+
+@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}.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@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.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --exclude-all-symbols
+@item --exclude-all-symbols
+Specifies no symbols should be automatically exported.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@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.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@cindex heap size
+@kindex --heap
+@item --heap @var{reserve}
+@itemx --heap @var{reserve},@var{commit}
+Specify the number of bytes of memory to reserve (and optionally commit)
+to be used as heap for this program.  The default is 1MB reserved, 4K
+committed.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@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.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --kill-at
+@item --kill-at
+If given, the stdcall suffixes (@@@var{nn}) will be stripped from
+symbols before they are exported.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --large-address-aware
+@item --large-address-aware
+If given, the appropriate bit in the ``Characteristics'' field of the COFF
+header is set to indicate that this executable supports virtual addresses
+greater than 2 gigabytes.  This should be used in conjunction with the /3GB
+or /USERVA=@var{value} megabytes switch in the ``[operating systems]''
+section of the BOOT.INI.  Otherwise, this bit has no effect.
+[This option is specific to PE targeted ports of the linker]
+
+@kindex --disable-large-address-aware
+@item --disable-large-address-aware
+Reverts the effect of a previous @samp{--large-address-aware} option.
+This is useful if @samp{--large-address-aware} is always set by the compiler
+driver (e.g. Cygwin gcc) and the executable does not support virtual
+addresses greater than 2 gigabytes.
+[This option is specific to PE targeted ports of the linker]
+
+@kindex --major-image-version
+@item --major-image-version @var{value}
+Sets the major number of the ``image version''.  Defaults to 1.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --major-os-version
+@item --major-os-version @var{value}
+Sets the major number of the ``os version''.  Defaults to 4.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --major-subsystem-version
+@item --major-subsystem-version @var{value}
+Sets the major number of the ``subsystem version''.  Defaults to 4.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --minor-image-version
+@item --minor-image-version @var{value}
+Sets the minor number of the ``image version''.  Defaults to 0.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --minor-os-version
+@item --minor-os-version @var{value}
+Sets the minor number of the ``os version''.  Defaults to 0.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --minor-subsystem-version
+@item --minor-subsystem-version @var{value}
+Sets the minor number of the ``subsystem version''.  Defaults to 0.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@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.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@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 behaviour
+makes it possible to skip a separate @code{dlltool} import library
+creation step.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --enable-auto-image-base
+@item --enable-auto-image-base
+@itemx --enable-auto-image-base=@var{value}
+Automatically choose the image base for DLLs, optionally starting with base
+@var{value}, 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.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@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.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@cindex DLLs, linking to
+@kindex --dll-search-prefix
+@item --dll-search-prefix @var{string}
+When linking dynamically to a dll without an import library,
+search for @code{<string><basename>.dll} in preference to
+@code{lib<basename>.dll}. This behaviour 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}.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@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 import libraries with those DATA exports. Note: Use of the
+'auto-import' extension will cause the text section of the image file
+to be made writable. This does not conform to the PE-COFF format
+specification published by Microsoft.
+
+Note - use of the 'auto-import' extension will also cause read only
+data which would normally be placed into the .rdata section to be
+placed into the .data section instead.  This is in order to work
+around a problem with consts that is described here:
+http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html
+
+Using 'auto-import' 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 way is to use --enable-runtime-pseudo-reloc switch. This leaves the task
+of adjusting references in your client code for runtime environment, so
+this method works only when runtime environment supports this feature.
+
+A second 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 third 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 fourth 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).
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --disable-auto-import
+@item --disable-auto-import
+Do not attempt to do sophisticated linking of @code{_symbol} to
+@code{__imp__symbol} for DATA imports from DLLs.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --enable-runtime-pseudo-reloc
+@item --enable-runtime-pseudo-reloc
+If your code contains expressions described in --enable-auto-import section,
+that is, DATA imports from DLL with non-zero offset, this switch will create
+a vector of 'runtime pseudo relocations' which can be used by runtime
+environment to adjust references to such data in your client code.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --disable-runtime-pseudo-reloc
+@item --disable-runtime-pseudo-reloc
+Do not create pseudo relocations for non-zero offset DATA imports from
+DLLs.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@kindex --enable-extra-pe-debug
+@item --enable-extra-pe-debug
+Show additional debug info related to auto-import symbol thunking.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@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.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@cindex stack size
+@kindex --stack
+@item --stack @var{reserve}
+@itemx --stack @var{reserve},@var{commit}
+Specify the number of bytes of memory to reserve (and optionally commit)
+to be used as stack for this program.  The default is 2MB reserved, 4K
+committed.
+[This option is specific to the i386 PE targeted port of the linker]
+
+@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}, @code{posix}, and @code{xbox}.  You may optionally set
+the subsystem version also.  Numeric values are also accepted for
+@var{which}.
+[This option is specific to the i386 PE targeted port of the linker]
+
+The following options set flags in the @code{DllCharacteristics} field
+of the PE file header:
+[These options are specific to PE targeted ports of the linker]
+
+@kindex --high-entropy-va
+@item --high-entropy-va
+Image is compatible with 64-bit address space layout randomization
+(ASLR).
+
+@kindex --dynamicbase
+@item --dynamicbase
+The image base address may be relocated using address space layout
+randomization (ASLR).  This feature was introduced with MS Windows
+Vista for i386 PE targets.
+
+@kindex --forceinteg
+@item --forceinteg
+Code integrity checks are enforced.
+
+@kindex --nxcompat
+@item --nxcompat
+The image is compatible with the Data Execution Prevention.
+This feature was introduced with MS Windows XP SP2 for i386 PE targets.
+
+@kindex --no-isolation
+@item --no-isolation
+Although the image understands isolation, do not isolate the image.
+
+@kindex --no-seh
+@item --no-seh
+The image does not use SEH. No SE handler may be called from
+this image.
+
+@kindex --no-bind
+@item --no-bind
+Do not bind this image.
+
+@kindex --wdmdriver
+@item --wdmdriver
+The driver uses the MS Windows Driver Model.
+
+@kindex --tsaware
+@item --tsaware
+The image is Terminal Server aware.
+
+@kindex --insert-timestamp
+@item --insert-timestamp
+@itemx --no-insert-timestamp
+Insert a real timestamp into the image.  This is the default behaviour
+as it matches legacy code and it means that the image will work with
+other, proprietary tools.  The problem with this default is that it
+will result in slightly different images being produced each time the
+same sources are linked.  The option @option{--no-insert-timestamp}
+can be used to insert a zero value for the timestamp, this ensuring
+that binaries produced from identical sources will compare
+identically.
+@end table
+
+@c man end
+
+@ifset C6X
+@subsection Options specific to C6X uClinux targets
+
+@c man begin OPTIONS
+
+The C6X uClinux target uses a binary format called DSBT to support shared
+libraries.  Each shared library in the system needs to have a unique index;
+all executables use an index of 0.
+
+@table @gcctabopt
+
+@kindex --dsbt-size
+@item --dsbt-size @var{size}
+This option sets the number of entries in the DSBT of the current executable
+or shared library to @var{size}.  The default is to create a table with 64
+entries.
+
+@kindex --dsbt-index
+@item --dsbt-index @var{index}
+This option sets the DSBT index of the current executable or shared library
+to @var{index}.  The default is 0, which is appropriate for generating
+executables.  If a shared library is generated with a DSBT index of 0, the
+@code{R_C6000_DSBT_INDEX} relocs are copied into the output file.
+
+@kindex --no-merge-exidx-entries
+The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent
+exidx entries in frame unwind info.
+
+@end table
+
+@c man end
+@end ifset
+
+@ifset M68HC11
+@subsection Options specific to Motorola 68HC11 and 68HC12 targets
+
+@c man begin OPTIONS
+
+The 68HC11 and 68HC12 linkers support specific options to control the
+memory bank switching mapping and trampoline code generation.
+
+@table @gcctabopt
+
+@kindex --no-trampoline
+@item --no-trampoline
+This option disables the generation of trampoline. By default a trampoline
+is generated for each far function which is called using a @code{jsr}
+instruction (this happens when a pointer to a far function is taken).
+
+@kindex --bank-window
+@item --bank-window @var{name}
+This option indicates to the linker the name of the memory region in
+the @samp{MEMORY} specification that describes the memory bank window.
+The definition of such region is then used by the linker to compute
+paging and addresses within the memory window.
+
+@end table
+
+@c man end
+@end ifset
+
+@ifset M68K
+@subsection Options specific to Motorola 68K target
+
+@c man begin OPTIONS
+
+The following options are supported to control handling of GOT generation
+when linking for 68K targets.
+
+@table @gcctabopt
+
+@kindex --got
+@item --got=@var{type}
+This option tells the linker which GOT generation scheme to use.
+@var{type} should be one of @samp{single}, @samp{negative},
+@samp{multigot} or @samp{target}.  For more information refer to the
+Info entry for @file{ld}.
+
+@end table
+
+@c man end
+@end ifset
+
+@ifset MIPS
+@subsection Options specific to MIPS targets
+
+@c man begin OPTIONS
+
+The following options are supported to control microMIPS instruction
+generation when linking for MIPS targets.
+
+@table @gcctabopt
+
+@kindex --insn32
+@item --insn32
+@kindex --no-insn32
+@itemx --no-insn32
+These options control the choice of microMIPS instructions used in code
+generated by the linker, such as that in the PLT or lazy binding stubs,
+or in relaxation.  If @samp{--insn32} is used, then the linker only uses
+32-bit instruction encodings.  By default or if @samp{--no-insn32} is
+used, all instruction encodings are used, including 16-bit ones where
+possible.
+
+@end table
+
+@c man end
+@end ifset
+
+@ifset UsesEnvVars
+@node Environment
+@section Environment Variables
+
+@c man begin ENVIRONMENT
+
+You can change the behaviour of @command{ld} with the environment variables
+@ifclear SingleFormat
+@code{GNUTARGET},
+@end ifclear
+@code{LDEMULATION} and @code{COLLECT_NO_DEMANGLE}.
+
+@ifclear SingleFormat
+@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.
+@end ifclear
+
+@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 means 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
+
+* REGION_ALIAS::		Assign alias names to memory regions
+* 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 a target specific symbol, if it is defined;  For many
+targets this is @code{start}, but PE and BeOS based systems for example
+check a list of possible entry symbols, matching the first one found.
+@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.
+
+You can place @code{INCLUDE} directives at the top level, in @code{MEMORY} or
+@code{SECTIONS} commands, or in output section descriptions.
+
+@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.
+
+In case a @dfn{sysroot prefix} is configured, and the filename starts
+with the @samp{/} character, and the script being processed was
+located inside the @dfn{sysroot prefix}, the filename will be looked
+for in the @dfn{sysroot prefix}.  Otherwise, the linker will try to
+open the file in the current directory.  If it is not found, the
+linker will search through the archive library search path.
+The @dfn{sysroot prefix} can also be forced by specifying @code{=}
+as the first character in the filename path.  See also 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 AS_NEEDED(@var{file}, @var{file}, @dots{})
+@itemx AS_NEEDED(@var{file} @var{file} @dots{})
+@kindex AS_NEEDED(@var{files})
+This construct can appear only inside of the @code{INPUT} or @code{GROUP}
+commands, among other filenames.  The files listed will be handled
+as if they appear directly in the @code{INPUT} or @code{GROUP} commands,
+with the exception of ELF shared libraries, that will be added only
+when they are actually needed.  This construct essentially enables
+@option{--as-needed} option for all the files listed inside of it
+and restores previous @option{--as-needed} resp. @option{--no-as-needed}
+setting afterwards.
+
+@item OUTPUT(@var{filename})
+@kindex OUTPUT(@var{filename})
+@cindex output file name in linker script
+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 REGION_ALIAS
+@subsection Assign alias names to memory regions
+@kindex REGION_ALIAS(@var{alias}, @var{region})
+@cindex region alias
+@cindex region names
+
+Alias names can be added to existing memory regions created with the
+@ref{MEMORY} command.  Each name corresponds to at most one memory region.
+
+@smallexample
+REGION_ALIAS(@var{alias}, @var{region})
+@end smallexample
+
+The @code{REGION_ALIAS} function creates an alias name @var{alias} for the
+memory region @var{region}.  This allows a flexible mapping of output sections
+to memory regions.  An example follows.
+
+Suppose we have an application for embedded systems which come with various
+memory storage devices.  All have a general purpose, volatile memory @code{RAM}
+that allows code execution or data storage.  Some may have a read-only,
+non-volatile memory @code{ROM} that allows code execution and read-only data
+access.  The last variant is a read-only, non-volatile memory @code{ROM2} with
+read-only data access and no code execution capability.  We have four output
+sections:
+
+@itemize @bullet
+@item
+@code{.text} program code;
+@item
+@code{.rodata} read-only data;
+@item
+@code{.data} read-write initialized data;
+@item
+@code{.bss} read-write zero initialized data.
+@end itemize
+
+The goal is to provide a linker command file that contains a system independent
+part defining the output sections and a system dependent part mapping the
+output sections to the memory regions available on the system.  Our embedded
+systems come with three different memory setups @code{A}, @code{B} and
+@code{C}:
+@multitable @columnfractions .25 .25 .25 .25
+@item Section @tab Variant A @tab Variant B @tab Variant C
+@item .text @tab RAM @tab ROM @tab ROM
+@item .rodata @tab RAM @tab ROM @tab ROM2
+@item .data @tab RAM @tab RAM/ROM @tab RAM/ROM2
+@item .bss @tab RAM @tab RAM @tab RAM
+@end multitable
+The notation @code{RAM/ROM} or @code{RAM/ROM2} means that this section is
+loaded into region @code{ROM} or @code{ROM2} respectively.  Please note that
+the load address of the @code{.data} section starts in all three variants at
+the end of the @code{.rodata} section.
+
+The base linker script that deals with the output sections follows.  It
+includes the system dependent @code{linkcmds.memory} file that describes the
+memory layout:
+@smallexample
+INCLUDE linkcmds.memory
+
+SECTIONS
+  @{
+    .text :
+      @{
+        *(.text)
+      @} > REGION_TEXT
+    .rodata :
+      @{
+        *(.rodata)
+        rodata_end = .;
+      @} > REGION_RODATA
+    .data : AT (rodata_end)
+      @{
+        data_start = .;
+        *(.data)
+      @} > REGION_DATA
+    data_size = SIZEOF(.data);
+    data_load_start = LOADADDR(.data);
+    .bss :
+      @{
+        *(.bss)
+      @} > REGION_BSS
+  @}
+@end smallexample
+
+Now we need three different @code{linkcmds.memory} files to define memory
+regions and alias names.  The content of @code{linkcmds.memory} for the three
+variants @code{A}, @code{B} and @code{C}:
+@table @code
+@item A
+Here everything goes into the @code{RAM}.
+@smallexample
+MEMORY
+  @{
+    RAM : ORIGIN = 0, LENGTH = 4M
+  @}
+
+REGION_ALIAS("REGION_TEXT", RAM);
+REGION_ALIAS("REGION_RODATA", RAM);
+REGION_ALIAS("REGION_DATA", RAM);
+REGION_ALIAS("REGION_BSS", RAM);
+@end smallexample
+@item B
+Program code and read-only data go into the @code{ROM}.  Read-write data goes
+into the @code{RAM}.  An image of the initialized data is loaded into the
+@code{ROM} and will be copied during system start into the @code{RAM}.
+@smallexample
+MEMORY
+  @{
+    ROM : ORIGIN = 0, LENGTH = 3M
+    RAM : ORIGIN = 0x10000000, LENGTH = 1M
+  @}
+
+REGION_ALIAS("REGION_TEXT", ROM);
+REGION_ALIAS("REGION_RODATA", ROM);
+REGION_ALIAS("REGION_DATA", RAM);
+REGION_ALIAS("REGION_BSS", RAM);
+@end smallexample
+@item C
+Program code goes into the @code{ROM}.  Read-only data goes into the
+@code{ROM2}.  Read-write data goes into the @code{RAM}.  An image of the
+initialized data is loaded into the @code{ROM2} and will be copied during
+system start into the @code{RAM}.
+@smallexample
+MEMORY
+  @{
+    ROM : ORIGIN = 0, LENGTH = 2M
+    ROM2 : ORIGIN = 0x10000000, LENGTH = 1M
+    RAM : ORIGIN = 0x20000000, LENGTH = 1M
+  @}
+
+REGION_ALIAS("REGION_TEXT", ROM);
+REGION_ALIAS("REGION_RODATA", ROM2);
+REGION_ALIAS("REGION_DATA", RAM);
+REGION_ALIAS("REGION_BSS", RAM);
+@end smallexample
+@end table
+
+It is possible to write a common system initialization routine to copy the
+@code{.data} section from @code{ROM} or @code{ROM2} into the @code{RAM} if
+necessary:
+@smallexample
+#include <string.h>
+
+extern char data_start [];
+extern char data_size [];
+extern char data_load_start [];
+
+void copy_data(void)
+@{
+  if (data_start != data_load_start)
+    @{
+      memcpy(data_start, data_load_start, (size_t) data_size);
+    @}
+@}
+@end smallexample
+
+@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}.
+
+Note that assertions are checked before the final stages of linking
+take place.  This means that expressions involving symbols PROVIDEd
+inside section definitions will fail if the user has not set values
+for those symbols.  The only exception to this rule is PROVIDEd
+symbols that just reference dot.  Thus an assertion like this:
+
+@smallexample
+  .stack :
+  @{
+    PROVIDE (__stack = .);
+    PROVIDE (__stack_size = 0x100);
+    ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
+  @}
+@end smallexample
+
+will fail if @code{__stack_size} is not defined elsewhere.  Symbols
+PROVIDEd outside of section definitions are evaluated earlier, so they
+can be used inside ASSERTions.  Thus:
+
+@smallexample
+  PROVIDE (__stack_size = 0x100);
+  .stack :
+  @{
+    PROVIDE (__stack = .);
+    ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
+  @}
+@end smallexample
+
+will work.
+
+@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 INSERT [ AFTER | BEFORE ] @var{output_section}
+@kindex INSERT
+@cindex insert user script into default script
+This command is typically used in a script specified by @samp{-T} to
+augment the default @code{SECTIONS} with, for example, overlays.  It
+inserts all prior linker script statements after (or before)
+@var{output_section}, and also causes @samp{-T} to not override the
+default linker script.  The exact insertion point is as for orphan
+sections.  @xref{Location Counter}.  The insertion happens after the
+linker has mapped input sections to output sections.  Prior to the
+insertion, since @samp{-T} scripts are parsed before the default
+linker script, statements in the @samp{-T} script occur before the
+default linker script statements in the internal linker representation
+of the script.  In particular, input section assignments will be made
+to @samp{-T} output sections before those in the default script.  Here
+is an example of how a @samp{-T} script using @code{INSERT} might look:
+
+@smallexample
+SECTIONS
+@{
+  OVERLAY :
+  @{
+    .ov1 @{ ov1*(.text) @}
+    .ov2 @{ ov2*(.text) @}
+  @}
+@}
+INSERT AFTER .text;
+@end smallexample
+
+@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
+
+@item LD_FEATURE(@var{string})
+@kindex LD_FEATURE(@var{string})
+This command may be used to modify @command{ld} behavior.  If
+@var{string} is @code{"SANE_EXPR"} then absolute symbols and numbers
+in a script are simply treated as numbers everywhere.
+@xref{Expression Section}.
+@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 and place it into the symbol table with a global scope.
+
+@menu
+* Simple Assignments::		Simple Assignments
+* HIDDEN::			HIDDEN
+* PROVIDE::			PROVIDE
+* PROVIDE_HIDDEN::		PROVIDE_HIDDEN
+* Source Code Reference::	How to use a linker script defined symbol in source code
+@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.  @xref{Location Counter}.
+
+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 HIDDEN
+@subsection HIDDEN
+@cindex HIDDEN
+For ELF targeted ports, define a symbol that will be hidden and won't be
+exported.  The syntax is @code{HIDDEN(@var{symbol} = @var{expression})}.
+
+Here is the example from @ref{Simple Assignments}, rewritten to use
+@code{HIDDEN}:
+
+@smallexample
+HIDDEN(floating_point = 0);
+SECTIONS
+@{
+  .text :
+    @{
+      *(.text)
+      HIDDEN(_etext = .);
+    @}
+  HIDDEN(_bdata = (. + 3) & ~ 3);
+  .data : @{ *(.data) @}
+@}
+@end smallexample
+@noindent
+In this case none of the three symbols will be visible outside this module.
+
+@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 PROVIDE_HIDDEN
+@subsection PROVIDE_HIDDEN
+@cindex PROVIDE_HIDDEN
+Similar to @code{PROVIDE}.  For ELF targeted ports, the symbol will be
+hidden and won't be exported.
+
+@node Source Code Reference
+@subsection Source Code Reference
+
+Accessing a linker script defined variable from source code is not
+intuitive.  In particular a linker script symbol is not equivalent to
+a variable declaration in a high level language, it is instead a
+symbol that does not have a value.
+
+Before going further, it is important to note that compilers often
+transform names in the source code into different names when they are
+stored in the symbol table.  For example, Fortran compilers commonly
+prepend or append an underscore, and C++ performs extensive @samp{name
+mangling}.  Therefore there might be a discrepancy between the name
+of a variable as it is used in source code and the name of the same
+variable as it is defined in a linker script.  For example in C a
+linker script variable might be referred to as:
+
+@smallexample
+  extern int foo;
+@end smallexample
+
+But in the linker script it might be defined as:
+
+@smallexample
+  _foo = 1000;
+@end smallexample
+
+In the remaining examples however it is assumed that no name
+transformation has taken place.
+
+When a symbol is declared in a high level language such as C, two
+things happen.  The first is that the compiler reserves enough space
+in the program's memory to hold the @emph{value} of the symbol.  The
+second is that the compiler creates an entry in the program's symbol
+table which holds the symbol's @emph{address}.  ie the symbol table
+contains the address of the block of memory holding the symbol's
+value.  So for example the following C declaration, at file scope:
+
+@smallexample
+  int foo = 1000;
+@end smallexample
+
+creates an entry called @samp{foo} in the symbol table.  This entry
+holds the address of an @samp{int} sized block of memory where the
+number 1000 is initially stored.
+
+When a program references a symbol the compiler generates code that
+first accesses the symbol table to find the address of the symbol's
+memory block and then code to read the value from that memory block.
+So:
+
+@smallexample
+  foo = 1;
+@end smallexample
+
+looks up the symbol @samp{foo} in the symbol table, gets the address
+associated with this symbol and then writes the value 1 into that
+address.  Whereas:
+
+@smallexample
+  int * a = & foo;
+@end smallexample
+
+looks up the symbol @samp{foo} in the symbol table, gets its address
+and then copies this address into the block of memory associated with
+the variable @samp{a}.
+
+Linker scripts symbol declarations, by contrast, create an entry in
+the symbol table but do not assign any memory to them.  Thus they are
+an address without a value.  So for example the linker script definition:
+
+@smallexample
+  foo = 1000;
+@end smallexample
+
+creates an entry in the symbol table called @samp{foo} which holds
+the address of memory location 1000, but nothing special is stored at
+address 1000.  This means that you cannot access the @emph{value} of a
+linker script defined symbol - it has no value - all you can do is
+access the @emph{address} of a linker script defined symbol.
+
+Hence when you are using a linker script defined symbol in source code
+you should always take the address of the symbol, and never attempt to
+use its value.  For example suppose you want to copy the contents of a
+section of memory called .ROM into a section called .FLASH and the
+linker script contains these declarations:
+
+@smallexample
+@group
+  start_of_ROM   = .ROM;
+  end_of_ROM     = .ROM + sizeof (.ROM);
+  start_of_FLASH = .FLASH;
+@end group
+@end smallexample
+
+Then the C source code to perform the copy would be:
+
+@smallexample
+@group
+  extern char start_of_ROM, end_of_ROM, start_of_FLASH;
+
+  memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
+@end group
+@end smallexample
+
+Note the use of the @samp{&} operators.  These are correct.
+Alternatively the symbols can be treated as the names of vectors or
+arrays and then the code will again work as expected:
+
+@smallexample
+@group
+  extern char start_of_ROM[], end_of_ROM[], start_of_FLASH[];
+
+  memcpy (start_of_FLASH, start_of_ROM, end_of_ROM - start_of_ROM);
+@end group
+@end smallexample
+
+Note how using this method does not require the use of @samp{&}
+operators.
+
+@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})]
+  [ALIGN(@var{section_align}) | ALIGN_WITH_INPUT]
+  [SUBALIGN(@var{subsection_align})]
+  [@var{constraint}]
+  @{
+    @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 comma at the end may be required if a @var{fillexp} is used and
+the next @var{sections-command} looks like a continuation of the expression.
+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.  This address is optional, but if it
+is provided then the output address will be set exactly as specified.
+
+If the output address is not specified then one will be chosen for the
+section, based on the heuristic below.  This address will be adjusted
+to fit the alignment requirement of the output section.  The
+alignment requirement is the strictest alignment of any input section
+contained within the output section.
+
+The output section address heuristic is as follows:
+
+@itemize @bullet
+@item
+If an output memory @var{region} is set for the section then it
+is added to this region and its address will be the next free address
+in that region.
+
+@item
+If the MEMORY command has been used to create a list of memory
+regions then the first region which has attributes compatible with the
+section is selected to contain it.  The section's output address will
+be the next free address in that region; @ref{MEMORY}.
+
+@item
+If no memory regions were specified, or none match the section then
+the output address will be based on the current value of the location
+counter.
+@end itemize
+
+@noindent
+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 any of the @samp{.text}
+input sections.
+
+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, provided that the section is non-empty.  (Empty
+sections are ignored).
+
+@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
+
+To refine the sections that are included based on the section flags
+of an input section, INPUT_SECTION_FLAGS may be used.
+
+Here is a simple example for using Section header flags for ELF sections:
+
+@smallexample
+@group
+SECTIONS @{
+  .text : @{ INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) @}
+  .text2 :  @{ INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) @}
+@}
+@end group
+@end smallexample
+
+In this example, the output section @samp{.text} will be comprised of any
+input section matching the name *(.text) whose section header flags
+@code{SHF_MERGE} and @code{SHF_STRINGS} are set.  The output section
+@samp{.text2} will be comprised of any input section matching the name *(.text)
+whose section header flag @code{SHF_WRITE} is clear.
+
+You can also specify files within archives by writing a pattern
+matching the archive, a colon, then the pattern matching the file,
+with no whitespace around the colon.
+
+@table @samp
+@item archive:file
+matches file within archive
+@item archive:
+matches the whole archive
+@item :file
+matches file but not one in an archive
+@end table
+
+Either one or both of @samp{archive} and @samp{file} can contain shell
+wildcards.  On DOS based file systems, the linker will assume that a
+single letter followed by a colon is a drive specifier, so
+@samp{c:myfile.o} is a simple file specification, not @samp{myfile.o}
+within an archive called @samp{c}.  @samp{archive:file} filespecs may
+also be used within an @code{EXCLUDE_FILE} list, but may not appear in
+other linker script contexts.  For instance, you cannot extract a file
+from an archive by using @samp{archive:file} in an @code{INPUT}
+command.
+
+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 is not an @samp{archive:file} specifier
+and 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_BY_NAME
+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_BY_NAME} keyword, which appears before a wildcard
+pattern in parentheses (e.g., @code{SORT_BY_NAME(.text*)}).  When the
+@code{SORT_BY_NAME} keyword is used, the linker will sort the files or sections
+into ascending order by name before placing them in the output file.
+
+@cindex SORT_BY_ALIGNMENT
+@code{SORT_BY_ALIGNMENT} is very similar to @code{SORT_BY_NAME}. The
+difference is @code{SORT_BY_ALIGNMENT} will sort sections into
+descending order by alignment before placing them in the output file.
+Larger alignments are placed before smaller alignments in order to
+reduce the amount of padding necessary.
+
+@cindex SORT_BY_INIT_PRIORITY
+@code{SORT_BY_INIT_PRIORITY} is very similar to @code{SORT_BY_NAME}. The
+difference is @code{SORT_BY_INIT_PRIORITY} will sort sections into
+ascending order by numerical value of the GCC init_priority attribute
+encoded in the section name before placing them in the output file.
+
+@cindex SORT
+@code{SORT} is an alias for @code{SORT_BY_NAME}.
+
+When there are nested section sorting commands in linker script, there
+can be at most 1 level of nesting for section sorting commands.
+
+@enumerate
+@item
+@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
+It will sort the input sections by name first, then by alignment if two
+sections have the same name.
+@item
+@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
+It will sort the input sections by alignment first, then by name if two
+sections have the same alignment.
+@item
+@code{SORT_BY_NAME} (@code{SORT_BY_NAME} (wildcard section pattern)) is
+treated the same as @code{SORT_BY_NAME} (wildcard section pattern).
+@item
+@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern))
+is treated the same as @code{SORT_BY_ALIGNMENT} (wildcard section pattern).
+@item
+All other nested section sorting commands are invalid.
+@end enumerate
+
+When both command line section sorting option and linker script
+section sorting command are used, section sorting command always
+takes precedence over the command line option.
+
+If the section sorting command in linker script isn't nested, the
+command line option will make the section sorting command to be
+treated as nested sorting command.
+
+@enumerate
+@item
+@code{SORT_BY_NAME} (wildcard section pattern ) with
+@option{--sort-sections alignment} is equivalent to
+@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
+@item
+@code{SORT_BY_ALIGNMENT} (wildcard section pattern) with
+@option{--sort-section name} is equivalent to
+@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
+@end enumerate
+
+If the section sorting command in linker script is nested, the
+command line option will be ignored.
+
+@cindex SORT_NONE
+@code{SORT_NONE} disables section sorting by ignoring the command line
+section sorting option.
+
+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_BY_NAME(*)(.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)
+    @}
+@end group
+@group
+  outputb :
+    @{
+    foo.o (.input2)
+    foo1.o (.input1)
+    @}
+@end group
+@group
+  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{__CTOR_END__}} marks the end.
+Similarly, @w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_END__}} mark
+the start and end of the global destructors.  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_BY_NAME(CONSTRUCTORS)} instead.  When using the
+@code{.ctors} and @code{.dtors} sections, use @samp{*(SORT_BY_NAME(.ctors))} and
+@samp{*(SORT_BY_NAME(.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 normally create output sections with no 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, and if the input
+sections are not all empty.  Other link script directives that allocate
+space in an output section will also create the output section.  So
+too will assignments to dot even if the assignment does not create
+space, except for @samp{. = 0}, @samp{. = . + 0}, @samp{. = sym},
+@samp{. = . + sym} and @samp{. = ALIGN (. != 0, expr, 1)} when
+@samp{sym} is an absolute symbol of value 0 defined in the script.
+This allows you to force output of an empty section with @samp{. = .}.
+
+The linker will ignore address assignments (@pxref{Output Section Address})
+on discarded output sections, except when the linker script defines
+symbols in the output section.  In that case the linker will obey
+the address assignments, possibly advancing dot even though the
+section is discarded.
+
+@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})]
+  [ALIGN(@var{section_align})]
+  [SUBALIGN(@var{subsection_align})]
+  [@var{constraint}]
+  @{
+    @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
+* Forced Output Alignment::	Forced Output Alignment
+* Forced Input Alignment::	Forced Input Alignment
+* Output Section Constraint::   Output section constraint
+* 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.
+@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 virtual address is specified by the
+@pxref{Output Section Address} described earlier.  The load address is
+specified by the @code{AT} or @code{AT>} keywords.  Specifying a load
+address is optional.
+
+The @code{AT} keyword takes an expression as an argument.  This
+specifies the exact load address of the section.  The @code{AT>} keyword
+takes the name of a memory region as an argument.  @xref{MEMORY}.  The
+load address of the section is set to the next free address in the
+region, aligned to the section's alignment requirements.
+
+If neither @code{AT} nor @code{AT>} is specified for an allocatable
+section, the linker will use the following heuristic to determine the
+load address:
+
+@itemize @bullet
+@item
+If the section has a specific VMA address, then this is used as
+the LMA address as well.
+
+@item
+If the section is not allocatable then its LMA is set to its VMA.
+
+@item
+Otherwise if a memory region can be found that is compatible
+with the current section, and this region contains at least one
+section, then the LMA is set so the difference between the
+VMA and LMA is the same as the difference between the VMA and LMA of
+the last section in the located region.
+
+@item
+If no memory regions have been declared then a default region
+that covers the entire address space is used in the previous step.
+
+@item
+If no suitable region could be found, or there was no previous
+section then the LMA is set equal to the VMA.
+@end itemize
+
+@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 Forced Output Alignment
+@subsubsection Forced Output Alignment
+@kindex ALIGN(@var{section_align})
+@cindex forcing output section alignment
+@cindex output section alignment
+You can increase an output section's alignment by using ALIGN.  As an
+alternative you can enforce that the difference between the VMA and LMA remains
+intact throughout this output section with the ALIGN_WITH_INPUT attribute.
+
+@node Forced Input Alignment
+@subsubsection Forced Input Alignment
+@kindex SUBALIGN(@var{subsection_align})
+@cindex forcing input section alignment
+@cindex input section alignment
+You can force input section alignment within an output section by using
+SUBALIGN.  The value specified overrides any alignment given by input
+sections, whether larger or smaller.
+
+@node Output Section Constraint
+@subsubsection Output Section Constraint
+@kindex ONLY_IF_RO
+@kindex ONLY_IF_RW
+@cindex constraints on output sections
+You can specify that an output section should only be created if all
+of its input sections are read-only or all of its input sections are
+read-write by using the keyword @code{ONLY_IF_RO} and
+@code{ONLY_IF_RW} respectively.
+
+@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} construct (@pxref{SECTIONS}),
+except that no addresses and no memory regions may be defined for
+sections within an @code{OVERLAY}.
+
+The comma at the end may be required if a @var{fill} is used and
+the next @var{sections-command} looks like a continuation of the expression.
+
+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 are 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
+provides 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 if referenced: @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) @}
+  PROVIDE (__load_start_text0 = LOADADDR (.text0));
+  PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
+  .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
+  PROVIDE (__load_start_text1 = LOADADDR (.text1));
+  PROVIDE (__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 many uses of the @code{MEMORY} command,
+however, all memory blocks defined are treated as if they were
+specified inside a single @code{MEMORY} command.  The syntax for
+@code{MEMORY} 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 within the @code{MEMORY} command.  However you can
+add later alias names to existing memory regions with the @ref{REGION_ALIAS}
+command.
+
+@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 attributes that follow
+@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 numerical expression for the start address of
+the memory region.  The expression must evaluate to a constant and it
+cannot involve any 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
+be numerical only and must evaluate to a constant.  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.
+
+It is possible to access the origin and length of a memory in an
+expression via the @code{ORIGIN(@var{memory})} and
+@code{LENGTH(@var{memory})} functions:
+
+@smallexample
+@group
+  _fstack = ORIGIN(ram) + LENGTH(ram) - 4;
+@end group
+@end smallexample
+
+@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.  The headers are processed in order and it
+is usual for them to map to sections in ascending load address order.
+
+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 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.  If applied to a loadable
+segment (@code{PT_LOAD}), all prior loadable segments must have one of
+these keywords.
+
+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;
+	 extern "C++" @{
+		 ns::*;
+		 "f(int, double)";
+	 @};
+@} 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'').
+However, if you specify the symbol name inside double quotes, then the
+name is treated as literal, rather than as a glob pattern.
+
+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.  Note that it's slightly crazy to use
+wildcards in a global spec except on the last version node.  Global
+wildcards elsewhere run the risk of accidentally adding symbols to the
+set exported for an old version.  That's wrong since older versions
+ought to have a fixed set of symbols.
+
+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 omitted, 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. A @samp{.symver} directive
+takes precedence over a version script.
+
+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}.  The default
+@samp{lang} is @samp{C}.
+
+Demangled names may contains spaces and other special characters.  As
+described above, you can use a glob pattern to match demangled names,
+or you can use a double-quoted string to match the string exactly.  In
+the latter case, be aware that minor differences (such as differing
+whitespace) between the version script and the demangler output will
+cause a mismatch.  As the exact string generated by the demangler
+might change in the future, even if the mangled name does not, you
+should check that all of your version directives are behaving as you
+expect when you upgrade.
+
+@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
+* Symbolic Constants::          Symbolic constants
+* Symbols::			Symbol Names
+* Orphan Sections::		Orphan Sections
+* 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.  Alternatively the linker accepts suffixes of @samp{h} or
+@samp{H} for hexadecimal, @samp{o} or @samp{O} for octal, @samp{b} or
+@samp{B} for binary and @samp{d} or @samp{D} for decimal.  Any integer
+value without a prefix or a suffix is considered 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
+@ifnottex
+@c END TEXI2ROFF-KILL
+@code{1024} or @code{1024*1024}
+@c TEXI2ROFF-KILL
+@end ifnottex
+@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;
+_fourk_4 = 10000o;
+@end smallexample
+
+Note - the @code{K} and @code{M} suffixes cannot be used in
+conjunction with the base suffixes mentioned above.
+
+@node Symbolic Constants
+@subsection Symbolic Constants
+@cindex symbolic constants
+@kindex CONSTANT
+It is possible to refer to target specific constants via the use of
+the @code{CONSTANT(@var{name})} operator, where @var{name} is one of:
+
+@table @code
+@item MAXPAGESIZE
+@kindex MAXPAGESIZE
+The target's maximum page size.
+
+@item COMMONPAGESIZE
+@kindex COMMONPAGESIZE
+The target's default page size.
+@end table
+
+So for example:
+
+@smallexample
+  .text ALIGN (CONSTANT (MAXPAGESIZE)) : @{ *(.text) @}
+@end smallexample
+
+will create a text section aligned to the largest page boundary
+supported by the target.
+
+@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 Orphan Sections
+@subsection Orphan Sections
+@cindex orphan
+Orphan sections are sections present in the input files which
+are not explicitly placed into the output file by the linker
+script.  The linker will still copy these sections into the
+output file, but it has to guess as to where they should be
+placed.  The linker uses a simple heuristic to do this.  It
+attempts to place orphan sections after non-orphan sections of the
+same attribute, such as code vs data, loadable vs non-loadable, etc.
+If there is not enough room to do this then it places
+at the end of the file.
+
+For ELF targets, the attribute of the section includes section type as
+well as section flag.
+
+The command line options @samp{--orphan-handling} and @samp{--unique}
+(@pxref{Options,,Command Line Options}) can be used to control which
+output sections an orphan is placed in.
+
+If an orphaned section's name is representable as a C identifier then
+the linker will automatically @pxref{PROVIDE} two symbols:
+__start_SECNAME and __stop_SECNAME, where SECNAME is the name of the
+section.  These indicate the start address and end address of the
+orphaned section respectively.  Note: most section names are not
+representable as C identifiers because they contain a @samp{.}
+character.
+
+@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 not be moved backwards inside an output section,
+and may not be moved backwards outside of an output section if so
+doing creates areas with overlapping LMAs.
+
+@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, whose 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.
+
+@cindex dot outside sections
+Setting symbols to the value of the location counter outside of an
+output section statement can result in unexpected values if the linker
+needs to place orphan sections.  For example, given the following:
+
+@smallexample
+SECTIONS
+@{
+    start_of_text = . ;
+    .text: @{ *(.text) @}
+    end_of_text = . ;
+
+    start_of_data = . ;
+    .data: @{ *(.data) @}
+    end_of_data = . ;
+@}
+@end smallexample
+
+If the linker needs to place some input section, e.g. @code{.rodata},
+not mentioned in the script, it might choose to place that section
+between @code{.text} and @code{.data}.  You might think the linker
+should place @code{.rodata} on the blank line in the above script, but
+blank lines are of no particular significance to the linker.  As well,
+the linker doesn't associate the above symbol names with their
+sections.  Instead, it assumes that all assignments or other
+statements belong to the previous output section, except for the
+special case of an assignment to @code{.}.  I.e., the linker will
+place the orphan @code{.rodata} section as if the script was written
+as follows:
+
+@smallexample
+SECTIONS
+@{
+    start_of_text = . ;
+    .text: @{ *(.text) @}
+    end_of_text = . ;
+
+    start_of_data = . ;
+    .rodata: @{ *(.rodata) @}
+    .data: @{ *(.data) @}
+    end_of_data = . ;
+@}
+@end smallexample
+
+This may or may not be the script author's intention for the value of
+@code{start_of_data}.  One way to influence the orphan section
+placement is to assign the location counter to itself, as the linker
+assumes that an assignment to @code{.} is setting the start address of
+a following output section and thus should be grouped with that
+section.  So you could write:
+
+@smallexample
+SECTIONS
+@{
+    start_of_text = . ;
+    .text: @{ *(.text) @}
+    end_of_text = . ;
+
+    . = . ;
+    start_of_data = . ;
+    .data: @{ *(.data) @}
+    end_of_data = . ;
+@}
+@end smallexample
+
+Now, the orphan @code{.rodata} section will be placed between
+@code{end_of_text} and @code{start_of_data}.
+
+@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
+@ifnottex
+@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 ifnottex
+@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
+Addresses and symbols may be section relative, or absolute.  A section
+relative symbol is relocatable.  If you request relocatable output
+using the @samp{-r} option, a further link operation may change the
+value of a section relative symbol.  On the other hand, an absolute
+symbol will retain the same value throughout any further link
+operations.
+
+Some terms in linker expressions are addresses.  This is true of
+section relative symbols and for builtin functions that return an
+address, such as @code{ADDR}, @code{LOADADDR}, @code{ORIGIN} and
+@code{SEGMENT_START}.  Other terms are simply numbers, or are builtin
+functions that return a non-address value, such as @code{LENGTH}.
+One complication is that unless you set @code{LD_FEATURE ("SANE_EXPR")}
+(@pxref{Miscellaneous Commands}), numbers and absolute symbols are treated
+differently depending on their location, for compatibility with older
+versions of @code{ld}.  Expressions appearing outside an output
+section definition treat all numbers as absolute addresses.
+Expressions appearing inside an output section definition treat
+absolute symbols as numbers.  If @code{LD_FEATURE ("SANE_EXPR")} is
+given, then absolute symbols and numbers are simply treated as numbers
+everywhere.
+
+In the following simple example,
+
+@smallexample
+@group
+SECTIONS
+  @{
+    . = 0x100;
+    __executable_start = 0x100;
+    .data :
+    @{
+      . = 0x10;
+      __data_start = 0x10;
+      *(.data)
+    @}
+    @dots{}
+  @}
+@end group
+@end smallexample
+
+both @code{.} and @code{__executable_start} are set to the absolute
+address 0x100 in the first two assignments, then both @code{.} and
+@code{__data_start} are set to 0x10 relative to the @code{.data}
+section in the second two assignments.
+
+For expressions involving numbers, relative addresses and absolute
+addresses, ld follows these rules to evaluate terms:
+
+@itemize @bullet
+@item
+Unary operations on an absolute address or number, and binary
+operations on two absolute addresses or two numbers, or between one
+absolute address and a number, apply the operator to the value(s).
+@item
+Unary operations on a relative address, and binary operations on two
+relative addresses in the same section or between one relative address
+and a number, apply the operator to the offset part of the address(es).
+@item
+Other binary operations, that is, between two relative addresses not
+in the same section, or between a relative address and an absolute
+address, first convert any non-absolute term to an absolute address
+before applying the operator.
+@end itemize
+
+The result section of each sub-expression is as follows:
+
+@itemize @bullet
+@item
+An operation involving only numbers results in a number.
+@item
+The result of comparisons, @samp{&&} and @samp{||} is also a number.
+@item
+The result of other binary arithmetic and logical operations on two
+relative addresses in the same section or two absolute addresses
+(after above conversions) is also a number.
+@item
+The result of other operations on relative addresses or one
+relative address and a number, is a relative address in the same
+section as the relative operand(s).
+@item
+The result of other operations on absolute addresses (after above
+conversions) is an absolute address.
+@end itemize
+
+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.
+
+Using @code{LOADADDR} also forces an expression absolute, since this
+particular builtin function returns an absolute address.
+
+@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 address (VMA) of the named @var{section}.  Your
+script must previously have defined the location of that section.  In
+the following example, @code{start_of_output_1}, @code{symbol_1} and
+@code{symbol_2} are assigned equivalent values, except that
+@code{symbol_1} will be relative to the @code{.output1} section while
+the other two will be absolute:
+@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{align})
+@itemx ALIGN(@var{exp},@var{align})
+@kindex ALIGN(@var{align})
+@kindex ALIGN(@var{exp},@var{align})
+@cindex round up location counter
+@cindex align location counter
+@cindex round up expression
+@cindex align expression
+Return the location counter (@code{.}) or arbitrary expression aligned
+to the next @var{align} boundary.  The single operand @code{ALIGN}
+doesn't change the value of the location counter---it just does
+arithmetic on it.  The two operand @code{ALIGN} allows an arbitrary
+expression to be aligned upwards (@code{ALIGN(@var{align})} is
+equivalent to @code{ALIGN(ABSOLUTE(.), @var{align})}).
+
+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 ALIGNOF(@var{section})
+@kindex ALIGNOF(@var{section})
+@cindex section alignment
+Return the alignment 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,
+the alignment of the @code{.output} section is stored as the first
+value in that section.
+@smallexample
+@group
+SECTIONS@{ @dots{}
+  .output @{
+    LONG (ALIGNOF (.output))
+    @dots{}
+    @}
+@dots{} @}
+@end group
+@end smallexample
+
+@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{commonpagesize} - 1) & (@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 DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
+@kindex DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
+This defines the end of the @code{PT_GNU_RELRO} segment when
+@samp{-z relro} option is used.
+When @samp{-z relro} option is not present, @code{DATA_SEGMENT_RELRO_END}
+does nothing, otherwise @code{DATA_SEGMENT_ALIGN} is padded so that
+@var{exp} + @var{offset} is aligned to the most commonly used page
+boundary for particular target.  If present in the linker script,
+it must always come in between @code{DATA_SEGMENT_ALIGN} and
+@code{DATA_SEGMENT_END}.  Evaluates to the second argument plus any
+padding needed at the end of the @code{PT_GNU_RELRO} segment due to
+section alignment.
+
+@smallexample
+  . = DATA_SEGMENT_RELRO_END(24, .);
+@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 before the statement using DEFINED in the script, 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 LENGTH(@var{memory})
+@kindex LENGTH(@var{memory})
+Return the length of the memory region named @var{memory}.
+
+@item LOADADDR(@var{section})
+@kindex LOADADDR(@var{section})
+@cindex section load address in expression
+Return the absolute LMA of the named @var{section}.  (@pxref{Output
+Section LMA}).
+
+@item LOG2CEIL(@var{exp})
+@kindex LOG2CEIL(@var{exp})
+Return the binary logarithm of @var{exp} rounded towards infinity.
+@code{LOG2CEIL(0)} returns 0.
+
+@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 ORIGIN(@var{memory})
+@kindex ORIGIN(@var{memory})
+Return the origin of the memory region named @var{memory}.
+
+@item SEGMENT_START(@var{segment}, @var{default})
+@kindex SEGMENT_START(@var{segment}, @var{default})
+Return the base address of the named @var{segment}.  If an explicit
+value has already been given for this segment (with a command-line
+@samp{-T} option) then that value will be returned otherwise the value
+will be @var{default}.  At present, the @samp{-T} command-line option
+can only be used to set the base address for the ``text'', ``data'', and
+``bss'' sections, but you can use @code{SEGMENT_START} with any segment
+name.
+
+@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
+@ifset H8300
+* H8/300::                      @command{ld} and the H8/300
+@end ifset
+@ifset I960
+* i960::                        @command{ld} and the Intel 960 family
+@end ifset
+@ifset M68HC11
+* M68HC11/68HC12::		@code{ld} and the Motorola 68HC11 and 68HC12 families
+@end ifset
+@ifset ARM
+* ARM::				@command{ld} and the ARM family
+@end ifset
+@ifset HPPA
+* HPPA ELF32::                  @command{ld} and HPPA 32-bit ELF
+@end ifset
+@ifset M68K
+* M68K::			@command{ld} and the Motorola 68K family
+@end ifset
+@ifset MIPS
+* MIPS::			@command{ld} and the MIPS family
+@end ifset
+@ifset MMIX
+* MMIX::			@command{ld} and MMIX
+@end ifset
+@ifset MSP430
+* MSP430::			@command{ld} and MSP430
+@end ifset
+@ifset NDS32
+* NDS32::			@command{ld} and NDS32
+@end ifset
+@ifset NIOSII
+* Nios II::			@command{ld} and the Altera Nios II
+@end ifset
+@ifset POWERPC
+* PowerPC ELF32::		@command{ld} and PowerPC 32-bit ELF Support
+@end ifset
+@ifset POWERPC64
+* PowerPC64 ELF64::		@command{ld} and PowerPC64 64-bit ELF Support
+@end ifset
+@ifset SPU
+* SPU ELF::			@command{ld} and SPU ELF Support
+@end ifset
+@ifset TICOFF
+* TI COFF::                     @command{ld} and TI COFF
+@end ifset
+@ifset WIN32
+* WIN32::                       @command{ld} and WIN32 (cygwin/mingw)
+@end ifset
+@ifset XTENSA
+* Xtensa::                      @command{ld} and Xtensa Processors
+@end ifset
+@end menu
+@end ifset
+
+@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? -> mov.b only, at least on H8, H8H, H8S
+@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).
+
+@command{ld} finds all @code{mov} instructions which use the register
+indirect with 32-bit displacement addressing mode, but use a small
+displacement inside 16-bit displacement range, and changes them to use
+the 16-bit displacement form.  (That is: the linker turns @samp{mov.b
+@code{@@}@var{d}:32,ERx} into @samp{mov.b @code{@@}@var{d}:16,ERx}
+whenever the displacement @var{d} is in the 16 bit signed integer
+range. Only implemented in ELF-format ld).
+
+@item bit manipulation instructions
+@command{ld} finds all bit manipulation instructions like @code{band, bclr,
+biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor}
+which use 32 bit and 16 bit absolute address form, but refer to the top
+page of memory, and changes them to use the 8 bit address form.
+(That is: the linker turns @samp{bset #xx:3,@code{@@}@var{aa}:32} into
+@samp{bset #xx:3,@code{@@}@var{aa}:8} whenever the address @var{aa} is in
+the top page of memory).
+
+@item system control instructions
+@command{ld} finds all @code{ldc.w, stc.w} instructions which use the
+32 bit absolute address form, but refer to the top page of memory, and
+changes them to use 16 bit address form.
+(That is: the linker turns @samp{ldc.w @code{@@}@var{aa}:32,ccr} into
+@samp{ldc.w @code{@@}@var{aa}:16,ccr} whenever the address @var{aa} is in
+the top page of memory).
+@end table
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifclear GENERIC
+@ifset Renesas
+@c This stuff is pointless to say unless you're especially concerned
+@c with Renesas chips; don't enable it for generic case, please.
+@node Renesas
+@chapter @command{ld} and Other Renesas Chips
+
+@command{ld} also supports the Renesas (formerly Hitachi) H8/300H,
+H8/500, and SH chips.  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
+
+@ifset ARM
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@ifset M68HC11
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node M68HC11/68HC12
+@section @command{ld} and the Motorola 68HC11 and 68HC12 families
+
+@cindex M68HC11 and 68HC12 support
+
+@subsection Linker Relaxation
+
+For the Motorola 68HC11, @command{ld} can perform these global
+optimizations when you specify the @samp{--relax} command-line option.
+
+@table @emph
+@cindex relaxing on M68HC11
+@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.
+
+@command{ld} also looks at all 16-bit extended addressing modes and
+transforms them in a direct addressing mode when the address is in
+page 0 (between 0 and 0x0ff).
+
+@item relaxing gcc instruction group
+When @command{gcc} is called with @option{-mrelax}, it can emit group
+of instructions that the linker can optimize to use a 68HC11 direct
+addressing mode. These instructions consists of @code{bclr} or
+@code{bset} instructions.
+
+@end table
+
+@subsection Trampoline Generation
+
+@cindex trampoline generation on M68HC11
+@cindex trampoline generation on M68HC12
+For 68HC11 and 68HC12, @command{ld} can generate trampoline code to
+call a far function using a normal @code{jsr} instruction. The linker
+will also change the relocation to some far function to use the
+trampoline address instead of the function address. This is typically the
+case when a pointer to a function is taken. The pointer will in fact
+point to the function trampoline.
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@node ARM
+@section @command{ld} and the ARM family
+
+@cindex ARM interworking support
+@kindex --support-old-code
+For the ARM, @command{ld} will generate code stubs to allow functions calls
+between 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.
+
+@cindex PE import table prefixing
+@kindex --use-nul-prefixed-import-tables
+The @samp{--use-nul-prefixed-import-tables} switch is specifying, that
+the import tables idata4 and idata5 have to be generated with a zero
+element prefix for import libraries. This is the old style to generate
+import tables. By default this option is turned off.
+
+@cindex BE8
+@kindex --be8
+The @samp{--be8} switch instructs @command{ld} to generate BE8 format
+executables.  This option is only valid when linking big-endian
+objects - ie ones which have been assembled with the @option{-EB}
+option.  The resulting image will contain big-endian data and
+little-endian code.
+
+@cindex TARGET1
+@kindex --target1-rel
+@kindex --target1-abs
+The @samp{R_ARM_TARGET1} relocation is typically used for entries in the
+@samp{.init_array} section.  It is interpreted as either @samp{R_ARM_REL32}
+or @samp{R_ARM_ABS32}, depending on the target.  The @samp{--target1-rel}
+and @samp{--target1-abs} switches override the default.
+
+@cindex TARGET2
+@kindex --target2=@var{type}
+The @samp{--target2=type} switch overrides the default definition of the
+@samp{R_ARM_TARGET2} relocation.  Valid values for @samp{type}, their
+meanings, and target defaults are as follows:
+@table @samp
+@item rel
+@samp{R_ARM_REL32} (arm*-*-elf, arm*-*-eabi)
+@item abs
+@samp{R_ARM_ABS32} (arm*-*-symbianelf)
+@item got-rel
+@samp{R_ARM_GOT_PREL} (arm*-*-linux, arm*-*-*bsd)
+@end table
+
+@cindex FIX_V4BX
+@kindex --fix-v4bx
+The @samp{R_ARM_V4BX} relocation (defined by the ARM AAELF
+specification) enables objects compiled for the ARMv4 architecture to be
+interworking-safe when linked with other objects compiled for ARMv4t, but
+also allows pure ARMv4 binaries to be built from the same ARMv4 objects.
+
+In the latter case, the switch @option{--fix-v4bx} must be passed to the
+linker, which causes v4t @code{BX rM} instructions to be rewritten as
+@code{MOV PC,rM}, since v4 processors do not have a @code{BX} instruction.
+
+In the former case, the switch should not be used, and @samp{R_ARM_V4BX}
+relocations are ignored.
+
+@cindex FIX_V4BX_INTERWORKING
+@kindex --fix-v4bx-interworking
+Replace @code{BX rM} instructions identified by @samp{R_ARM_V4BX}
+relocations with a branch to the following veneer:
+
+@smallexample
+TST rM, #1
+MOVEQ PC, rM
+BX Rn
+@end smallexample
+
+This allows generation of libraries/applications that work on ARMv4 cores
+and are still interworking safe.  Note that the above veneer clobbers the
+condition flags, so may cause incorrect program behavior in rare cases.
+
+@cindex USE_BLX
+@kindex --use-blx
+The @samp{--use-blx} switch enables the linker to use ARM/Thumb
+BLX instructions (available on ARMv5t and above) in various
+situations. Currently it is used to perform calls via the PLT from Thumb
+code using BLX rather than using BX and a mode-switching stub before
+each PLT entry. This should lead to such calls executing slightly faster.
+
+This option is enabled implicitly for SymbianOS, so there is no need to
+specify it if you are using that target.
+
+@cindex VFP11_DENORM_FIX
+@kindex --vfp11-denorm-fix
+The @samp{--vfp11-denorm-fix} switch enables a link-time workaround for a
+bug in certain VFP11 coprocessor hardware, which sometimes allows
+instructions with denorm operands (which must be handled by support code)
+to have those operands overwritten by subsequent instructions before
+the support code can read the intended values.
+
+The bug may be avoided in scalar mode if you allow at least one
+intervening instruction between a VFP11 instruction which uses a register
+and another instruction which writes to the same register, or at least two
+intervening instructions if vector mode is in use. The bug only affects
+full-compliance floating-point mode: you do not need this workaround if
+you are using "runfast" mode. Please contact ARM for further details.
+
+If you know you are using buggy VFP11 hardware, you can
+enable this workaround by specifying the linker option
+@samp{--vfp-denorm-fix=scalar} if you are using the VFP11 scalar
+mode only, or @samp{--vfp-denorm-fix=vector} if you are using
+vector mode (the latter also works for scalar code). The default is
+@samp{--vfp-denorm-fix=none}.
+
+If the workaround is enabled, instructions are scanned for
+potentially-troublesome sequences, and a veneer is created for each
+such sequence which may trigger the erratum. The veneer consists of the
+first instruction of the sequence and a branch back to the subsequent
+instruction. The original instruction is then replaced with a branch to
+the veneer. The extra cycles required to call and return from the veneer
+are sufficient to avoid the erratum in both the scalar and vector cases.
+
+@cindex ARM1176 erratum workaround
+@kindex --fix-arm1176
+@kindex --no-fix-arm1176
+The @samp{--fix-arm1176} switch enables a link-time workaround for an erratum
+in certain ARM1176 processors.  The workaround is enabled by default if you
+are targeting ARM v6 (excluding ARM v6T2) or earlier.  It can be disabled
+unconditionally by specifying @samp{--no-fix-arm1176}.
+
+Further information is available in the ``ARM1176JZ-S and ARM1176JZF-S
+Programmer Advice Notice'' available on the ARM documentation website at:
+http://infocenter.arm.com/.
+
+@cindex STM32L4xx erratum workaround
+@kindex --fix-stm32l4xx-629360
+
+The @samp{--fix-stm32l4xx-629360} switch enables a link-time
+workaround for a bug in the bus matrix / memory controller for some of
+the STM32 Cortex-M4 based products (STM32L4xx).  When accessing
+off-chip memory via the affected bus for bus reads of 9 words or more,
+the bus can generate corrupt data and/or abort.  These are only
+core-initiated accesses (not DMA), and might affect any access:
+integer loads such as LDM, POP and floating-point loads such as VLDM,
+VPOP.  Stores are not affected.
+
+The bug can be avoided by splitting memory accesses into the
+necessary chunks to keep bus reads below 8 words.
+
+The workaround is not enabled by default, this is equivalent to use
+@samp{--fix-stm32l4xx-629360=none}.  If you know you are using buggy
+STM32L4xx hardware, you can enable the workaround by specifying the
+linker option @samp{--fix-stm32l4xx-629360}, or the equivalent
+@samp{--fix-stm32l4xx-629360=default}.
+
+If the workaround is enabled, instructions are scanned for
+potentially-troublesome sequences, and a veneer is created for each
+such sequence which may trigger the erratum.  The veneer consists in a
+replacement sequence emulating the behaviour of the original one and a
+branch back to the subsequent instruction.  The original instruction is
+then replaced with a branch to the veneer.
+
+The workaround does not always preserve the memory access order for
+the LDMDB instruction, when the instruction loads the PC.
+
+The workaround is not able to handle problematic instructions when
+they are in the middle of an IT block, since a branch is not allowed
+there.  In that case, the linker reports a warning and no replacement
+occurs.
+
+The workaround is not able to replace problematic instructions with a
+PC-relative branch instruction if the @samp{.text} section is too
+large.  In that case, when the branch that replaces the original code
+cannot be encoded, the linker reports a warning and no replacement
+occurs.
+
+@cindex NO_ENUM_SIZE_WARNING
+@kindex --no-enum-size-warning
+The @option{--no-enum-size-warning} switch prevents the linker from
+warning when linking object files that specify incompatible EABI
+enumeration size attributes.  For example, with this switch enabled,
+linking of an object file using 32-bit enumeration values with another
+using enumeration values fitted into the smallest possible space will
+not be diagnosed.
+
+@cindex NO_WCHAR_SIZE_WARNING
+@kindex --no-wchar-size-warning
+The @option{--no-wchar-size-warning} switch prevents the linker from
+warning when linking object files that specify incompatible EABI
+@code{wchar_t} size attributes.  For example, with this switch enabled,
+linking of an object file using 32-bit @code{wchar_t} values with another
+using 16-bit @code{wchar_t} values will not be diagnosed.
+
+@cindex PIC_VENEER
+@kindex --pic-veneer
+The @samp{--pic-veneer} switch makes the linker use PIC sequences for
+ARM/Thumb interworking veneers, even if the rest of the binary
+is not PIC.  This avoids problems on uClinux targets where
+@samp{--emit-relocs} is used to generate relocatable binaries.
+
+@cindex STUB_GROUP_SIZE
+@kindex --stub-group-size=@var{N}
+The linker will automatically generate and insert small sequences of
+code into a linked ARM ELF executable whenever an attempt is made to
+perform a function call to a symbol that is too far away.  The
+placement of these sequences of instructions - called stubs - is
+controlled by the command line option @option{--stub-group-size=N}.
+The placement is important because a poor choice can create a need for
+duplicate stubs, increasing the code size.  The linker will try to
+group stubs together in order to reduce interruptions to the flow of
+code, but it needs guidance as to how big these groups should be and
+where they should be placed.
+
+The value of @samp{N}, the parameter to the
+@option{--stub-group-size=} option controls where the stub groups are
+placed.  If it is negative then all stubs are placed after the first
+branch that needs them.  If it is positive then the stubs can be
+placed either before or after the branches that need them.  If the
+value of @samp{N} is 1 (either +1 or -1) then the linker will choose
+exactly where to place groups of stubs, using its built in heuristics.
+A value of @samp{N} greater than 1 (or smaller than -1) tells the
+linker that a single group of stubs can service at most @samp{N} bytes
+from the input sections.
+
+The default, if @option{--stub-group-size=} is not specified, is
+@samp{N = +1}.
+
+Farcalls stubs insertion is fully supported for the ARM-EABI target
+only, because it relies on object files properties not present
+otherwise.
+
+@cindex Cortex-A8 erratum workaround
+@kindex --fix-cortex-a8
+@kindex --no-fix-cortex-a8
+The @samp{--fix-cortex-a8} switch enables a link-time workaround for an erratum in certain Cortex-A8 processors.  The workaround is enabled by default if you are targeting the ARM v7-A architecture profile.  It can be enabled otherwise by specifying @samp{--fix-cortex-a8}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a8}.
+
+The erratum only affects Thumb-2 code.  Please contact ARM for further details.
+
+@cindex Cortex-A53 erratum 835769 workaround
+@kindex --fix-cortex-a53-835769
+@kindex --no-fix-cortex-a53-835769
+The @samp{--fix-cortex-a53-835769} switch enables a link-time workaround for erratum 835769 present on certain early revisions of Cortex-A53 processors.  The workaround is disabled by default.  It can be enabled by specifying @samp{--fix-cortex-a53-835769}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a53-835769}.
+
+Please contact ARM for further details.
+
+@kindex --merge-exidx-entries
+@kindex --no-merge-exidx-entries
+@cindex Merging exidx entries
+The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent exidx entries in debuginfo.
+
+@kindex --long-plt
+@cindex 32-bit PLT entries
+The @samp{--long-plt} option enables the use of 16 byte PLT entries
+which support up to 4Gb of code.  The default is to use 12 byte PLT
+entries which only support 512Mb of code.
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset HPPA
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@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.
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset M68K
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node M68K
+@section @command{ld} and the Motorola 68K family
+
+@cindex Motorola 68K GOT generation
+@kindex --got=@var{type}
+The @samp{--got=@var{type}} option lets you choose the GOT generation scheme.
+The choices are @samp{single}, @samp{negative}, @samp{multigot} and
+@samp{target}.  When @samp{target} is selected the linker chooses
+the default GOT generation scheme for the current target.
+@samp{single} tells the linker to generate a single GOT with
+entries only at non-negative offsets.
+@samp{negative} instructs the linker to generate a single GOT with
+entries at both negative and positive offsets.  Not all environments
+support such GOTs.
+@samp{multigot} allows the linker to generate several GOTs in the
+output file.  All GOT references from a single input object
+file access the same GOT, but references from different input object
+files might access different GOTs.  Not all environments support such GOTs.
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset MIPS
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node MIPS
+@section @command{ld} and the MIPS family
+
+@cindex MIPS microMIPS instruction choice selection
+@kindex --insn32
+@kindex --no-insn32
+The @samp{--insn32} and @samp{--no-insn32} options control the choice of
+microMIPS instructions used in code generated by the linker, such as that
+in the PLT or lazy binding stubs, or in relaxation.  If @samp{--insn32} is
+used, then the linker only uses 32-bit instruction encodings.  By default
+or if @samp{--no-insn32} is used, all instruction encodings are used,
+including 16-bit ones where possible.
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset MMIX
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node MMIX
+@section @code{ld} and MMIX
+For MMIX, there is a 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.
+
+Global symbols with the prefix @code{__.MMIX.start.}, for example
+@code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special.
+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.
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset MSP430
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node  MSP430
+@section @code{ld} and MSP430
+For the MSP430 it is possible to select the MPU architecture.  The flag @samp{-m [mpu type]}
+will select an appropriate linker script for selected MPU type.  (To get a list of known MPUs
+just pass @samp{-m help} option to the linker).
+
+@cindex MSP430 extra sections
+The linker will recognize some extra sections which are MSP430 specific:
+
+@table @code
+@item @samp{.vectors}
+Defines a portion of ROM where interrupt vectors located.
+
+@item @samp{.bootloader}
+Defines the bootloader portion of the ROM (if applicable).  Any code
+in this section will be uploaded to the MPU.
+
+@item @samp{.infomem}
+Defines an information memory section (if applicable).  Any code in
+this section will be uploaded to the MPU.
+
+@item @samp{.infomemnobits}
+This is the same as the @samp{.infomem} section except that any code
+in this section will not be uploaded to the MPU.
+
+@item @samp{.noinit}
+Denotes a portion of RAM located above @samp{.bss} section.
+
+The last two sections are used by gcc.
+@end table
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset NDS32
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node NDS32
+@section @code{ld} and NDS32
+@kindex relaxing on NDS32
+For NDS32, there are some options to select relaxation behavior.  The linker
+relaxes objects according to these options.
+
+@table @code
+@item @samp{--m[no-]fp-as-gp}
+Disable/enable fp-as-gp relaxation.
+
+@item @samp{--mexport-symbols=FILE}
+Exporting symbols and their address into FILE as linker script.
+
+@item @samp{--m[no-]ex9}
+Disable/enable link-time EX9 relaxation.
+
+@item @samp{--mexport-ex9=FILE}
+Export the EX9 table after linking.
+
+@item @samp{--mimport-ex9=FILE}
+Import the Ex9 table for EX9 relaxation.
+
+@item @samp{--mupdate-ex9}
+Update the existing EX9 table.
+
+@item @samp{--mex9-limit=NUM}
+Maximum number of entries in the ex9 table.
+
+@item @samp{--mex9-loop-aware}
+Avoid generating the EX9 instruction inside the loop.
+
+@item @samp{--m[no-]ifc}
+Disable/enable the link-time IFC optimization.
+
+@item @samp{--mifc-loop-aware}
+Avoid generating the IFC instruction inside the loop.
+@end table
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset NIOSII
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node Nios II
+@section @command{ld} and the Altera Nios II
+@cindex Nios II call relaxation
+@kindex --relax on Nios II
+
+Call and immediate jump instructions on Nios II processors are limited to
+transferring control to addresses in the same 256MB memory segment,
+which may result in @command{ld} giving
+@samp{relocation truncated to fit} errors with very large programs.
+The command-line option @option{--relax} enables the generation of
+trampolines that can access the entire 32-bit address space for calls
+outside the normal @code{call} and @code{jmpi} address range.  These
+trampolines are inserted at section boundaries, so may not themselves
+be reachable if an input section and its associated call trampolines are
+larger than 256MB.
+
+The @option{--relax} option is enabled by default unless @option{-r}
+is also specified.  You can disable trampoline generation by using the
+@option{--no-relax} linker option.  You can also disable this optimization
+locally by using the @samp{set .noat} directive in assembly-language
+source files, as the linker-inserted trampolines use the @code{at}
+register as a temporary.
+
+Note that the linker @option{--relax} option is independent of assembler
+relaxation options, and that using the GNU assembler's @option{-relax-all}
+option interferes with the linker's more selective call instruction relaxation.
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset POWERPC
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node PowerPC ELF32
+@section @command{ld} and PowerPC 32-bit ELF Support
+@cindex PowerPC long branches
+@kindex --relax on PowerPC
+Branches on PowerPC processors are limited to a signed 26-bit
+displacement, which may result in @command{ld} giving
+@samp{relocation truncated to fit} errors with very large programs.
+@samp{--relax} enables the generation of trampolines that can access
+the entire 32-bit address space.  These trampolines are inserted at
+section boundaries, so may not themselves be reachable if an input
+section exceeds 33M in size.  You may combine @samp{-r} and
+@samp{--relax} to add trampolines in a partial link.  In that case
+both branches to undefined symbols and inter-section branches are also
+considered potentially out of range, and trampolines inserted.
+
+@cindex PowerPC ELF32 options
+@table @option
+@cindex PowerPC PLT
+@kindex --bss-plt
+@item --bss-plt
+Current PowerPC GCC accepts a @samp{-msecure-plt} option that
+generates code capable of using a newer PLT and GOT layout that has
+the security advantage of no executable section ever needing to be
+writable and no writable section ever being executable.  PowerPC
+@command{ld} will generate this layout, including stubs to access the
+PLT, if all input files (including startup and static libraries) were
+compiled with @samp{-msecure-plt}.  @samp{--bss-plt} forces the old
+BSS PLT (and GOT layout) which can give slightly better performance.
+
+@kindex --secure-plt
+@item --secure-plt
+@command{ld} will use the new PLT and GOT layout if it is linking new
+@samp{-fpic} or @samp{-fPIC} code, but does not do so automatically
+when linking non-PIC code.  This option requests the new PLT and GOT
+layout.  A warning will be given if some object file requires the old
+style BSS PLT.
+
+@cindex PowerPC GOT
+@kindex --sdata-got
+@item --sdata-got
+The new secure PLT and GOT are placed differently relative to other
+sections compared to older BSS PLT and GOT placement.  The location of
+@code{.plt} must change because the new secure PLT is an initialized
+section while the old PLT is uninitialized.  The reason for the
+@code{.got} change is more subtle:  The new placement allows
+@code{.got} to be read-only in applications linked with
+@samp{-z relro -z now}.  However, this placement means that
+@code{.sdata} cannot always be used in shared libraries, because the
+PowerPC ABI accesses @code{.sdata} in shared libraries from the GOT
+pointer.  @samp{--sdata-got} forces the old GOT placement.  PowerPC
+GCC doesn't use @code{.sdata} in shared libraries, so this option is
+really only useful for other compilers that may do so.
+
+@cindex PowerPC stub symbols
+@kindex --emit-stub-syms
+@item --emit-stub-syms
+This option causes @command{ld} to label linker stubs with a local
+symbol that encodes the stub type and destination.
+
+@cindex PowerPC TLS optimization
+@kindex --no-tls-optimize
+@item --no-tls-optimize
+PowerPC @command{ld} normally performs some optimization of code
+sequences used to access Thread-Local Storage.  Use this option to
+disable the optimization.
+@end table
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset POWERPC64
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node PowerPC64 ELF64
+@section @command{ld} and PowerPC64 64-bit ELF Support
+
+@cindex PowerPC64 ELF64 options
+@table @option
+@cindex PowerPC64 stub grouping
+@kindex --stub-group-size
+@item --stub-group-size
+Long branch stubs, PLT call stubs  and TOC adjusting 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.
+
+@cindex PowerPC64 stub symbols
+@kindex --emit-stub-syms
+@item --emit-stub-syms
+This option causes @command{ld} to label linker stubs with a local
+symbol that encodes the stub type and destination.
+
+@cindex PowerPC64 dot symbols
+@kindex --dotsyms
+@kindex --no-dotsyms
+@item --dotsyms
+@itemx --no-dotsyms
+These two options control how @command{ld} interprets version patterns
+in a version script.  Older PowerPC64 compilers emitted both a
+function descriptor symbol with the same name as the function, and a
+code entry symbol with the name prefixed by a dot (@samp{.}).  To
+properly version a function @samp{foo}, the version script thus needs
+to control both @samp{foo} and @samp{.foo}.  The option
+@samp{--dotsyms}, on by default, automatically adds the required
+dot-prefixed patterns.  Use @samp{--no-dotsyms} to disable this
+feature.
+
+@cindex PowerPC64 register save/restore functions
+@kindex --save-restore-funcs
+@kindex --no-save-restore-funcs
+@item --save-restore-funcs
+@itemx --no-save-restore-funcs
+These two options control whether PowerPC64 @command{ld} automatically
+provides out-of-line register save and restore functions used by
+@samp{-Os} code.  The default is to provide any such referenced
+function for a normal final link, and to not do so for a relocatable
+link.
+
+@cindex PowerPC64 TLS optimization
+@kindex --no-tls-optimize
+@item --no-tls-optimize
+PowerPC64 @command{ld} normally performs some optimization of code
+sequences used to access Thread-Local Storage.  Use this option to
+disable the optimization.
+
+@cindex PowerPC64 __tls_get_addr optimization
+@kindex --tls-get-addr-optimize
+@kindex --no-tls-get-addr-optimize
+@item --tls-get-addr-optimize
+@itemx --no-tls-get-addr-optimize
+These options control whether PowerPC64 @command{ld} uses a special
+stub to call __tls_get_addr.  PowerPC64 glibc 2.22 and later support
+an optimization that allows the second and subsequent calls to
+@code{__tls_get_addr} for a given symbol to be resolved by the special
+stub without calling in to glibc.  By default the linker enables this
+option when glibc advertises the availability of __tls_get_addr_opt.
+Forcing this option on when using an older glibc won't do much besides
+slow down your applications, but may be useful if linking an
+application against an older glibc with the expectation that it will
+normally be used on systems having a newer glibc.
+
+@cindex PowerPC64 OPD optimization
+@kindex --no-opd-optimize
+@item --no-opd-optimize
+PowerPC64 @command{ld} normally removes @code{.opd} section entries
+corresponding to deleted link-once functions, or functions removed by
+the action of @samp{--gc-sections} or linker script @code{/DISCARD/}.
+Use this option to disable @code{.opd} optimization.
+
+@cindex PowerPC64 OPD spacing
+@kindex --non-overlapping-opd
+@item --non-overlapping-opd
+Some PowerPC64 compilers have an option to generate compressed
+@code{.opd} entries spaced 16 bytes apart, overlapping the third word,
+the static chain pointer (unused in C) with the first word of the next
+entry.  This option expands such entries to the full 24 bytes.
+
+@cindex PowerPC64 TOC optimization
+@kindex --no-toc-optimize
+@item --no-toc-optimize
+PowerPC64 @command{ld} normally removes unused @code{.toc} section
+entries.  Such entries are detected by examining relocations that
+reference the TOC in code sections.  A reloc in a deleted code section
+marks a TOC word as unneeded, while a reloc in a kept code section
+marks a TOC word as needed.  Since the TOC may reference itself, TOC
+relocs are also examined.  TOC words marked as both needed and
+unneeded will of course be kept.  TOC words without any referencing
+reloc are assumed to be part of a multi-word entry, and are kept or
+discarded as per the nearest marked preceding word.  This works
+reliably for compiler generated code, but may be incorrect if assembly
+code is used to insert TOC entries.  Use this option to disable the
+optimization.
+
+@cindex PowerPC64 multi-TOC
+@kindex --no-multi-toc
+@item --no-multi-toc
+If given any toc option besides @code{-mcmodel=medium} or
+@code{-mcmodel=large}, PowerPC64 GCC generates code for a TOC model
+where TOC
+entries are accessed with a 16-bit offset from r2.  This limits the
+total TOC size to 64K.  PowerPC64 @command{ld} extends this limit by
+grouping code sections such that each group uses less than 64K for its
+TOC entries, then inserts r2 adjusting stubs between inter-group
+calls.  @command{ld} does not split apart input sections, so cannot
+help if a single input file has a @code{.toc} section that exceeds
+64K, most likely from linking multiple files with @command{ld -r}.
+Use this option to turn off this feature.
+
+@cindex PowerPC64 TOC sorting
+@kindex --no-toc-sort
+@item --no-toc-sort
+By default, @command{ld} sorts TOC sections so that those whose file
+happens to have a section called @code{.init} or @code{.fini} are
+placed first, followed by TOC sections referenced by code generated
+with PowerPC64 gcc's @code{-mcmodel=small}, and lastly TOC sections
+referenced only by code generated with PowerPC64 gcc's
+@code{-mcmodel=medium} or @code{-mcmodel=large} options.  Doing this
+results in better TOC grouping for multi-TOC.  Use this option to turn
+off this feature.
+
+@cindex PowerPC64 PLT stub alignment
+@kindex --plt-align
+@kindex --no-plt-align
+@item --plt-align
+@itemx --no-plt-align
+Use these options to control whether individual PLT call stubs are
+padded so that they don't cross a 32-byte boundary, or to the
+specified power of two boundary when using @code{--plt-align=}.  Note
+that this isn't alignment in the usual sense.  By default PLT call
+stubs are packed tightly.
+
+@cindex PowerPC64 PLT call stub static chain
+@kindex --plt-static-chain
+@kindex --no-plt-static-chain
+@item --plt-static-chain
+@itemx --no-plt-static-chain
+Use these options to control whether PLT call stubs load the static
+chain pointer (r11).  @code{ld} defaults to not loading the static
+chain since there is never any need to do so on a PLT call.
+
+@cindex PowerPC64 PLT call stub thread safety
+@kindex --plt-thread-safe
+@kindex --no-plt-thread-safe
+@item --plt-thread-safe
+@itemx --no-thread-safe
+With power7's weakly ordered memory model, it is possible when using
+lazy binding for ld.so to update a plt entry in one thread and have
+another thread see the individual plt entry words update in the wrong
+order, despite ld.so carefully writing in the correct order and using
+memory write barriers.  To avoid this we need some sort of read
+barrier in the call stub, or use LD_BIND_NOW=1.  By default, @code{ld}
+looks for calls to commonly used functions that create threads, and if
+seen, adds the necessary barriers.  Use these options to change the
+default behaviour.
+@end table
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset SPU
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node SPU ELF
+@section @command{ld} and SPU ELF Support
+
+@cindex SPU ELF options
+@table @option
+
+@cindex SPU plugins
+@kindex --plugin
+@item --plugin
+This option marks an executable as a PIC plugin module.
+
+@cindex SPU overlays
+@kindex --no-overlays
+@item --no-overlays
+Normally, @command{ld} recognizes calls to functions within overlay
+regions, and redirects such calls to an overlay manager via a stub.
+@command{ld} also provides a built-in overlay manager.  This option
+turns off all this special overlay handling.
+
+@cindex SPU overlay stub symbols
+@kindex --emit-stub-syms
+@item --emit-stub-syms
+This option causes @command{ld} to label overlay stubs with a local
+symbol that encodes the stub type and destination.
+
+@cindex SPU extra overlay stubs
+@kindex --extra-overlay-stubs
+@item --extra-overlay-stubs
+This option causes @command{ld} to add overlay call stubs on all
+function calls out of overlay regions.  Normally stubs are not added
+on calls to non-overlay regions.
+
+@cindex SPU local store size
+@kindex --local-store=lo:hi
+@item --local-store=lo:hi
+@command{ld} usually checks that a final executable for SPU fits in
+the address range 0 to 256k.  This option may be used to change the
+range.  Disable the check entirely with @option{--local-store=0:0}.
+
+@cindex SPU
+@kindex --stack-analysis
+@item --stack-analysis
+SPU local store space is limited.  Over-allocation of stack space
+unnecessarily limits space available for code and data, while
+under-allocation results in runtime failures.  If given this option,
+@command{ld} will provide an estimate of maximum stack usage.
+@command{ld} does this by examining symbols in code sections to
+determine the extents of functions, and looking at function prologues
+for stack adjusting instructions.  A call-graph is created by looking
+for relocations on branch instructions.  The graph is then searched
+for the maximum stack usage path.  Note that this analysis does not
+find calls made via function pointers, and does not handle recursion
+and other cycles in the call graph.  Stack usage may be
+under-estimated if your code makes such calls.  Also, stack usage for
+dynamic allocation, e.g. alloca, will not be detected.  If a link map
+is requested, detailed information about each function's stack usage
+and calls will be given.
+
+@cindex SPU
+@kindex --emit-stack-syms
+@item --emit-stack-syms
+This option, if given along with @option{--stack-analysis} will result
+in @command{ld} emitting stack sizing symbols for each function.
+These take the form @code{__stack_<function_name>} for global
+functions, and @code{__stack_<number>_<function_name>} for static
+functions.  @code{<number>} is the section id in hex.  The value of
+such symbols is the stack requirement for the corresponding function.
+The symbol size will be zero, type @code{STT_NOTYPE}, binding
+@code{STB_LOCAL}, and section @code{SHN_ABS}.
+@end table
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset TICOFF
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@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.
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset WIN32
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node WIN32
+@section @command{ld} and WIN32 (cygwin/mingw)
+
+This section describes some of the win32 specific @command{ld} issues.
+See @ref{Options,,Command Line Options} for detailed description of the
+command line options mentioned here.
+
+@table @emph
+@cindex import libraries
+@item import libraries
+The standard Windows linker creates and uses so-called import
+libraries, which contains information for linking to dll's.  They are
+regular static archives and are handled as any other static
+archive.  The cygwin and mingw ports of @command{ld} have specific
+support for creating such libraries provided with the
+@samp{--out-implib} command line option.
+
+@item   exporting DLL symbols
+@cindex exporting DLL symbols
+The cygwin/mingw @command{ld} has several ways to export symbols for dll's.
+
+@table @emph
+@item   using auto-export functionality
+@cindex using auto-export functionality
+By default @command{ld} exports symbols with the auto-export functionality,
+which is controlled by the following command line options:
+
+@itemize
+@item --export-all-symbols   [This is the default]
+@item --exclude-symbols
+@item --exclude-libs
+@item --exclude-modules-for-implib
+@item --version-script
+@end itemize
+
+When auto-export is in operation, @command{ld} will export all the non-local
+(global and common) symbols it finds in a DLL, with the exception of a few
+symbols known to belong to the system's runtime and libraries.  As it will
+often not be desirable to export all of a DLL's symbols, which may include
+private functions that are not part of any public interface, the command-line
+options listed above may be used to filter symbols out from the list for
+exporting.  The @samp{--output-def} option can be used in order to see the
+final list of exported symbols with all exclusions taken into effect.
+
+If @samp{--export-all-symbols} is not given explicitly on the
+command line, then the default auto-export behavior will be @emph{disabled}
+if either of the following are true:
+
+@itemize
+@item A DEF file is used.
+@item Any symbol in any object file was marked with the __declspec(dllexport) attribute.
+@end itemize
+
+@item   using a DEF file
+@cindex using a DEF file
+Another way of exporting symbols is using a DEF file.  A DEF file is
+an ASCII file containing definitions of symbols which should be
+exported when a dll is created.  Usually it is named @samp{<dll
+name>.def} and is added as any other object file to the linker's
+command line.  The file's name must end in @samp{.def} or @samp{.DEF}.
+
+@example
+gcc -o <output> <objectfiles> <dll name>.def
+@end example
+
+Using a DEF file turns off the normal auto-export behavior, unless the
+@samp{--export-all-symbols} option is also used.
+
+Here is an example of a DEF file for a shared library called @samp{xyz.dll}:
+
+@example
+LIBRARY "xyz.dll" BASE=0x20000000
+
+EXPORTS
+foo
+bar
+_bar = bar
+another_foo = abc.dll.afoo
+var1 DATA
+doo = foo == foo2
+eoo DATA == var1
+@end example
+
+This example defines a DLL with a non-default base address and seven
+symbols in the export table. The third exported symbol @code{_bar} is an
+alias for the second. The fourth symbol, @code{another_foo} is resolved
+by "forwarding" to another module and treating it as an alias for
+@code{afoo} exported from the DLL @samp{abc.dll}. The final symbol
+@code{var1} is declared to be a data object. The @samp{doo} symbol in
+export library is an alias of @samp{foo}, which gets the string name
+in export table @samp{foo2}. The @samp{eoo} symbol is an data export
+symbol, which gets in export table the name @samp{var1}.
+
+The optional @code{LIBRARY <name>} command indicates the @emph{internal}
+name of the output DLL. If @samp{<name>} does not include a suffix,
+the default library suffix, @samp{.DLL} is appended.
+
+When the .DEF file is used to build an application, rather than a
+library, the @code{NAME <name>} command should be used instead of
+@code{LIBRARY}. If @samp{<name>} does not include a suffix, the default
+executable suffix, @samp{.EXE} is appended.
+
+With either @code{LIBRARY <name>} or @code{NAME <name>} the optional
+specification @code{BASE = <number>} may be used to specify a
+non-default base address for the image.
+
+If neither @code{LIBRARY <name>} nor  @code{NAME <name>} is specified,
+or they specify an empty string, the internal name is the same as the
+filename specified on the command line.
+
+The complete specification of an export symbol is:
+
+@example
+EXPORTS
+  ( (  ( <name1> [ = <name2> ] )
+     | ( <name1> = <module-name> . <external-name>))
+  [ @@ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== <name3>] ) *
+@end example
+
+Declares @samp{<name1>} as an exported symbol from the DLL, or declares
+@samp{<name1>} as an exported alias for @samp{<name2>}; or declares
+@samp{<name1>} as a "forward" alias for the symbol
+@samp{<external-name>} in the DLL @samp{<module-name>}.
+Optionally, the symbol may be exported by the specified ordinal
+@samp{<integer>} alias. The optional @samp{<name3>} is the to be used
+string in import/export table for the symbol.
+
+The optional keywords that follow the declaration indicate:
+
+@code{NONAME}: Do not put the symbol name in the DLL's export table.  It
+will still be exported by its ordinal alias (either the value specified
+by the .def specification or, otherwise, the value assigned by the
+linker). The symbol name, however, does remain visible in the import
+library (if any), unless @code{PRIVATE} is also specified.
+
+@code{DATA}: The symbol is a variable or object, rather than a function.
+The import lib will export only an indirect reference to @code{foo} as
+the symbol @code{_imp__foo} (ie, @code{foo} must be resolved as
+@code{*_imp__foo}).
+
+@code{CONSTANT}: Like @code{DATA}, but put the undecorated @code{foo} as
+well as @code{_imp__foo} into the import library. Both refer to the
+read-only import address table's pointer to the variable, not to the
+variable itself. This can be dangerous. If the user code fails to add
+the @code{dllimport} attribute and also fails to explicitly add the
+extra indirection that the use of the attribute enforces, the
+application will behave unexpectedly.
+
+@code{PRIVATE}: Put the symbol in the DLL's export table, but do not put
+it into the static import library used to resolve imports at link time. The
+symbol can still be imported using the @code{LoadLibrary/GetProcAddress}
+API at runtime or by by using the GNU ld extension of linking directly to
+the DLL without an import library.
+
+See ld/deffilep.y in the binutils sources for the full specification of
+other DEF file statements
+
+@cindex creating a DEF file
+While linking a shared dll, @command{ld} is able to create a DEF file
+with the @samp{--output-def <file>} command line option.
+
+@item   Using decorations
+@cindex Using decorations
+Another way of marking symbols for export is to modify the source code
+itself, so that when building the DLL each symbol to be exported is
+declared as:
+
+@example
+__declspec(dllexport) int a_variable
+__declspec(dllexport) void a_function(int with_args)
+@end example
+
+All such symbols will be exported from the DLL.  If, however,
+any of the object files in the DLL contain symbols decorated in
+this way, then the normal auto-export behavior is disabled, unless
+the @samp{--export-all-symbols} option is also used.
+
+Note that object files that wish to access these symbols must @emph{not}
+decorate them with dllexport.  Instead, they should use dllimport,
+instead:
+
+@example
+__declspec(dllimport) int a_variable
+__declspec(dllimport) void a_function(int with_args)
+@end example
+
+This complicates the structure of library header files, because
+when included by the library itself the header must declare the
+variables and functions as dllexport, but when included by client
+code the header must declare them as dllimport.  There are a number
+of idioms that are typically used to do this; often client code can
+omit the __declspec() declaration completely.  See
+@samp{--enable-auto-import} and @samp{automatic data imports} for more
+information.
+@end table
+
+@cindex automatic data imports
+@item automatic data imports
+The standard Windows dll format supports data imports from dlls only
+by adding special decorations (dllimport/dllexport), which let the
+compiler produce specific assembler instructions to deal with this
+issue.  This increases the effort necessary to port existing Un*x
+code to these platforms, especially for large
+c++ libraries and applications.  The auto-import feature, which was
+initially provided by Paul Sokolovsky, allows one to omit the
+decorations to achieve a behavior that conforms to that on POSIX/Un*x
+platforms. This feature is enabled with the @samp{--enable-auto-import}
+command-line option, although it is enabled by default on cygwin/mingw.
+The @samp{--enable-auto-import} option itself now serves mainly to
+suppress any warnings that are ordinarily emitted when linked objects
+trigger the feature's use.
+
+auto-import of variables does not always work flawlessly without
+additional assistance.  Sometimes, you will see this message
+
+"variable '<var>' can't be auto-imported. Please read the
+documentation for ld's @code{--enable-auto-import} for details."
+
+The @samp{--enable-auto-import} documentation explains why this error
+occurs, and several methods that can be used to overcome this difficulty.
+One of these methods is the @emph{runtime pseudo-relocs} feature, described
+below.
+
+@cindex runtime pseudo-relocation
+For complex variables imported from DLLs (such as structs or classes),
+object files typically contain a base address for the variable and an
+offset (@emph{addend}) within the variable--to specify a particular
+field or public member, for instance.  Unfortunately, the runtime loader used
+in win32 environments is incapable of fixing these references at runtime
+without the additional information supplied by dllimport/dllexport decorations.
+The standard auto-import feature described above is unable to resolve these
+references.
+
+The @samp{--enable-runtime-pseudo-relocs} switch allows these references to
+be resolved without error, while leaving the task of adjusting the references
+themselves (with their non-zero addends) to specialized code provided by the
+runtime environment.  Recent versions of the cygwin and mingw environments and
+compilers provide this runtime support; older versions do not.  However, the
+support is only necessary on the developer's platform; the compiled result will
+run without error on an older system.
+
+@samp{--enable-runtime-pseudo-relocs} is not the default; it must be explicitly
+enabled as needed.
+
+@cindex direct linking to a dll
+@item direct linking to a dll
+The cygwin/mingw ports of @command{ld} support the direct linking,
+including data symbols, to a dll without the usage of any import
+libraries.  This is much faster and uses much less memory than does the
+traditional import library method, especially when linking large
+libraries or applications.  When @command{ld} creates an import lib, each
+function or variable exported from the dll is stored in its own bfd, even
+though a single bfd could contain many exports.  The overhead involved in
+storing, loading, and processing so many bfd's is quite large, and explains the
+tremendous time, memory, and storage needed to link against particularly
+large or complex libraries when using import libs.
+
+Linking directly to a dll uses no extra command-line switches other than
+@samp{-L} and @samp{-l}, because @command{ld} already searches for a number
+of names to match each library.  All that is needed from the developer's
+perspective is an understanding of this search, in order to force ld to
+select the dll instead of an import library.
+
+
+For instance, when ld is called with the argument @samp{-lxxx} it will attempt
+to find, in the first directory of its search path,
+
+@example
+libxxx.dll.a
+xxx.dll.a
+libxxx.a
+xxx.lib
+cygxxx.dll (*)
+libxxx.dll
+xxx.dll
+@end example
+
+before moving on to the next directory in the search path.
+
+(*) Actually, this is not @samp{cygxxx.dll} but in fact is @samp{<prefix>xxx.dll},
+where @samp{<prefix>} is set by the @command{ld} option
+@samp{--dll-search-prefix=<prefix>}. In the case of cygwin, the standard gcc spec
+file includes @samp{--dll-search-prefix=cyg}, so in effect we actually search for
+@samp{cygxxx.dll}.
+
+Other win32-based unix environments, such as mingw or pw32, may use other
+@samp{<prefix>}es, although at present only cygwin makes use of this feature.  It
+was originally intended to help avoid name conflicts among dll's built for the
+various win32/un*x environments, so that (for example) two versions of a zlib dll
+could coexist on the same machine.
+
+The generic cygwin/mingw path layout uses a @samp{bin} directory for
+applications and dll's and a @samp{lib} directory for the import
+libraries (using cygwin nomenclature):
+
+@example
+bin/
+	cygxxx.dll
+lib/
+	libxxx.dll.a   (in case of dll's)
+	libxxx.a       (in case of static archive)
+@end example
+
+Linking directly to a dll without using the import library can be
+done two ways:
+
+1. Use the dll directly by adding the @samp{bin} path to the link line
+@example
+gcc -Wl,-verbose  -o a.exe -L../bin/ -lxxx
+@end example
+
+However, as the dll's often have version numbers appended to their names
+(@samp{cygncurses-5.dll}) this will often fail, unless one specifies
+@samp{-L../bin -lncurses-5} to include the version.  Import libs are generally
+not versioned, and do not have this difficulty.
+
+2. Create a symbolic link from the dll to a file in the @samp{lib}
+directory according to the above mentioned search pattern.  This
+should be used to avoid unwanted changes in the tools needed for
+making the app/dll.
+
+@example
+ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
+@end example
+
+Then you can link without any make environment changes.
+
+@example
+gcc -Wl,-verbose  -o a.exe -L../lib/ -lxxx
+@end example
+
+This technique also avoids the version number problems, because the following is
+perfectly legal
+
+@example
+bin/
+	cygxxx-5.dll
+lib/
+	libxxx.dll.a -> ../bin/cygxxx-5.dll
+@end example
+
+Linking directly to a dll without using an import lib will work
+even when auto-import features are exercised, and even when
+@samp{--enable-runtime-pseudo-relocs} is used.
+
+Given the improvements in speed and memory usage, one might justifiably
+wonder why import libraries are used at all.  There are three reasons:
+
+1. Until recently, the link-directly-to-dll functionality did @emph{not}
+work with auto-imported data.
+
+2. Sometimes it is necessary to include pure static objects within the
+import library (which otherwise contains only bfd's for indirection
+symbols that point to the exports of a dll).  Again, the import lib
+for the cygwin kernel makes use of this ability, and it is not
+possible to do this without an import lib.
+
+3. Symbol aliases can only be resolved using an import lib.  This is
+critical when linking against OS-supplied dll's (eg, the win32 API)
+in which symbols are usually exported as undecorated aliases of their
+stdcall-decorated assembly names.
+
+So, import libs are not going away.  But the ability to replace
+true import libs with a simple symbolic link to (or a copy of)
+a dll, in many cases, is a useful addition to the suite of tools
+binutils makes available to the win32 developer.  Given the
+massive improvements in memory requirements during linking, storage
+requirements, and linking speed, we expect that many developers
+will soon begin to use this feature whenever possible.
+
+@item symbol aliasing
+@table @emph
+@item adding additional names
+Sometimes, it is useful to export symbols with additional names.
+A symbol @samp{foo} will be exported as @samp{foo}, but it can also be
+exported as @samp{_foo} by using special directives in the DEF file
+when creating the dll.  This will affect also the optional created
+import library.  Consider the following DEF file:
+
+@example
+LIBRARY "xyz.dll" BASE=0x61000000
+
+EXPORTS
+foo
+_foo = foo
+@end example
+
+The line @samp{_foo = foo} maps the symbol @samp{foo} to @samp{_foo}.
+
+Another method for creating a symbol alias is to create it in the
+source code using the "weak" attribute:
+
+@example
+void foo () @{ /* Do something.  */; @}
+void _foo () __attribute__ ((weak, alias ("foo")));
+@end example
+
+See the gcc manual for more information about attributes and weak
+symbols.
+
+@item renaming symbols
+Sometimes it is useful to rename exports.  For instance, the cygwin
+kernel does this regularly.  A symbol @samp{_foo} can be exported as
+@samp{foo} but not as @samp{_foo} by using special directives in the
+DEF file. (This will also affect the import library, if it is
+created).  In the following example:
+
+@example
+LIBRARY "xyz.dll" BASE=0x61000000
+
+EXPORTS
+_foo = foo
+@end example
+
+The line @samp{_foo = foo} maps the exported symbol @samp{foo} to
+@samp{_foo}.
+@end table
+
+Note: using a DEF file disables the default auto-export behavior,
+unless the @samp{--export-all-symbols} command line option is used.
+If, however, you are trying to rename symbols, then you should list
+@emph{all} desired exports in the DEF file, including the symbols
+that are not being renamed, and do @emph{not} use the
+@samp{--export-all-symbols} option.  If you list only the
+renamed symbols in the DEF file, and use @samp{--export-all-symbols}
+to handle the other symbols, then the both the new names @emph{and}
+the original names for the renamed symbols will be exported.
+In effect, you'd be aliasing those symbols, not renaming them,
+which is probably not what you wanted.
+
+@cindex weak externals
+@item weak externals
+The Windows object format, PE, specifies a form of weak symbols called
+weak externals.  When a weak symbol is linked and the symbol is not
+defined, the weak symbol becomes an alias for some other symbol.  There
+are three variants of weak externals:
+@itemize
+@item Definition is searched for in objects and libraries, historically
+called lazy externals.
+@item Definition is searched for only in other objects, not in libraries.
+This form is not presently implemented.
+@item No search; the symbol is an alias.  This form is not presently
+implemented.
+@end itemize
+As a GNU extension, weak symbols that do not specify an alternate symbol
+are supported.  If the symbol is undefined when linking, the symbol
+uses a default value.
+
+@cindex aligned common symbols
+@item aligned common symbols
+As a GNU extension to the PE file format, it is possible to specify the
+desired alignment for a common symbol.  This information is conveyed from
+the assembler or compiler to the linker by means of GNU-specific commands
+carried in the object file's @samp{.drectve} section, which are recognized
+by @command{ld} and respected when laying out the common symbols.  Native
+tools will be able to process object files employing this GNU extension,
+but will fail to respect the alignment instructions, and may issue noisy
+warnings about unknown linker directives.
+
+@end table
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset XTENSA
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node Xtensa
+@section @code{ld} and Xtensa Processors
+
+@cindex Xtensa processors
+The default @command{ld} behavior for Xtensa processors is to interpret
+@code{SECTIONS} commands so that lists of explicitly named sections in a
+specification with a wildcard file will be interleaved when necessary to
+keep literal pools within the range of PC-relative load offsets.  For
+example, with the command:
+
+@smallexample
+SECTIONS
+@{
+  .text : @{
+    *(.literal .text)
+  @}
+@}
+@end smallexample
+
+@noindent
+@command{ld} may interleave some of the @code{.literal}
+and @code{.text} sections from different object files to ensure that the
+literal pools are within the range of PC-relative load offsets.  A valid
+interleaving might place the @code{.literal} sections from an initial
+group of files followed by the @code{.text} sections of that group of
+files.  Then, the @code{.literal} sections from the rest of the files
+and the @code{.text} sections from the rest of the files would follow.
+
+@cindex @option{--relax} on Xtensa
+@cindex relaxing on Xtensa
+Relaxation is enabled by default for the Xtensa version of @command{ld} and
+provides two important link-time optimizations.  The first optimization
+is to combine identical literal values to reduce code size.  A redundant
+literal will be removed and all the @code{L32R} instructions that use it
+will be changed to reference an identical literal, as long as the
+location of the replacement literal is within the offset range of all
+the @code{L32R} instructions.  The second optimization is to remove
+unnecessary overhead from assembler-generated ``longcall'' sequences of
+@code{L32R}/@code{CALLX@var{n}} when the target functions are within
+range of direct @code{CALL@var{n}} instructions.
+
+For each of these cases where an indirect call sequence can be optimized
+to a direct call, the linker will change the @code{CALLX@var{n}}
+instruction to a @code{CALL@var{n}} instruction, remove the @code{L32R}
+instruction, and remove the literal referenced by the @code{L32R}
+instruction if it is not used for anything else.  Removing the
+@code{L32R} instruction always reduces code size but can potentially
+hurt performance by changing the alignment of subsequent branch targets.
+By default, the linker will always preserve alignments, either by
+switching some instructions between 24-bit encodings and the equivalent
+density instructions or by inserting a no-op in place of the @code{L32R}
+instruction that was removed.  If code size is more important than
+performance, the @option{--size-opt} option can be used to prevent the
+linker from widening density instructions or inserting no-ops, except in
+a few cases where no-ops are required for correctness.
+
+The following Xtensa-specific command-line options can be used to
+control the linker:
+
+@cindex Xtensa options
+@table @option
+@item --size-opt
+When optimizing indirect calls to direct calls, optimize for code size
+more than performance.  With this option, the linker will not insert
+no-ops or widen density instructions to preserve branch target
+alignment.  There may still be some cases where no-ops are required to
+preserve the correctness of the code.
+@end table
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@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.
+
+@ifset BUGURL
+Otherwise, send bug reports for @command{ld} to
+@value{BUGURL}.
+@end ifset
+
+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?''  This cannot help us fix a bug, so it is basically useless.  We
+respond by asking for enough details to enable us to investigate.
+You might as well expedite matters by sending them to begin with.
+
+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
+provided that they are reasonably small.  Say no more than 10K.  For
+bigger files you can either make them available by FTP or HTTP or else
+state that you are willing to send the object file(s) to whomever
+requests them.  (Note - your email will be going to a mailing list, so
+we do not want to clog it up with large attachments).  But small
+attachments are best.
+
+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 sync, 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
+@include fdl.texi
+
+@node LD Index
+@unnumbered LD 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
+
+@bye
diff -Nuar binutils-2.26.orig/ld/lexsup.c binutils-2.26/ld/lexsup.c
--- binutils-2.26.orig/ld/lexsup.c	2016-04-03 07:35:47.533763235 +0300
+++ binutils-2.26/ld/lexsup.c	2016-04-03 07:39:40.334754162 +0300
@@ -1,5 +1,5 @@
 /* Parse options for the GNU linker.
-   Copyright (C) 1991-2015 Free Software Foundation, Inc.
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
 
    This file is part of the GNU Binutils.
 
@@ -1586,15 +1586,14 @@
   /* We may have -Bsymbolic, -Bsymbolic-functions, --dynamic-list-data,
      --dynamic-list-cpp-new, --dynamic-list-cpp-typeinfo and
      --dynamic-list FILE.  -Bsymbolic and -Bsymbolic-functions are
-     for shared libraries.  -Bsymbolic overrides all others and vice
-     versa.  */
+     for PIC outputs.  -Bsymbolic overrides all others and vice versa.  */
   switch (command_line.symbolic)
     {
     case symbolic_unset:
       break;
     case symbolic:
-      /* -Bsymbolic is for shared library only.  */
-      if (bfd_link_dll (&link_info))
+      /* -Bsymbolic is for PIC output only.  */
+      if (bfd_link_pic (&link_info))
 	{
 	  link_info.symbolic = TRUE;
 	  /* Should we free the unused memory?  */
@@ -1603,8 +1602,8 @@
 	}
       break;
     case symbolic_functions:
-      /* -Bsymbolic-functions is for shared library only.  */
-      if (bfd_link_dll (&link_info))
+      /* -Bsymbolic-functions is for PIC output only.  */
+      if (bfd_link_pic (&link_info))
 	command_line.dynamic_list = dynamic_list_data;
       break;
     }
diff -Nuar binutils-2.26.orig/ld/testsuite/ld-i386/i386.exp binutils-2.26/ld/testsuite/ld-i386/i386.exp
--- binutils-2.26.orig/ld/testsuite/ld-i386/i386.exp	2016-04-03 07:35:47.989763217 +0300
+++ binutils-2.26/ld/testsuite/ld-i386/i386.exp	2016-04-03 07:43:32.503745115 +0300
@@ -1,5 +1,5 @@
 # Expect script for ld-i386 tests
-#   Copyright (C) 2002-2015 Free Software Foundation, Inc.
+#   Copyright (C) 2002-2016 Free Software Foundation, Inc.
 #
 # This file is part of the GNU Binutils.
 #
@@ -319,6 +319,7 @@
 run_dump_test "load5b"
 run_dump_test "load6"
 run_dump_test "pr19175"
+run_dump_test "pr19615"
 
 if { !([istarget "i?86-*-linux*"]
        || [istarget "i?86-*-gnu*"]
@@ -357,7 +358,7 @@
 	[list \
 	    "Build libplt-main1.a" \
 	    "" \
-	    "-fPIC" \
+	    "-fPIC -Wa,-mrelax-relocations=yes" \
 	    { plt-main1.c } \
 	    {{readelf {-Wr} plt-main1.rd}} \
 	    "libplt-main1.a" \
@@ -365,7 +366,7 @@
 	[list \
 	    "Build libplt-main2.a" \
 	    "" \
-	    "-fPIC" \
+	    "-fPIC -Wa,-mrelax-relocations=yes" \
 	    { plt-main2.c } \
 	    {{readelf {-Wr} plt-main2.rd}} \
 	    "libplt-main2.a" \
@@ -373,7 +374,7 @@
 	[list \
 	    "Build libplt-main3.a" \
 	    "" \
-	    "-fPIC $PLT_CFLAGS" \
+	    "-fPIC -Wa,-mrelax-relocations=yes $PLT_CFLAGS" \
 	    { plt-main3.c } \
 	    {{readelf {-Wr} plt-main3.rd}} \
 	    "libplt-main3.a" \
@@ -381,7 +382,7 @@
 	[list \
 	    "Build libplt-main4.a" \
 	    "" \
-	    "-fPIC $PLT_CFLAGS" \
+	    "-fPIC -Wa,-mrelax-relocations=yes $PLT_CFLAGS" \
 	    { plt-main4.c } \
 	    {{readelf {-Wr} plt-main4.rd}} \
 	    "libplt-main4.a" \
@@ -535,7 +536,7 @@
 	[list \
 	    "Build gotpc1" \
 	    "tmpdir/got1d.so" \
-	    "" \
+	    "-Wa,-mrelax-relocations=yes" \
 	    { got1a.S got1b.c got1c.c } \
 	    {{objdump {-dw} got1.dd}} \
 	    "got1" \
diff -Nuar binutils-2.26.orig/ld/testsuite/ld-i386/pr19615.d binutils-2.26/ld/testsuite/ld-i386/pr19615.d
--- binutils-2.26.orig/ld/testsuite/ld-i386/pr19615.d	1970-01-01 02:00:00.000000000 +0200
+++ binutils-2.26/ld/testsuite/ld-i386/pr19615.d	2016-04-03 07:44:18.145743336 +0300
@@ -0,0 +1,13 @@
+#as: --32
+#ld: -pie -Bsymbolic -E -melf_i386
+#readelf: -r --wide --dyn-syms
+
+Relocation section '.rel.dyn' at offset 0x[0-9a-f]+ contains 1 entries:
+ Offset     Info    Type                Sym. Value  Symbol's Name
+[0-9a-f]+ +[0-9a-f]+ +R_386_RELATIVE +
+
+Symbol table '.dynsym' contains [0-9]+ entries:
+   Num:    Value  Size Type    Bind   Vis      Ndx Name
+#...
+[ 	]*[a-f0-9]+: [a-f0-9]+     0 FUNC    GLOBAL DEFAULT    [a-f0-9]+ xyzzy
+#...
diff -Nuar binutils-2.26.orig/ld/testsuite/ld-i386/pr19615.s binutils-2.26/ld/testsuite/ld-i386/pr19615.s
--- binutils-2.26.orig/ld/testsuite/ld-i386/pr19615.s	1970-01-01 02:00:00.000000000 +0200
+++ binutils-2.26/ld/testsuite/ld-i386/pr19615.s	2016-04-03 07:44:34.444742701 +0300
@@ -0,0 +1,13 @@
+	.text
+	.globl _start
+	.type _start, @function
+_start:
+	ret
+
+	.globl xyzzy	/* This symbol should be exported */
+	.type xyzzy, @function
+xyzzy:
+	ret
+
+	.section ".xyzzy_ptr","aw",%progbits
+	.dc.a xyzzy
diff -Nuar binutils-2.26.orig/ld/testsuite/ld-x86-64/pr19615.d binutils-2.26/ld/testsuite/ld-x86-64/pr19615.d
--- binutils-2.26.orig/ld/testsuite/ld-x86-64/pr19615.d	1970-01-01 02:00:00.000000000 +0200
+++ binutils-2.26/ld/testsuite/ld-x86-64/pr19615.d	2016-04-03 07:46:46.744737545 +0300
@@ -0,0 +1,13 @@
+#as: --64
+#ld: -pie -Bsymbolic -E -melf_x86_64
+#readelf: -r --wide --dyn-syms
+
+Relocation section '.rela.dyn' at offset 0x[0-9a-f]+ contains 1 entries:
+    Offset             Info             Type               Symbol's Value  Symbol's Name \+ Addend
+[0-9a-f]+ +[0-9a-f]+ +R_X86_64_RELATIVE +[0-9]+
+
+Symbol table '.dynsym' contains [0-9]+ entries:
+   Num:    Value          Size Type    Bind   Vis      Ndx Name
+#...
+[ 	]*[a-f0-9]+: [a-f0-9]+     0 FUNC    GLOBAL DEFAULT    [a-f0-9]+ xyzzy
+#...
diff -Nuar binutils-2.26.orig/ld/testsuite/ld-x86-64/pr19615.s binutils-2.26/ld/testsuite/ld-x86-64/pr19615.s
--- binutils-2.26.orig/ld/testsuite/ld-x86-64/pr19615.s	1970-01-01 02:00:00.000000000 +0200
+++ binutils-2.26/ld/testsuite/ld-x86-64/pr19615.s	2016-04-03 07:46:32.977738081 +0300
@@ -0,0 +1,13 @@
+	.text
+	.globl _start
+	.type _start, @function
+_start:
+	ret
+
+	.globl xyzzy	/* This symbol should be exported */
+	.type xyzzy, @function
+xyzzy:
+	ret
+
+	.section ".xyzzy_ptr","aw",%progbits
+	.dc.a xyzzy
diff -Nuar binutils-2.26.orig/ld/testsuite/ld-x86-64/x86-64.exp binutils-2.26/ld/testsuite/ld-x86-64/x86-64.exp
--- binutils-2.26.orig/ld/testsuite/ld-x86-64/x86-64.exp	2016-04-03 07:35:48.566763194 +0300
+++ binutils-2.26/ld/testsuite/ld-x86-64/x86-64.exp	2016-04-03 07:45:56.631739498 +0300
@@ -1,5 +1,5 @@
 # Expect script for ld-x86_64 tests
-#   Copyright (C) 2002-2015 Free Software Foundation, Inc.
+#   Copyright (C) 2002-2016 Free Software Foundation, Inc.
 #
 # This file is part of the GNU Binutils.
 #
@@ -353,6 +353,8 @@
 run_dump_test "pr19013-nacl"
 run_dump_test "pr19162"
 run_dump_test "pr19175"
+run_dump_test "pr18591"
+run_dump_test "pr19615"
 
 # Add $PLT_CFLAGS if PLT is expected.
 global PLT_CFLAGS
@@ -391,7 +393,7 @@
 	[list \
 	    "Build libplt-main1.a" \
 	    "" \
-	    "-fPIC" \
+	    "-fPIC -Wa,-mrelax-relocations=yes" \
 	    { plt-main1.c } \
 	    {{readelf {-Wr} plt-main1.rd}} \
 	    "libplt-main1.a" \
@@ -399,7 +401,7 @@
 	[list \
 	    "Build libplt-main2.a" \
 	    "" \
-	    "-fPIC" \
+	    "-fPIC -Wa,-mrelax-relocations=yes" \
 	    { plt-main2.c } \
 	    {{readelf {-Wr} plt-main2.rd}} \
 	    "libplt-main2.a" \
@@ -407,7 +409,7 @@
 	[list \
 	    "Build libplt-main3.a" \
 	    "" \
-	    "-fPIC $PLT_CFLAGS" \
+	    "-fPIC -Wa,-mrelax-relocations=yes $PLT_CFLAGS" \
 	    { plt-main3.c } \
 	    {{readelf {-Wr} plt-main3.rd}} \
 	    "libplt-main3.a" \
@@ -415,7 +417,7 @@
 	[list \
 	    "Build libplt-main4.a" \
 	    "" \
-	    "-fPIC $PLT_CFLAGS" \
+	    "-fPIC -Wa,-mrelax-relocations=yes $PLT_CFLAGS" \
 	    { plt-main4.c } \
 	    {{readelf {-Wr} plt-main4.rd}} \
 	    "libplt-main4.a" \
@@ -545,7 +547,7 @@
 	[list \
 	    "Build gotpcrel1" \
 	    "tmpdir/gotpcrel1d.so" \
-	    "" \
+	    "-Wa,-mrelax-relocations=yes" \
 	    { gotpcrel1a.S gotpcrel1b.c gotpcrel1c.c } \
 	    {{objdump {-dw} gotpcrel1.dd}} \
 	    "gotpcrel1" \