Initial GNU binutils 2.6 import

1 files changed, 2641 insertions, 0 deletions

diff --git a/gnu/usr.bin/binutils/ld/ld.texinfo b/gnu/usr.bin/binutils/ld/ld.texinfo
new file mode 100644
index 00000000000..b782ce21edf
--- /dev/null
+++ b/gnu/usr.bin/binutils/ld/ld.texinfo
@@ -0,0 +1,2641 @@
+\input texinfo
+@setfilename ld.info
+@syncodeindex ky cp
+@include configdoc.texi
+@c (configdoc.texi is generated by the Makefile)
+
+@c @smallbook
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Ld: (ld).                       The GNU linker.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@ifinfo
+This file documents the @sc{gnu} linker LD.
+
+Copyright (C) 1991, 92, 93, 94, 1995 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+@end ifinfo
+@iftex
+@finalout
+@setchapternewpage odd
+@settitle Using LD, the GNU linker
+@titlepage
+@title Using ld
+@subtitle The GNU linker
+@sp 1
+@subtitle @code{ld} version 2
+@subtitle January 1994
+@author Steve Chamberlain
+@author Cygnus Support
+@page
+
+@tex
+{\parskip=0pt
+\hfill Cygnus Support\par
+\hfill steve\@cygnus.com, doc\@cygnus.com\par
+\hfill {\it Using LD, the GNU linker}\par
+\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
+}
+\global\parindent=0pt % Steve likes it this way.
+@end tex
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1991, 92, 93, 94, 1995 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end titlepage
+@end iftex
+@c FIXME: Talk about importance of *order* of args, cmds to linker!
+
+@ifinfo
+@node Top
+@top Using ld
+This file documents the @sc{gnu} linker ld.
+
+@menu
+* Overview::                    Overview
+* Invocation::                  Invocation
+* Commands::                    Command Language
+@ifset GENERIC
+* Machine Dependent::           Machine Dependent Features
+@end ifset
+@ifclear GENERIC
+@ifset H8300
+* H8/300::                      ld and the H8/300
+@end ifset
+@ifset Hitachi
+* Hitachi::                     ld and other Hitachi micros
+@end ifset
+@ifset I960
+* i960::                        ld and the Intel 960 family
+@end ifset
+@end ifclear
+@ifclear SingleFormat
+* BFD::                         BFD
+@end ifclear
+@c Following blank line required for remaining bug in makeinfo conds/menus
+
+* MRI::                         MRI Compatible Script Files
+* Index::                       Index
+@end menu
+@end ifinfo
+
+@node Overview
+@chapter Overview
+
+@cindex @sc{gnu} linker
+@cindex what is this?
+@code{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 @code{ld}.
+
+@code{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.
+
+@ifclear SingleFormat
+This version of @code{ld} uses the general purpose BFD libraries
+to operate on object files. This allows @code{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,
+@code{ld} continues executing, allowing you to identify other errors
+(or, in some cases, to get an output file in spite of the error).
+
+@node Invocation
+@chapter Invocation
+
+The @sc{gnu} linker @code{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.
+
+@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
+Here is a summary of the options you can use on the @code{ld} command
+line:
+
+@c FIXME!  -relax only avail h8/300, i960.  Conditionals screwed in examples.
+@smallexample
+ld [ -o @var{output} ]  @var{objfile}@dots{}
+  [ -A@var{architecture} ]  [ -b @var{input-format} ]
+  [ -Bstatic ]  [ -Bdynamic ]  [ -Bsymbolic ]
+  [ -c @var{MRI-commandfile} ]  [ -d | -dc | -dp ]  
+  [ -defsym @var{symbol}=@var{expression} ]
+  [ -dynamic-linker @var{file} ] [ -embedded-relocs ]
+  [ -e @var{entry} ]  [ -F ]  [ -F @var{format} ]
+  [ -format @var{input-format} ]  [ -g ]  [ -G @var{size} ]
+  [ -help ]  [ -i ]  [ -l@var{archive} ]  [ -L@var{searchdir} ]
+  [ -M ]  [ -Map @var{mapfile} ]  [ -m @var{emulation} ]
+  [ -N | -n ]  [ -noinhibit-exec ]  [ -no-keep-memory ]
+  [ -oformat @var{output-format} ]  [ -R @var{filename} ]
+  [ -relax ]  [ -retain-symbols-file @var{filename} ]
+  [ -r | -Ur ]  [ -rpath @var{dir} ] [-rpath-link @var{dir} ]
+  [ -S ]  [ -s ] [ -soname @var{name} ] [ -shared ] 
+  [ -sort-common ] [ -stats ] [ -T @var{commandfile} ]
+  [ -Ttext @var{org} ]  [ -Tdata @var{org} ]
+  [ -Tbss @var{org} ]  [ -t ] [ -traditional-format ]
+  [ -u @var{symbol}]  [-V]  [-v]  [ -verbose]  [ -version ]
+  [ -warn-common ] [ -warn-constructors] [ -warn-once ]
+  [ -y @var{symbol} ]  [ -X ]  [-x ]
+  [ -( [ archives ] -) ]
+  [ --start-group [ archives ] --end-group ]
+  [ -split-by-reloc @var{count} ] [ -split-by-file ]
+  [ --whole-archive ]
+@end smallexample
+
+This plethora of command-line options may seem intimidating, but in
+actual practice few of them are used in any particular context.
+@cindex standard Unix system
+For instance, a frequent use of @code{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 @code{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.)
+
+The command-line options to @code{ld} may be specified in any order, and
+may be repeated at will.  Repeating most 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.  
+
+@ifclear SingleFormat
+The exceptions---which may meaningfully be used more than once---are
+@samp{-A}, @samp{-b} (or its synonym @samp{-format}), @samp{-defsym},
+@samp{-L}, @samp{-l}, @samp{-R}, @samp{-u}, and @samp{-(} (or its
+synonym @samp{--start-group})..
+@end ifclear
+@ifset SingleFormat
+The exceptions---which may meaningfully be used more than once---are
+@samp{-A}, @samp{-defsym}, @samp{-L}, @samp{-l}, @samp{-R}, @samp{-u},
+and @samp{-(} (or its synonym @samp{--start-group}).
+@end ifset
+
+@cindex object files
+The list of object files to be linked together, shown as @var{objfile}@dots{},
+may follow, precede, or be mixed in with command-line options, except that
+an @var{objfile} argument may not be placed between an option and
+its argument.
+
+Usually the linker is invoked with at least one object file, but you can
+specify other forms of binary input files using @samp{-l}, @samp{-R},
+and the script command language.  If @emph{no} binary input files at all
+are specified, the linker does not produce any output, and issues the
+message @samp{No input files}.
+
+If the linker can not recognize the format of an object file, it will
+assume that it is a linker script.  A script specified in this way
+augments the main linker script used for the link (either the default
+linker script or the one specified by using @samp{-T}).  This feature
+permits the linker to link against a file which appears to be an object
+or an archive, but actually merely defines some symbol values, or uses
+@code{INPUT} or @code{GROUP} to load other objects.  @xref{Commands}.
+
+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{--oformat} and
+@samp{-oformat} are equivalent.  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{--oformat srec} and
+@samp{--oformat=srec} are equivalent.  Unique abbreviations of the names
+of multiple-letter options are accepted.
+
+@table @code
+@ifset I960
+@cindex architectures
+@kindex -A@var{arch}
+@item -A@var{architecture}
+In the current release of @code{ld}, this option is useful only for the
+Intel 960 family of architectures.  In that @code{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,,@code{ld} and the Intel 960
+family}, for details.
+
+Future releases of @code{ld} may support similar functionality for
+other architecture families.
+@end ifset
+
+@ifclear SingleFormat
+@cindex binary input format
+@kindex -b @var{format}
+@cindex input format
+@cindex input format
+@item -b @var{input-format}
+@code{ld} may be configured to support more than one kind of object
+file.  If your @code{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 @code{ld} is
+configured to support alternative object formats, you don't usually need
+to specify this, as @code{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}.)  @w{@samp{-format @var{input-format}}}
+has the same effect, as does the script command @code{TARGET}.
+@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}; see @ref{Option
+Commands}.
+@end ifclear
+
+@kindex -Bstatic
+@item -Bstatic 
+Do not link against shared libraries.  This is only meaningful on
+platforms for which shared libraries are supported.
+
+@kindex -Bdynamic
+@item -Bdynamic
+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.
+
+@kindex -Bsymbolic
+@item -Bsymbolic
+When creating a shared library, bind references to global symbols to the
+definition within the shared library, if any.  Normally, it is possible
+for a program linked against a shared library to override the definition
+within the shared library.  This option is only meaningful on ELF
+platforms which support shared libraries.
+
+@kindex -c @var{MRI-cmdfile}
+@cindex compatibility, MRI
+@item -c @var{MRI-commandfile}
+For compatibility with linkers produced by MRI, @code{ld} accepts script
+files written in an alternate, restricted command language, described in
+@ref{MRI,,MRI Compatible Script Files}.  Introduce MRI script files with
+the option @samp{-c}; use the @samp{-T} option to run linker
+scripts written in the general-purpose @code{ld} scripting language.
+If @var{MRI-cmdfile} does not exist, @code{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{Option
+Commands}.
+
+@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{Assignment, ,
+Assignment: Symbol Definitions}).  @emph{Note:}  there should be no
+white space between @var{symbol}, the equals sign (``@key{=}''), and
+@var{expression}.
+
+@ifset GENERIC
+@cindex dynamic linker, from command line
+@kindex -dynamic-linker @var{file}
+@item -dynamic-linker @var{file}
+Set the name of the dynamic linker.  This is only meaningful when
+generating dynamically linked ELF executables.  The default dynamic
+linker is normally correct; don't use this unless you know what you are
+doing.
+@end ifset
+
+@cindex MIPS embedded PIC code
+@kindex -embedded-relocs
+@item -embedded-relocs
+This option is only meaningful when linking MIPS embedded PIC code,
+generated by the -membedded-pic option to the @sc{gnu} compiler and
+assembler.  It causes the linker to create a table which may be used at
+runtime to relocate any data which was statically initialized to pointer
+values.  See the code in testsuite/ld-empic for details.
+
+@cindex entry point, from command line
+@kindex -e @var{entry}
+@item -e @var{entry} 
+Use @var{entry} as the explicit symbol for beginning execution of your
+program, rather than the default entry point. @xref{Entry Point}, for a
+discussion of defaults and other ways of specifying the
+entry point.
+
+@ifclear SingleFormat
+@kindex -F
+@item -F
+@itemx -F@var{format}
+Ignored.  Some older linkers used this option throughout a compilation
+toolchain for specifying object-file format for both input and output
+object files.  The mechanisms @code{ld} uses for this purpose (the
+@samp{-b} or @samp{-format} options for input files, @samp{-oformat}
+option or the @code{TARGET} command in linker scripts for output files,
+the @code{GNUTARGET} environment variable) are more flexible, but
+@code{ld} accepts the @samp{-F} option for compatibility with scripts
+written to call the old linker.
+
+@kindex -format
+@item -format @var{input-format}
+Synonym for @samp{-b @var{input-format}}.
+@end ifclear
+
+@kindex -g
+@item -g
+Ignored.  Provided for compatibility with other tools.
+
+@kindex -G
+@cindex object size
+@item -G@var{value}
+@itemx -G @var{value}
+Set the maximum size of objects to be optimized using the GP register to
+@var{size} under MIPS ECOFF.  Ignored for other object file formats.
+
+@cindex help
+@cindex usage
+@kindex -help
+@item -help
+Print a summary of the command-line options on the standard output and exit.
+
+@kindex -i
+@cindex incremental link
+@item -i
+Perform an incremental link (same as option @samp{-r}).
+
+@cindex archive files, from cmd line
+@kindex -l@var{archive}
+@item -l@var{ar} 
+Add archive file @var{archive} to the list of files to link.  This 
+option may be used any number of times.  @code{ld} will search its
+path-list for occurrences of @code{lib@var{ar}.a} for every @var{archive}
+specified.
+
+@cindex search directory, from cmd line
+@kindex -L@var{dir}
+@item -L@var{searchdir} 
+@itemx -L @var{searchdir} 
+Add path @var{searchdir} to the list of paths that @code{ld} will search
+for archive libraries and @code{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
+@code{-L} options apply to all @code{-l} options, regardless of the
+order in which the options appear.
+
+@ifset UsesEnvVars
+The default set of paths searched (without being specified with
+@samp{-L}) depends on which emulation mode @code{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 link map
+@kindex -M
+@item -M 
+Print (to the standard output) a link map---diagnostic information about
+where symbols are mapped by @code{ld}, and information on global common
+storage allocation.
+
+@cindex link map
+@kindex -Map
+@item -Map @var{mapfile}
+Print to the file @var{mapfile} a link map---diagnostic information
+about where symbols are mapped by @code{ld}, and information on global
+common storage allocation.
+
+@cindex emulation
+@kindex -m @var{emulation}
+@item -m@var{emulation}
+@itemx -m @var{emulation}
+Emulate the @var{emulation} linker.  You can list the available
+emulations with the @samp{--verbose} or @samp{-V} options.  The default
+depends on how your @code{ld} was configured.
+
+@kindex -N
+@cindex read/write from cmd line
+@kindex OMAGIC
+@item -N 
+Set the text and data sections to be readable and writable.  Also, do
+not page-align the data segment.  If the output format supports Unix
+style magic numbers, mark the output as @code{OMAGIC}.
+
+@kindex -n
+@cindex read-only text
+@kindex NMAGIC
+@item -n 
+Set the text segment to be read only, and mark the output as
+@code{NMAGIC} if possible.
+
+@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.
+
+@cindex memory usage
+@kindex -no-keep-memory
+@item -no-keep-memory
+@code{ld} normally optimizes for speed over memory usage by caching the
+symbol tables of input files in memory.  This option tells @code{ld} to
+instead optimize for memory usage, by rereading the symbol tables as
+necessary.  This may be required if @code{ld} runs out of memory space
+while linking a large executable.
+
+@kindex -o @var{output}
+@cindex naming the output file
+@item -o @var{output}
+Use @var{output} as the name for the program produced by @code{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.
+
+@ifclear SingleFormat
+@kindex -oformat
+@item -oformat @var{output-format}
+@code{ld} may be configured to support more than one kind of object
+file.  If your @code{ld} is configured this way, you can use the
+@samp{-oformat} option to specify the binary format for the output
+object file.  Even when @code{ld} is configured to support alternative
+object formats, you don't usually need to specify this, as @code{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 -R @var{file}
+@cindex symbol-only input
+@item -R @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.
+ 
+@kindex -relax
+@cindex synthesizing linker
+@cindex relaxing addressing modes
+@item -relax
+An option with machine dependent effects.  
+@ifset GENERIC
+Currently this option is only supported on the H8/300 and the Intel 960.
+@end ifset
+@ifset H8300
+@xref{H8/300,,@code{ld} and the H8/300}.
+@end ifset
+@ifset I960
+@xref{i960,, @code{ld} and the Intel 960 family}.
+@end ifset
+
+On some platforms, the @samp{-relax} option performs global optimizations that
+become possible when the linker resolves addressing in the program, such
+as relaxing address modes and synthesizing new instructions in the
+output object file.  
+
+@ifset GENERIC
+On platforms where this is not supported, @samp{-relax} is accepted, but
+ignored.
+@end ifset
+
+@cindex retaining specified symbols
+@cindex stripping all but some symbols
+@cindex symbols, retaining selectively
+@item -retain-symbols-file @var{filename}
+Retain @emph{only} the symbols listed in the file @var{filename},
+discarding all others.  @var{filename} is simply a flat file, with one
+symbol name per line.  This option is especially useful in environments
+@ifset GENERIC
+(such as VxWorks)
+@end ifset
+where a large global symbol table is accumulated gradually, to conserve
+run-time memory.
+
+@samp{-retain-symbols-file} does @emph{not} discard undefined symbols,
+or symbols needed for relocations.
+
+You may only specify @samp{-retain-symbols-file} once in the command
+line.  It overrides @samp{-s} and @samp{-S}.
+
+@ifset GENERIC
+@item -rpath @var{dir}
+@cindex runtime library search path
+@kindex -rpath
+Add a directory to the runtime library search path.  This is used when
+linking an ELF executable with shared objects.  All @code{-rpath}
+arguments are concatenated and passed to the runtime linker, which uses
+them to locate shared objects at runtime.  The @code{-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
+@code{-rpath-link} option.  If @code{-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 @code{-rpath} option may also be used on SunOS.  By default, on
+SunOS, the linker will form a runtime search patch out of all the
+@code{-L} options it is given.  If a @code{-rpath} option is used, the
+runtime search path will be formed exclusively using the @code{-rpath}
+options, ignoring the @code{-L} options.  This can be useful when using
+gcc, which adds many @code{-L} options which may be on NFS mounted
+filesystems.
+@end ifset
+
+@ifset GENERIC
+@cindex link-time runtime library search path
+@kindex -rpath-link
+@item -rpath-link @var{DIR}
+When using ELF or SunOS, one shared library may require another.  This
+happens when an @code{ld -shared} link includes a shared library as one
+of the input files.
+
+When the linker encounters such a dependency when doing a non-shared,
+non-relocateable 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 @code{-rpath-link} option
+specifies the first set of directories to search.  The
+@code{-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.
+
+The linker uses the following search paths to locate required shared
+libraries.
+@enumerate
+@item
+Any directories specified by @code{-rpath-link} options.
+@item
+Any directories specified by @code{-rpath} options.  The difference
+between @code{-rpath} and @code{-rpath-link} is that directories
+specified by @code{-rpath} options are included in the executable and
+used at runtime, whereas the @code{-rpath-link} option is only effective
+at link time.
+@item
+On an ELF system, if the @code{-rpath} and @code{rpath-link} options
+were not used, search the contents of the environment variable
+@code{LD_RUN_PATH}.
+@item
+On SunOS, if the @code{-rpath} option was not used, search any
+directories specified using @code{-L} options.
+@item
+For a native linker, the contents of the environment variable
+@code{LD_LIBRARY_PATH}.
+@item
+The default directories, normally @file{/lib} and @file{/usr/lib}.
+@end enumerate
+
+If the required shared library is not found, the linker will issue a
+warning and continue with the link.
+@end ifset
+
+@cindex partial link
+@cindex relocatable output
+@kindex -r
+@item -r 
+Generate relocatable output---i.e., generate an output file that can in
+turn serve as input to @code{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 @code{-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}.
+
+This option does the same thing as @samp{-i}.
+
+@kindex -S
+@cindex strip debugger symbols
+@item -S 
+Omit debugger symbol information (but not all symbols) from the output file.
+
+@kindex -s
+@cindex strip all symbols
+@item -s 
+Omit all symbol information from the output file.
+
+@ifset GENERIC
+@cindex runtime library name
+@kindex -soname
+@item -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.
+@end ifset
+
+@item -shared
+@cindex shared libraries
+@kindex -shared
+Create a shared library.  This is currently only supported on ELF and
+SunOS platforms.  On SunOS, the linker will automatically create a
+shared library if the @code{-e} option is not used and there are
+undefined symbols in the link.
+
+@item -sort-common
+@kindex -sort-common
+Normally, when @code{ld} places the global common symbols in the
+appropriate output sections, it sorts them by size.  First come all the
+one byte symbols, then all the two bytes, then all the four bytes, and
+then everything else.  This is to prevent gaps between symbols due to
+alignment constraints.  This option disables that sorting.
+
+@kindex split
+@item -split-by-reloc @var{count}
+Trys 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 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.
+
+@kindex split
+@item -split-by-file
+Similar to -split-by-reloc but creates a new output section for each
+input file.
+
+@item -stats
+Compute and display statistics about the operation of the linker,
+such as execution time and memory usage.
+
+@kindex -Tbss @var{org}
+@kindex -Tdata @var{org}
+@kindex -Ttext @var{org}
+@cindex segment origins, cmd line
+@item -Tbss @var{org}
+@itemx -Tdata @var{org}
+@itemx -Ttext @var{org}
+Use @var{org} as the starting address for---respectively---the
+@code{bss}, @code{data}, or the @code{text} segment of the output file.
+@var{org} must be a single hexadecimal integer;
+for compatibility with other linkers, you may omit the leading
+@samp{0x} usually associated with hexadecimal values.
+
+@kindex -T @var{script}
+@cindex script files
+@item -T @var{commandfile}
+@itemx -T@var{commandfile}
+Read link commands from the file @var{commandfile}.  These commands
+replace @code{ld}'s default link script (rather than adding
+to it), so @var{commandfile} must specify everything necessary to describe
+the target format.  @xref{Commands}.  If @var{commandfile} does not
+exist, @code{ld} looks for it in the directories specified by any
+preceding @samp{-L} options.  Multiple @samp{-T} options accumulate.
+
+@kindex -t
+@cindex verbose
+@cindex input files, displaying
+@item -t 
+Print the names of the input files as @code{ld} processes them.
+
+@kindex -traditional-format
+@cindex traditional format
+@item -traditional-format
+For some targets, the output of @code{ld} is different in some ways from
+the output of some existing linker.  This switch requests @code{ld} to
+use the traditional format instead.
+
+@cindex dbx
+For example, on SunOS, @code{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 @code{ld} to not
+combine duplicate entries.
+
+@kindex -u @var{symbol}
+@cindex undefined symbol
+@item -u @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.
+@c Nice idea, but no such command: This option is equivalent
+@c to the @code{EXTERN} linker command.
+
+@kindex -Ur
+@cindex constructors
+@item -Ur 
+For anything other than C++ programs, this option is equivalent to
+@samp{-r}: it generates relocatable output---i.e., an output file that can in
+turn serve as input to @code{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 --verbose
+@cindex version
+@item --verbose
+Display the version number for @code{ld} and list the linker emulations
+supported.  Display which input files can and cannot be opened.
+
+@kindex -v
+@kindex -V
+@cindex version
+@item -v
+@itemx -V
+Display the version number for @code{ld}.  The @code{-V} option also
+lists the supported emulations.
+
+@kindex -version
+@item -version
+Display the version number for @code{ld} and exit.
+
+@kindex -warn-comon
+@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-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 --whole-archive
+@cindex including an entire archive
+For each archive mentioned on the command line, include every object
+file in the archive in the link, rather than searching the archive for
+the required object files.  This is normally used to turn an archive
+file into a shared library, forcing every object to be included in the
+resulting shared library.
+
+@kindex -X
+@cindex local symbols, deleting
+@cindex L, deleting symbols beginning
+@item -X 
+Delete all temporary local symbols.  For most targets, this is all local
+symbols whose names begin with @samp{L}.
+
+@kindex -x
+@cindex deleting local symbols
+@item -x
+Delete all local symbols.
+
+@kindex -y @var{symbol}
+@cindex symbol tracing
+@item -y @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 -(
+@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.
+@end table
+
+@ifset UsesEnvVars
+@node Environment
+@section Environment Variables
+
+You can change the behavior of @code{ld} with the environment
+variable @code{GNUTARGET}.  
+
+@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, @code{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 ifset
+
+@node Commands
+@chapter Command Language
+
+@cindex command files
+The command language provides explicit control over the link process,
+allowing complete specification of the mapping between the linker's
+input files and its output.  It controls:
+@itemize @bullet
+@item 
+input files 
+@item 
+file formats
+@item 
+output file layout
+@item 
+addresses of sections
+@item 
+placement of common blocks
+@end itemize
+
+You may supply a command file (also known as a link script) to the
+linker either explicitly through the @samp{-T} option, or implicitly as
+an ordinary file. If the linker opens a file which it cannot recognize
+as a supported object or archive format, it reports an error.
+
+@menu
+* Scripts::                     Linker Scripts
+* Expressions::                 Expressions
+* MEMORY::                      MEMORY Command
+* SECTIONS::                    SECTIONS Command
+* Entry Point::                 The Entry Point
+* Option Commands::             Option Commands
+@end menu
+
+@node Scripts
+@section Linker Scripts
+The @code{ld} command language is a collection of statements; some are
+simple keywords setting a particular option, some are used to select and
+group input files or name output files; and two statement
+types have a fundamental and pervasive impact on the linking process.
+
+@cindex fundamental script commands
+@cindex commands, fundamental
+@cindex output file layout
+@cindex layout of output file
+The most fundamental command of the @code{ld} command language is the
+@code{SECTIONS} command (@pxref{SECTIONS}).  Every meaningful command
+script must have a @code{SECTIONS} command: it specifies a
+``picture'' of the output file's layout, in varying degrees of detail.
+No other command is required in all cases.
+
+The @code{MEMORY} command complements @code{SECTIONS} by describing the
+available memory in the target architecture.  This command is optional;
+if you don't use a @code{MEMORY} command, @code{ld} assumes sufficient
+memory is available in a contiguous block for all output.
+@xref{MEMORY}.
+
+@cindex comments
+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 Expressions
+@section Expressions
+@cindex expression syntax
+@cindex arithmetic
+Many useful commands involve arithmetic expressions.  The syntax for
+expressions in the command language is identical to that of C
+expressions, with the following features:
+@itemize @bullet
+@item 
+All expressions evaluated as integers and
+are of ``long'' or ``unsigned long'' type.
+@item 
+All constants are integers.
+@item 
+All of the C arithmetic operators are provided.
+@item 
+You may reference, define, and create global variables.
+@item 
+You may call special purpose built-in functions.
+@end itemize
+
+@menu
+* Integers::                    Integers
+* Symbols::                     Symbol Names
+* Location Counter::            The Location Counter
+* Operators::                   Operators
+* Evaluation::                  Evaluation
+* Assignment::                  Assignment: Defining Symbols
+* Arithmetic Functions::        Built-In Functions
+@end menu
+
+@node Integers
+@subsection Integers
+@cindex integer notation
+@cindex octal integers
+An octal integer is @samp{0} followed by zero or more of the octal
+digits (@samp{01234567}).
+@smallexample
+_as_octal = 0157255;
+@end smallexample
+
+@cindex decimal integers
+A decimal integer starts with a non-zero digit followed by zero or
+more digits (@samp{0123456789}).
+@smallexample
+_as_decimal = 57005;
+@end smallexample
+
+@cindex hexadecimal integers
+@kindex 0x
+A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
+more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
+@smallexample
+_as_hex = 0xdead;
+@end smallexample
+
+@cindex negative integers
+To write a negative integer, use
+the prefix operator @samp{-}; @pxref{Operators}.
+@smallexample
+_as_neg = -57005;
+@end smallexample
+
+@cindex scaled integers
+@cindex K and M integer suffixes
+@cindex M and K integer suffixes
+@cindex suffixes for integers
+@cindex integer suffixes
+Additionally the suffixes @code{K} and @code{M} may be used to scale a
+constant by 
+@c TEXI2ROFF-KILL
+@ifinfo
+@c END TEXI2ROFF-KILL
+@code{1024} or @code{1024*1024}
+@c TEXI2ROFF-KILL
+@end ifinfo
+@tex
+${\rm 1024}$ or ${\rm 1024}^2$
+@end tex
+@c END TEXI2ROFF-KILL
+respectively. For example, the following all refer to the same quantity:
+
+@smallexample
+        _fourk_1 = 4K;
+        _fourk_2 = 4096;
+        _fourk_3 = 0x1000;
+@end smallexample
+
+@node Symbols
+@subsection Symbol Names
+@cindex symbol names
+@cindex names
+@cindex quoted symbol names
+@kindex "
+Unless quoted, symbol names start with a letter, underscore, or point
+and may include any letters, underscores, digits, points,
+and hyphens.  Unquoted symbol names must not conflict with any
+keywords.  You can specify a symbol which contains odd characters or has
+the same name as a keyword, by surrounding the symbol name in double quotes:
+@smallexample
+        "SECTION" = 9;
+        "with a space" = "also with a space" + 10;
+@end smallexample
+
+Since symbols can contain many non-alphabetic characters, it is safest
+to delimit symbols with spaces.  For example, @samp{A-B} is one symbol,
+whereas @samp{A - B} is an expression involving subtraction.
+
+@node Location Counter
+@subsection The Location Counter
+@kindex .
+@cindex dot
+@cindex location counter
+@cindex current output location
+The special linker variable @dfn{dot} @samp{.} always contains the
+current output location counter. Since the @code{.} always refers to
+a location in an output section, it must always appear in an
+expression within a @code{SECTIONS} command. The @code{.} symbol
+may appear anywhere that an ordinary symbol is allowed in an
+expression, but its assignments have a side effect. Assigning a value
+to the @code{.} symbol will cause the location counter to be moved.
+@cindex holes
+This may be used to create holes in the output section.  The location
+counter may never be moved backwards.
+@smallexample
+SECTIONS
+@{
+  output :
+  @{
+  file1(.text)
+  . = . + 1000;
+  file2(.text)
+  . += 1000;
+  file3(.text)
+  @} = 0x1234;
+@}
+@end smallexample
+@noindent
+In the previous example, @code{file1} is located at the beginning of the
+output section, then there is a 1000 byte gap.  Then @code{file2}
+appears, also with a 1000 byte gap following before @code{file3} is
+loaded.  The notation @samp{= 0x1234} specifies what data to write in
+the gaps (@pxref{Section Options}).
+
+@iftex
+@vfill
+@end iftex
+
+@need 2000
+@node Operators
+@subsection Operators
+@cindex Operators for arithmetic
+@cindex arithmetic operators
+@cindex precedence in expressions
+The linker recognizes  the standard C set of arithmetic operators, with
+the standard bindings and precedence levels:
+@c TEXI2ROFF-KILL
+@ifinfo
+@c END TEXI2ROFF-KILL
+@smallexample
+precedence      associativity   Operators                Notes
+(highest)
+1               left            !  -  ~                  (1)
+2               left            *  /  %
+3               left            +  -
+4               left            >>  <<
+5               left            ==  !=  >  <  <=  >=
+6               left            &
+7               left            |
+8               left            &&
+9               left            ||
+10              right           ? :
+11              right           &=  +=  -=  *=  /=       (2)
+(lowest)
+@end smallexample
+Notes:
+(1) Prefix operators 
+(2) @xref{Assignment}
+@c TEXI2ROFF-KILL
+@end ifinfo
+@tex
+\vskip \baselineskip
+%"lispnarrowing" is the extra indent used generally for @smallexample
+\hskip\lispnarrowing\vbox{\offinterlineskip
+\hrule
+\halign
+{\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
+height2pt&\omit&&\omit&&\omit&\cr
+&Precedence&&  Associativity  &&{\rm Operators}&\cr
+height2pt&\omit&&\omit&&\omit&\cr
+\noalign{\hrule}
+height2pt&\omit&&\omit&&\omit&\cr
+&highest&&&&&\cr
+% '176 is tilde, '~' in tt font
+&1&&left&&\qquad-          \char'176\      !\qquad\dag&\cr 
+&2&&left&&*          /        \%&\cr
+&3&&left&&+          -&\cr
+&4&&left&&>>         <<&\cr
+&5&&left&&==         !=       >      <      <=      >=&\cr
+&6&&left&&\&&\cr
+&7&&left&&|&\cr
+&8&&left&&{\&\&}&\cr
+&9&&left&&||&\cr
+&10&&right&&?        :&\cr
+&11&&right&&\qquad\&=      +=       -=     *=     /=\qquad\ddag&\cr
+&lowest&&&&&\cr
+height2pt&\omit&&\omit&&\omit&\cr}
+\hrule}
+@end tex
+@iftex
+{
+@obeylines@parskip=0pt@parindent=0pt
+@dag@quad Prefix operators.
+@ddag@quad @xref{Assignment}.
+}
+@end iftex
+@c END TEXI2ROFF-KILL
+
+@node Evaluation
+@subsection Evaluation
+
+@cindex lazy evaluation
+@cindex expression evaluation order
+The linker uses ``lazy evaluation'' for expressions; it only calculates
+an expression when absolutely necessary.  The linker needs the value of
+the start address, and the 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 command file.  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.
+
+@node Assignment
+@subsection Assignment: Defining Symbols
+@cindex assignment in scripts
+@cindex symbol definition, scripts
+@cindex variables, defining
+You may create global symbols, and assign values (addresses) to global
+symbols, 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} ;
+@end table
+
+Two things distinguish assignment from other operators in @code{ld}
+expressions.
+@itemize @bullet
+@item 
+Assignment may only be used at the root of an expression;
+@samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error.
+
+@kindex ;
+@cindex semicolon
+@item 
+You must place a trailing semicolon (``@key{;}'') at the end of an
+assignment statement.
+@end itemize
+
+Assignment statements may appear:
+@itemize @bullet
+@item 
+as commands in their own right in an @code{ld} script; or
+@item 
+as independent statements within a @code{SECTIONS} command; or
+@item 
+as part of the contents of a section definition in a
+@code{SECTIONS} command.
+@end itemize
+
+The first two cases are equivalent in effect---both define a symbol with
+an absolute address.  The last case defines a symbol whose address is
+relative to a particular section (@pxref{SECTIONS}).
+
+@cindex absolute and relocatable symbols
+@cindex relocatable and absolute symbols
+@cindex symbols, relocatable and absolute
+When a linker expression is evaluated and assigned to a variable, it is
+given either an absolute or a relocatable type. An absolute expression
+type is one in which the symbol contains the value that it will have in
+the output file; a relocatable expression type is one in which the
+value is expressed as a fixed offset from the base of a section.
+
+The type of the expression is controlled by its position in the script
+file.  A symbol assigned within a section definition is created relative
+to the base of the section; a symbol assigned in any other place is
+created as an absolute symbol. Since a symbol created within a
+section definition is relative to the base of the section, it
+will remain relocatable if relocatable output is requested.  A symbol
+may be created with an absolute value even when assigned to within a
+section definition by using the absolute assignment function
+@code{ABSOLUTE}.  For example, to create an absolute symbol whose address
+is the last byte of an output section named @code{.data}:
+@smallexample
+SECTIONS@{ @dots{}
+  .data : 
+    @{
+      *(.data)
+      _edata = ABSOLUTE(.) ;
+    @} 
+@dots{} @}
+@end smallexample
+
+The linker tries to put off the evaluation of an assignment until all
+the terms in the source expression are known (@pxref{Evaluation}).  For
+instance, 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 @dfn{dot}, @samp{.} must be evaluated during 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
+SECTIONS @{ @dots{}
+  text 9+this_isnt_constant : 
+    @{ @dots{}
+    @}
+@dots{} @}
+@end smallexample
+@kindex Non constant expression
+@noindent
+will cause the error message ``@code{Non constant expression for initial
+address}''.
+
+@cindex provide
+In some cases, it is desirable for a linker script to define a symbol
+only if it is referenced, and only if it 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})}.
+
+@node Arithmetic Functions
+@subsection Arithmetic Functions
+@cindex functions in expression language
+The command language includes a number of built-in
+functions for use in link script expressions.
+@table @code
+@kindex ABSOLUTE(@var{exp})
+@cindex expression, absolute
+@item ABSOLUTE(@var{exp})
+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.
+
+@kindex ADDR(@var{section})
+@cindex section address
+@item ADDR(@var{section})
+Return the absolute address of the named @var{section}.  Your script must
+previously have defined the location of that section. In the following
+example, @code{symbol_1} and @code{symbol_2} are assigned identical
+values:
+@smallexample
+@group
+SECTIONS@{ @dots{}
+  .output1 :
+    @{ 
+    start_of_output_1 = ABSOLUTE(.);
+    @dots{}
+    @}
+  .output :
+    @{
+    symbol_1 = ADDR(.output1);
+    symbol_2 = start_of_output_1;
+    @}
+@dots{} @}
+@end group
+@end smallexample
+
+@kindex ALIGN(@var{exp})
+@cindex rounding up location counter
+@item ALIGN(@var{exp})
+Return the result of the current location counter (@code{.}) aligned to
+the next @var{exp} boundary.  @var{exp} must be an expression whose
+value is a power of two.  This is equivalent to 
+@smallexample
+(. + @var{exp} - 1) & ~(@var{exp} - 1)
+@end smallexample
+
+@code{ALIGN} doesn't change the value of the location counter---it just
+does arithmetic on it.  As an example, to align the output @code{.data}
+section to the next @code{0x2000} byte boundary after the preceding
+section and to set 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{start} attribute of a
+section definition (@pxref{Section Options}).  The second use simply
+defines the value of a variable.
+
+The built-in @code{NEXT} is closely related to @code{ALIGN}.
+
+@kindex DEFINED(@var{symbol})
+@cindex symbol defaults
+@item DEFINED(@var{symbol})
+Return 1 if @var{symbol} is in the linker global symbol table and is
+defined, otherwise return 0.  You can use this function to provide default
+values for symbols.  For example, the following command-file fragment shows how
+to set a global symbol @code{begin} to the first location in the
+@code{.text} section---but if a symbol called @code{begin} already
+existed, its value is preserved:
+
+@smallexample
+@group
+SECTIONS@{ @dots{}
+  .text : @{
+    begin = DEFINED(begin) ? begin : . ;
+    @dots{}
+  @}
+@dots{} @}
+@end group
+@end smallexample
+
+@kindex NEXT(@var{exp})
+@cindex unallocated address, next
+@item NEXT(@var{exp})
+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.
+
+@kindex SIZEOF(@var{section})
+@cindex section size
+@item SIZEOF(@var{section})
+Return the size in bytes of the named @var{section}, if that section has
+been allocated.  In the following example, @code{symbol_1} and
+@code{symbol_2} are assigned identical values:
+@c What does it return if the section hasn't been allocated?  0?
+@smallexample
+@group
+SECTIONS@{ @dots{}
+  .output @{
+    .start = . ;
+    @dots{}
+    .end = . ;
+    @}
+  symbol_1 = .end - .start ;
+  symbol_2 = SIZEOF(.output);
+@dots{} @}
+@end group
+@end smallexample
+
+@kindex SIZEOF_HEADERS
+@cindex header size
+@kindex sizeof_headers
+@item SIZEOF_HEADERS
+@itemx sizeof_headers
+Return the size in bytes of the output file's headers.  You can use this number
+as the start address of the first section, if you choose, to facilitate
+paging. 
+
+@end table
+
+@node MEMORY
+@section Memory Layout
+@kindex MEMORY
+@cindex regions of memory
+@cindex discontinuous memory
+@cindex allocating memory
+The linker's default configuration permits allocation of all available memory.
+You can override this configuration by using the @code{MEMORY} command.  The
+@code{MEMORY} command describes the location and size of blocks of
+memory in the target.  By using it carefully, you can describe which
+memory regions may be used by the linker, and which memory regions it
+must avoid.  The linker does not shuffle sections to fit into the
+available regions, but does move the requested sections into the correct
+regions and issue errors when the regions become too full.  
+
+A command file may contain at most one use of the @code{MEMORY}
+command; however, you can define as many blocks of memory within it as
+you wish.  The syntax is:
+        
+@smallexample
+@group
+MEMORY 
+  @{
+    @var{name} (@var{attr}) : ORIGIN = @var{origin}, LENGTH = @var{len}
+    @dots{}
+  @}
+@end group
+@end smallexample
+@table @code
+@cindex naming memory regions
+@item @var{name}
+is a name used internally by the linker to refer to the region. Any
+symbol name may be used.  The region names are stored in a separate
+name space, and will not conflict with symbols, file names or section
+names.  Use distinct names to specify multiple regions.
+
+@cindex memory region attributes
+@item (@var{attr})
+is an optional list of attributes, permitted for compatibility with the
+AT&T linker but not used by @code{ld} beyond checking that the
+attribute list is valid.  Valid attribute lists must be made up of the
+characters ``@code{LIRWX}''.  If you omit the attribute list, you may
+omit the parentheses around it as well.
+
+@kindex ORIGIN =
+@kindex o =
+@kindex org =
+@item @var{origin}
+is the start address of the region in physical memory.  It is
+an expression that must evaluate to a constant before
+memory allocation is performed. The keyword @code{ORIGIN} may be
+abbreviated to @code{org} or @code{o} (but not, for example, @samp{ORG}).
+
+@kindex LENGTH =
+@kindex len =
+@kindex l =
+@item @var{len}
+is the size in bytes of the region (an expression).
+The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
+@end table 
+
+For example, to specify that memory has two regions available for
+allocation---one starting at 0 for 256 kilobytes, and the other
+starting at @code{0x40000000} for four megabytes:
+
+@smallexample
+@group
+MEMORY 
+  @{
+  rom : ORIGIN = 0, LENGTH = 256K
+  ram : org = 0x40000000, l = 4M
+  @}
+@end group
+@end smallexample
+
+Once you have defined a region of memory named @var{mem}, you can direct
+specific output sections there by using a command ending in
+@samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section
+Options}).  If the combined output sections directed to a region are too
+big for the region, the linker will issue an error message.
+
+@node SECTIONS
+@section Specifying Output Sections
+
+@kindex SECTIONS
+The @code{SECTIONS} command controls exactly where input sections are
+placed into output sections, their order in the output file, and to
+which output sections they are allocated.
+
+You may use at most one @code{SECTIONS} command in a script file,
+but you can have as many statements within it as you wish.  Statements
+within the @code{SECTIONS} command can do one of three things:
+
+@itemize @bullet
+@item 
+define the entry point;
+
+@item 
+assign a value to a symbol;
+
+@item 
+describe the placement of a named output section, and which input
+sections go into it.
+@end itemize
+
+You can also use the first two operations---defining the entry point and
+defining symbols---outside the @code{SECTIONS} command: @pxref{Entry
+Point}, and @pxref{Assignment}.  They are permitted here as well for
+your convenience in reading the script, so that symbols and the entry
+point can be defined at meaningful points in your output-file layout.
+
+If you do not use a @code{SECTIONS} command, the linker places 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.
+
+@menu
+* Section Definition::          Section Definitions
+* Section Placement::           Section Placement
+* Section Data Expressions::    Section Data Expressions
+* Section Options::             Optional Section Attributes
+@end menu
+
+@node Section Definition
+@subsection Section Definitions
+@cindex section definition
+The most frequently used statement in the @code{SECTIONS} command is
+the @dfn{section definition}, which specifies the
+properties of an output section: its location, alignment, contents,
+fill pattern, and target memory region.  Most of
+these specifications are optional; the simplest form of a section
+definition is
+@smallexample
+SECTIONS @{ @dots{}
+  @var{secname} : @{
+    @var{contents}
+  @}
+@dots{} @}
+@end smallexample
+@cindex naming output sections
+@noindent
+@var{secname} is the name of the output section, and @var{contents} a
+specification of what goes there---for example, a list of input files or
+sections of input files (@pxref{Section Placement}).  As you might
+assume, the whitespace shown is optional.  You do need the colon
+@samp{:} and the braces @samp{@{@}}, however.
+
+@var{secname} 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 @code{.text}, @code{.data} or
+@code{.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 any name which does not conform to the standard
+@code{ld} symbol name syntax must be quoted.
+@xref{Symbols, , Symbol Names}.
+
+The linker will not create output sections which do not have any
+contents.  This is for convenience when referring to input sections that
+may or may not exist.  For example,
+@smallexample
+.foo @{ *(.foo @}
+@end smallexample
+will only create a @samp{.foo} section in the output file if there is a
+@samp{.foo} section in at least one input file.
+
+@node Section Placement
+@subsection Section Placement
+
+@cindex contents of a section
+In a section definition, you can specify the contents of an output
+section by listing particular input files, by listing particular
+input-file sections, or by a combination of the two.  You can also place
+arbitrary data in the section, and define symbols relative to the
+beginning of the section.
+
+The @var{contents} of a section definition may include any of the
+following kinds of statement.  You can include as many of these as you
+like in a single section definition, separated from one another by
+whitespace. 
+
+@table @code
+@kindex @var{filename}
+@cindex input files, section defn
+@cindex files, including in output sections
+@item @var{filename}
+You may simply name a particular input file to be placed in the current
+output section; @emph{all} sections from that file are placed in the
+current section definition.  If the file name has already been mentioned
+in another section definition, with an explicit section name list, then
+only those sections which have not yet been allocated are used.
+
+To specify a list of particular files by name:
+@smallexample
+.data : @{ afile.o bfile.o cfile.o @}
+@end smallexample
+@noindent
+The example also illustrates that multiple statements can be included in
+the contents of a section definition, since each file name is a separate
+statement. 
+
+@kindex @var{filename}(@var{section})
+@cindex files and sections, section defn
+@item @var{filename}( @var{section} )
+@itemx @var{filename}( @var{section}, @var{section}, @dots{} )
+@itemx @var{filename}( @var{section} @var{section} @dots{} )
+You can name one or more sections from your input files, for
+insertion in the current output section.  If you wish to specify a list
+of input-file sections inside the parentheses, you may separate the
+section names by either commas or whitespace.
+
+@cindex input sections to output section
+@kindex *(@var{section})
+@item * (@var{section})
+@itemx * (@var{section}, @var{section}, @dots{})
+@itemx * (@var{section} @var{section} @dots{})
+Instead of explicitly naming particular input files in a link control
+script, you can refer to @emph{all} files from the @code{ld} command
+line: use @samp{*} instead of a particular file name before the
+parenthesized input-file section list.  
+
+If you have already explicitly included some files by name, @samp{*}
+refers to all @emph{remaining} files---those whose places in the output
+file have not yet been defined.
+
+For example, to copy sections @code{1} through @code{4} from an Oasys file
+into the @code{.text} section of an @code{a.out} file, and sections @code{13}
+and @code{14} into the @code{.data} section:
+@smallexample
+@group
+SECTIONS @{
+  .text :@{
+    *("1" "2" "3" "4")
+  @}
+  
+  .data :@{
+    *("13" "14")
+  @}
+@}
+@end group
+@end smallexample
+
+@cindex @code{[@var{section}@dots{}]}, not supported
+@samp{[ @var{section} @dots{} ]} used to be accepted as an alternate way
+to specify named sections from all unallocated input files.  Because
+some operating systems (VMS) allow brackets in file names, that notation
+is no longer supported.
+
+@cindex uninitialized data
+@cindex commons in output
+@kindex *( COMMON )
+@item @var{filename}@code{( COMMON )}
+@itemx *( COMMON )
+Specify where in your output file to place uninitialized data
+with this notation.  @code{*(COMMON)} by itself refers to all
+uninitialized data from all input files (so far as it is not yet
+allocated); @var{filename}@code{(COMMON)} refers to uninitialized data
+from a particular file.  Both are special cases of the general
+mechanisms for specifying where to place input-file sections:
+@code{ld} permits you to refer to uninitialized data as if it
+were in an input-file section named @code{COMMON}, regardless of the
+input file's format.
+@end table
+
+For example, the following command script arranges the output file into
+three consecutive sections, named @code{.text}, @code{.data}, and
+@code{.bss}, taking the input for each from the correspondingly named
+sections of all the input files:
+
+@smallexample
+@group
+SECTIONS @{ 
+  .text : @{ *(.text) @}
+  .data : @{ *(.data) @} 
+  .bss :  @{ *(.bss)  *(COMMON) @} 
+@} 
+@end group
+@end smallexample
+
+The following example reads all of the sections from file @code{all.o}
+and places them at the start of output section @code{outputa} which
+starts at location @code{0x10000}. All of section @code{.input1} from
+file @code{foo.o} follows immediately, in the same output section.  All
+of section @code{.input2} from @code{foo.o} goes into output section
+@code{outputb}, followed by section @code{.input1} from @code{foo1.o}.
+All of the remaining @code{.input1} and @code{.input2} sections from any
+files are written to output section @code{outputc}.
+
+@smallexample
+@group
+SECTIONS @{
+  outputa 0x10000 :
+    @{
+    all.o
+    foo.o (.input1)
+    @}
+  outputb :
+    @{
+    foo.o (.input2)
+    foo1.o (.input1)
+    @}
+  outputc :
+    @{
+    *(.input1)
+    *(.input2)
+    @}
+@}
+@end group
+@end smallexample        
+
+@node Section Data Expressions
+@subsection Section Data Expressions
+
+@cindex expressions in a section
+The foregoing statements arrange, in your output file, data originating
+from your input files.  You can also place data directly in an output
+section from the link command script.  Most of these additional
+statements involve expressions; @pxref{Expressions}.  Although these
+statements are shown separately here for ease of presentation, no such
+segregation is needed within a section definition in the @code{SECTIONS}
+command; you can intermix them freely with any of the statements we've
+just described.
+
+@table @code
+@cindex input filename symbols
+@cindex filename symbols
+@kindex CREATE_OBJECT_SYMBOLS
+@item CREATE_OBJECT_SYMBOLS
+Create a symbol for each input file
+in the current section, set to the address of the first byte of
+data written from that input file.  For instance, with @code{a.out}
+files it is conventional to have a symbol for each input file.  You can
+accomplish this by defining the output @code{.text} section as follows:
+@smallexample
+@group
+SECTIONS @{
+  .text 0x2020 :
+     @{
+    CREATE_OBJECT_SYMBOLS
+    *(.text)
+    _etext = ALIGN(0x2000);
+    @}
+  @dots{}
+@}
+@end group
+@end smallexample
+
+If @code{sample.ld} is a file containing this script, and @code{a.o},
+@code{b.o}, @code{c.o}, and @code{d.o} are four input files with
+contents like the following---
+@smallexample
+@group
+/* a.c */
+
+afunction() @{ @}
+int adata=1;
+int abss;
+@end group
+@end smallexample
+
+@noindent
+@samp{ld -M -T sample.ld a.o b.o c.o d.o} would create a map like this,
+containing symbols matching the object file names:
+@smallexample
+00000000 A __DYNAMIC
+00004020 B _abss
+00004000 D _adata
+00002020 T _afunction
+00004024 B _bbss
+00004008 D _bdata
+00002038 T _bfunction
+00004028 B _cbss
+00004010 D _cdata
+00002050 T _cfunction
+0000402c B _dbss
+00004018 D _ddata
+00002068 T _dfunction
+00004020 D _edata
+00004030 B _end
+00004000 T _etext
+00002020 t a.o
+00002038 t b.o
+00002050 t c.o
+00002068 t d.o
+@end smallexample
+
+@kindex @var{symbol} = @var{expression} ;
+@kindex @var{symbol} @var{f}= @var{expression} ;
+@item @var{symbol} = @var{expression} ;
+@itemx @var{symbol} @var{f}= @var{expression} ;
+@var{symbol} is any symbol name (@pxref{Symbols}).  ``@var{f}='' 
+refers to any of the operators @code{&= += -= *= /=} which combine
+arithmetic and assignment.
+
+@cindex assignment, in section defn
+When you assign a value to a symbol within a particular section
+definition, the value is relative to the beginning of the section
+(@pxref{Assignment}).  If you write
+
+@smallexample
+@group
+SECTIONS @{
+  abs = 14 ;
+  @dots{}
+  .data : @{ @dots{} rel = 14 ; @dots{} @}
+  abs2 = 14 + ADDR(.data);
+  @dots{}
+@}
+@end group
+@end smallexample
+
+@c FIXME:  Try above example!
+@noindent
+@code{abs} and @code{rel} do not have the same value; @code{rel} has the
+same value as @code{abs2}.
+
+@kindex BYTE(@var{expression})
+@kindex SHORT(@var{expression})
+@kindex LONG(@var{expression})
+@kindex QUAD(@var{expression})
+@cindex direct output
+@item BYTE(@var{expression})
+@itemx SHORT(@var{expression})
+@itemx LONG(@var{expression})
+@itemx QUAD(@var{expression})
+By including one of these four statements in a section definition, you
+can explicitly place one, two, four, or eight bytes (respectively) at
+the current address of that section.  @code{QUAD} is only supported when
+using a 64 bit host or target.
+
+@ifclear SingleFormat
+Multiple-byte quantities are represented in whatever byte order is
+appropriate for the output file format (@pxref{BFD}).
+@end ifclear
+
+@kindex FILL(@var{expression})
+@cindex holes, filling
+@cindex unspecified memory
+@item FILL(@var{expression})
+Specify the ``fill pattern'' for the current section.  Any otherwise
+unspecified regions of memory within the section (for example, regions
+you skip over by assigning a new value to the location counter @samp{.})
+are filled with the two least significant bytes from the
+@var{expression} argument.  A @code{FILL} statement covers memory
+locations @emph{after} the point 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.
+@end table
+
+@node Section Options
+@subsection Optional Section Attributes
+@cindex section defn, full syntax
+Here is the full syntax of a section definition, including all the
+optional portions:
+
+@smallexample
+@group
+SECTIONS @{
+@dots{}
+@var{secname} @var{start} BLOCK(@var{align}) (NOLOAD) : AT ( @var{ldadr} )
+  @{ @var{contents} @} >@var{region} =@var{fill}
+@dots{}
+@}
+@end group
+@end smallexample
+
+@var{secname} and @var{contents} are required.  @xref{Section
+Definition}, and @pxref{Section Placement} for details on
+@var{contents}.  The remaining elements---@var{start},
+@code{BLOCK(@var{align)}}, @code{(NOLOAD)}, @code{AT ( @var{ldadr} )},
+@code{>@var{region}}, and @code{=@var{fill}}---are all optional.
+
+@table @code
+@cindex start address, section
+@cindex section start
+@cindex section address
+@item @var{start} 
+You can force the output section to be loaded at a specified address by
+specifying @var{start} immediately following the section name.
+@var{start} can be represented as any expression. The following
+example generates section @var{output} at location
+@code{0x40000000}:
+
+@smallexample
+@group
+SECTIONS @{
+  @dots{}
+  output 0x40000000: @{
+    @dots{}
+    @}
+  @dots{}
+@}
+@end group
+@end smallexample
+
+@kindex BLOCK(@var{align})
+@cindex section alignment
+@cindex aligning sections
+@item BLOCK(@var{align})
+You can include @code{BLOCK()} specification to advance
+the location counter @code{.} prior to the beginning of the section, so
+that the section will begin at the specified alignment.  @var{align} is
+an expression.
+
+@kindex NOLOAD
+@cindex prevent unnecessary loading
+@cindex loading, preventing
+@item (NOLOAD)
+Use @samp{(NOLOAD)} to prevent a section from being loaded into memory
+each time it is accessed.  For example, in the script sample below, the
+@code{ROM} segment is addressed at memory location @samp{0} and does not
+need to be loaded into each object file:
+
+@smallexample
+@group
+SECTIONS @{
+  ROM  0  (NOLOAD)  : @{ @dots{} @}
+  @dots{}
+@}
+@end group
+@end smallexample
+
+@kindex AT ( @var{ldadr} )
+@cindex specify load address
+@cindex load address, specifying
+@item AT ( @var{ldadr} )
+The expression @var{ldadr} that follows the @code{AT} keyword specifies
+the load address of the section.  The default (if you do not use the
+@code{AT} keyword) is to make the load address the same as the
+relocation address.  This feature is designed to make it easy to build a
+ROM image.  For example, this @code{SECTIONS} definition creates two
+output sections: one called @samp{.text}, which starts at @code{0x1000},
+and one called @samp{.mdata}, which is loaded at the end of the
+@samp{.text} section even though its relocation address is
+@code{0x2000}.  The symbol @code{_data} is defined with the value
+@code{0x2000}:
+
+@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 C programs, usually @code{crt0})
+for use with a ROM generated this way has to include something like
+the following, to copy the initialized data from the ROM image to its runtime
+address:
+
+@smallexample
+@group
+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
+
+@kindex >@var{region}
+@cindex section, assigning to memory region
+@cindex memory regions and sections
+@item >@var{region}
+Assign this section to a previously defined region of memory.  
+@xref{MEMORY}.
+
+@kindex =@var{fill}
+@cindex section fill pattern
+@cindex fill pattern, entire section
+@item =@var{fill}
+Including @code{=@var{fill}} in a section definition specifies the
+initial fill value for that section.  You may use any expression to
+specify @var{fill}.  Any unallocated holes in the current output section
+when written to the output file will be filled with the two least
+significant bytes of the value, repeated as necessary.  You can also
+change the fill value with a @code{FILL} statement in the @var{contents}
+of a section definition.
+
+@end table
+
+@node Entry Point
+@section The Entry Point
+@kindex ENTRY(@var{symbol})
+@cindex start of execution
+@cindex first instruction
+The linker command language includes a command specifically for
+defining the first executable instruction in an output file (its
+@dfn{entry point}).  Its argument is a symbol name:
+@smallexample
+ENTRY(@var{symbol})
+@end smallexample
+
+Like symbol assignments, the @code{ENTRY} command may be placed either
+as an independent command in the command file, or among the section
+definitions within the @code{SECTIONS} command---whatever makes the most
+sense for your layout.
+
+@cindex entry point, defaults
+@code{ENTRY} is only one of several ways of choosing the entry point.
+You may indicate it in any of the following ways (shown in descending
+order of priority: methods higher in the list override methods lower down).
+@itemize @bullet
+@item 
+the @samp{-e} @var{entry} command-line option;
+@item 
+the @code{ENTRY(@var{symbol})} command in a linker control script;
+@item 
+the value of the symbol @code{start}, if present;
+@item 
+the address of the first byte of the @code{.text} section, if present;
+@item 
+The address @code{0}.
+@end itemize
+
+For example, you can use these rules to generate an entry point with an
+assignment statement: if no symbol @code{start} is defined within your
+input files, you can simply define it, assigning it an appropriate
+value---
+
+@smallexample
+start = 0x2020;
+@end smallexample
+
+@noindent
+The example shows an absolute address, but you can use any expression.
+For example, if your input object files use some other symbol-name
+convention for the entry point, you can just assign the value of
+whatever symbol contains the start address to @code{start}:
+
+@smallexample
+start = other_symbol ;
+@end smallexample
+
+@node Option Commands
+@section Option Commands
+The command language includes a number of other commands that you can
+use for specialized purposes.  They are similar in purpose to
+command-line options.
+
+@table @code
+@kindex CONSTRUCTORS
+@cindex C++ constructors, arranging in link
+@cindex constructors, arranging in link
+@item CONSTRUCTORS
+This command ties up C++ style constructor and destructor records.  The
+details of the constructor representation vary from one object format to
+another, but usually lists of constructors and destructors appear as
+special sections.  The @code{CONSTRUCTORS} command specifies where the
+linker is to place the data from these sections, relative to the rest of
+the linked output.  Constructor data is marked by the symbol
+@w{@code{__CTOR_LIST__}} at the start, and @w{@code{__CTOR_LIST_END}} at
+the end; destructor data is bracketed similarly, between
+@w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_LIST_END}}.  (The compiler
+must arrange to actually run this code; @sc{gnu} C++ calls constructors from
+a subroutine @code{__main}, which it inserts automatically into the
+startup code for @code{main}, and destructors from @code{_exit}.)
+
+@need 1000
+@kindex FLOAT
+@kindex NOFLOAT
+@item FLOAT
+@itemx NOFLOAT
+These keywords were used in some older linkers to request a particular
+math subroutine library.  @code{ld} doesn't use the keywords, assuming
+instead that any necessary subroutines are in libraries specified using
+the general mechanisms for linking to archives; but to permit the use of
+scripts that were written for the older linkers, the keywords
+@code{FLOAT} and @code{NOFLOAT} are accepted and ignored.
+
+@kindex FORCE_COMMON_ALLOCATION
+@cindex common allocation
+@item FORCE_COMMON_ALLOCATION
+This command has the same effect as the @samp{-d} command-line option:
+to make @code{ld} assign space to common symbols even if a relocatable
+output file is specified (@samp{-r}).
+
+@kindex INPUT ( @var{files} )
+@cindex binary input files
+@item INPUT ( @var{file}, @var{file}, @dots{} )
+@itemx INPUT ( @var{file} @var{file} @dots{} )
+Use this command to include binary input files in the link, without
+including them in a particular section definition.  
+Specify the full name for each @var{file}, including @samp{.a} if
+required.
+
+@code{ld} searches for each @var{file} through the archive-library
+search path, just as for files you specify on the command line.
+See the description of @samp{-L} in @ref{Options,,Command Line
+Options}.
+
+If you use @samp{-l@var{file}}, @code{ld} will transform the name to
+@code{lib@var{file}.a} as with the command line argument @samp{-l}.
+
+@kindex GROUP ( @var{files} )
+@cindex grouping input files
+@item GROUP ( @var{file}, @var{file}, @dots{} )
+@itemx GROUP ( @var{file} @var{file} @dots{} )
+This 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}.
+
+@ignore
+@kindex MAP ( @var{name} )
+@item MAP ( @var{name} )
+@c MAP(...) appears to look for an F in the arg, ignoring all other
+@c chars; if it finds one, it sets "map_option_f" to true.  But nothing
+@c checks map_option_f.  Apparently a stub for the future...
+@end ignore
+
+@kindex OUTPUT ( @var{filename} )
+@cindex naming the output file
+@item OUTPUT ( @var{filename} )
+Use this command to name the link output file @var{filename}.  The
+effect of @code{OUTPUT(@var{filename})} is identical to the effect of
+@w{@samp{-o @var{filename}}}, which overrides it.  You can use this
+command to supply a default output-file name other than @code{a.out}.
+
+@ifclear SingleFormat
+@kindex OUTPUT_ARCH ( @var{bfdname} )
+@cindex machine architecture, output
+@item OUTPUT_ARCH ( @var{bfdname} )
+Specify a particular output machine architecture, with one of the names
+used by the BFD back-end routines (@pxref{BFD}).  This command is often
+unnecessary; the architecture is most often set implicitly by either the
+system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT}
+command.
+
+@kindex OUTPUT_FORMAT ( @var{bfdname} )
+@cindex format, output file
+@item OUTPUT_FORMAT ( @var{bfdname} )
+When @code{ld} is configured to support multiple object code formats,
+you can use this command to specify a particular output format.
+@var{bfdname} is one of the names used by the BFD back-end routines
+(@pxref{BFD}).  The effect is identical to the effect of the
+@samp{-oformat} command-line option.  This selection affects only
+the output file; the related command @code{TARGET} affects primarily
+input files.
+@end ifclear
+
+@kindex SEARCH_DIR ( @var{path} )
+@cindex path for libraries
+@cindex search path, libraries
+@item SEARCH_DIR ( @var{path} )
+Add @var{path} to the list of paths where @code{ld} looks for
+archive libraries.  @code{SEARCH_DIR(@var{path})} has the same
+effect as @samp{-L@var{path}} on the command line.
+
+@kindex STARTUP ( @var{filename} )
+@cindex first input file
+@item STARTUP ( @var{filename} )
+Ensure that @var{filename} is the first input file used in the link
+process. 
+
+@ifclear SingleFormat
+@cindex input file format
+@kindex TARGET ( @var{format} )
+@item TARGET ( @var{format} )
+When @code{ld} is configured to support multiple object code formats,
+you can use this command to change the input-file object code format
+(like the command-line option @samp{-b} or its synonym @samp{-format}).
+The argument @var{format} is one of the strings used by BFD to name
+binary formats.  If @code{TARGET} is specified but @code{OUTPUT_FORMAT}
+is not, the last @code{TARGET} argument is also used as the default
+format for the @code{ld} output file.  @xref{BFD}.
+
+@kindex GNUTARGET
+If you don't use the @code{TARGET} command, @code{ld} uses the value of
+the environment variable @code{GNUTARGET}, if available, to select the
+output file format.  If that variable is also absent, @code{ld} uses
+the default format configured for your machine in the BFD libraries.
+@end ifclear
+@end table
+
+@ifset GENERIC
+@node Machine Dependent
+@chapter Machine Dependent Features
+
+@cindex machine dependencies
+@code{ld} has additional features on some platforms; the following
+sections describe them.  Machines where @code{ld} has no additional
+functionality are not listed.
+
+@menu
+* H8/300::                      @code{ld} and the H8/300
+* i960::                        @code{ld} and the Intel 960 family
+@end menu
+@end ifset
+
+@c FIXME!  This could use @raisesections/@lowersections, but there seems to be a conflict
+@c         between those and node-defaulting.
+@ifset H8300
+@ifclear GENERIC
+@raisesections
+@end ifclear
+@node H8/300
+@section @code{ld} and the H8/300
+
+@cindex H8/300 support
+For the H8/300, @code{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
+@code{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?
+@code{ld} finds all @code{mov.b} instructions which use the
+sixteen-bit absolute address form, but refer to the top
+page of memory, and changes them to use the eight-bit address form.
+(That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
+@samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
+top page of memory).
+@end table
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifclear GENERIC
+@ifset Hitachi
+@c This stuff is pointless to say unless you're especially concerned
+@c with Hitachi chips; don't enable it for generic case, please.
+@node Hitachi
+@chapter @code{ld} and other Hitachi chips
+
+@code{ld} also supports the H8/300H, the H8/500, and the Hitachi SH.  No
+special features, commands, or command-line options are required for
+these chips.
+@end ifset
+@end ifclear
+
+@ifset I960
+@ifclear GENERIC
+@raisesections
+@end ifclear
+@node i960
+@section @code{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 @code{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 @code{-relax} on i960
+@cindex relaxing on i960
+@code{ld} supports the @samp{-relax} option for the i960 family.  If you
+specify @samp{-relax}, @code{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.  @code{ld} also turns @code{cal}
+instructions into @code{bal} instructions when it determines that the
+target subroutine is a leaf routine (that is, the target subroutine does
+not itself call any subroutines).
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifclear 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 MRI
+@appendix MRI Compatible Script Files
+@cindex MRI compatibility
+To aid users making the transition to @sc{gnu} @code{ld} from the MRI
+linker, @code{ld} can use MRI compatible linker scripts as an
+alternative to the more general-purpose linker scripting language
+described in @ref{Commands,,Command Language}.  MRI compatible linker
+scripts have a much simpler command set than the scripting language
+otherwise used with @code{ld}.  @sc{gnu} @code{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, @code{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, @code{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
+@code{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 @code{ld}
+command line.
+
+@cindex @code{NAME} (MRI)
+@item NAME @var{output-name}
+@var{output-name} is the name for the program produced by @code{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, @code{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 Index
+@unnumbered Index
+
+@printindex cp
+
+@tex
+% I think something like @colophon should be in texinfo.  In the
+% meantime:
+\long\def\colophon{\hbox to0pt{}\vfill
+\centerline{The body of this manual is set in}
+\centerline{\fontname\tenrm,}
+\centerline{with headings in {\bf\fontname\tenbf}}
+\centerline{and examples in {\tt\fontname\tentt}.}
+\centerline{{\it\fontname\tenit\/} and}
+\centerline{{\sl\fontname\tensl\/}}
+\centerline{are used for emphasis.}\vfill}
+\page\colophon
+% Blame: doc@cygnus.com, 28mar91.
+@end tex
+
+
+@contents
+@bye
+
+