Updated, amplified, and reorganized linker manual. Option-flag

description believed complete as of today; still holes---small
ones---in "commands" section.  BFD section also needs better table of
supported archs and formats; see FIXMEs for scattered q's and
desiderata.

1 files changed, 1044 insertions, 577 deletions

diff --git a/ld/ld.texinfo b/ld/ld.texinfo
index 1764ad507c..5bdbc53261 100644
--- a/ld/ld.texinfo
+++ b/ld/ld.texinfo
@@ -1,14 +1,60 @@
 \input texinfo
-@parindent=0pt
-@setfilename gld
-@c @@setchapternewpage odd
-@settitle GLD, The GNU linker
+@setfilename gld.info
+@c $Id$
+@syncodeindex ky cp
+@ifinfo
+This file documents the GNU linker GLD.
+
+Copyright (C) 1991 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.
+
+@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
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU General Public License'' is included exactly as
+in the original, and provided 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,
+except that the section entitled ``GNU General Public License'' may be
+included in a translation approved by the author instead of in the
+original English.
+@end ifinfo
+@setchapternewpage odd
+@settitle GLD, the GNU linker
 @titlepage
 @title{gld}
-@subtitle{The gnu loader}
+@subtitle{The GNU linker}
 @sp 1
-@subtitle Second Edition---gld version 2.0
-@subtitle January 1991
+@subtitle Second Edition---@code{gld} version 2.0
+@subtitle April 1991
+@author {Steve Chamberlain, Roland Pesch}
+@author {Cygnus Support}
+@page
+
+@tex
+\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
+\xdef\manvers{\$Revision$}  % For use in headers, footers too
+{\parskip=0pt
+\hfill Cygnus Support\par
+\hfill {\it GLD, the GNU linker}, \manvers\par
+\hfill \TeX{}info \texinfoversion\par
+\hfill steve\@cygnus.com, pesch\@cygnus.com\par
+}
+\global\parindent=0pt % Steve likes it this way.
+@end tex
+
 @vskip 0pt plus 1filll
 Copyright @copyright{} 1991 Free Software Foundation, Inc.
 
@@ -23,91 +69,85 @@ 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.
-
-@author {Steve Chamberlain}
-@author {Cygnus Support}
-@author {steve@@cygnus.com}
 @end titlepage
+@c FIXME: Talk about importance of *order* of args, cmds to linker!
 
 @node Top,,,
-@comment  node-name,  next,  previous,  up
 @ifinfo
 This file documents the GNU linker gld.
 @end ifinfo
 
-@c chapter What does a linker do ?
-@c chapter Command Language
-@noindent
+@node Overview,,,
 @chapter Overview
 
+@code{gld} combines a number of object and archive files, relocates
+their data and ties up symbol references. Often the last step in
+building a new compiled program to run is a call to @code{gld}.
 
-The @code{gld} command combines a number of object and archive files,
-relocates their data and ties up symbol references. Often the last
-step in building a new compiled program to run is a call to @code{gld}.
-
-The @code{gld} command accepts Linker Command Language files in
-a superset of AT+T's Link Editor Command Language syntax,
-to provide explict and total control over the linking process.
+@code{gld} 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.
 
 This version of @code{gld} uses the general purpose @code{bfd} libraries
-to operate on object files. This allows @code{gld} to read and
-write any of the formats supported by @code{bfd}, different
-formats may be linked together producing any available object file. 
+to operate on object files. This allows @code{gld} 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 a list of formats
+supported on various architectures.
 
-Supported formats:
-@itemize @bullet
-@item
-Sun3 68k a.out
-@item 
-IEEE-695 68k Object Module Format
-@item 
-Oasys 68k Binary Relocatable Object File Format
-@item 
-Sun4 sparc a.out
-@item 
-88k bcs coff
-@item 
-i960 coff little endian
-@item 
-i960 coff big endian
-@item 
-i960 b.out little endian
-@item 
-i960 b.out big endian
-@item
-s-records
-@end itemize
- 
-When linking similar formats, @code{gld} maintains all debugging
-information. 
+When linking formats with equivalent representations of debugging
+information (typically variations on one format), @code{gld} maintains
+all debugging information.
 
+@node Invocation,,,
 @chapter Command line options
 
+@c FIXME: -D, -N, -z, -f from older GNU linker, but not currently in new;
+@c FIXME...steve is currently thinking about whether to add them.  Maybe
+@c FIXME...remove from document.
+@example
+gld [-o @var{output} ] @var{objfiles}@dots{}
+    [ -A@var{architecture} ]  [ -b @var{output-format} ]  [ -Bstatic ]  
+    [ -c @var{commandfile} ]  [ -D @var{datasize} ]  
+    [ -d | -dc | -dp ]  [ -defsym @var{symbol} = @var{expression} ]
+    [ -e @var{entry} ]  [ -f @var{fill} ]  [ -F ]  [ -F @var{format} ]
+    [ -format @var{output-format} ]  [ -g ]  [ -i ]
+    [ -l@var{ar} ]  [ -L@var{searchdir} ]  [ -M | -m ]  
+    [ -N | -n | -z ]  [ -noinhibit-exec ]  [ -R @var{filename} ]
+    [ -r | -Ur ]  [ -S ]  [ -s ]  
+    [ SCRIPT  @dots{}  ENDSCRIPT ]  [ SCRIPT  @dots{}  @@ ]
+    [ -T @var{commandfile} ]  
+    [ -Ttext @var{textorg} ]  [ -Tdata @var{dataorg} ]  [ -Tbss @var{bssorg} ]
+    [ -t ]  [ -u @var{sym}]  [-v]  [ -X ]  [ -x ] 
+@end example
+
+This plethora of command-line options may seem intimidating, but in
+actual practice few of them are used in any particular context.
+For instance, a frequent use of @code{gld} is to link standard Unix
+object files on a standard, supported Unix system.  On such a system, to
+link a file @code{hello.o}:
 @example
-  gld [ -Bstatic ]  [ -D @var{datasize} ] 
-      [ -c @var{filename} ]
-      [ -d ]  | [ -dc ] | [ -dp ]
-      [ -i ]
-      [ -e @var{entry} ]  [ -l @var{arch} ]  [ -L @var{searchdir} ]  [ -M ]  
-      [ -N | -n | -z ]  [ -noinhibit-exec ]  [ -r ]  [ -S ]  [ -s ]  
-      [ -f @var{fill} ]
-      [ -T @var{textorg} ]  [ -Tdata @var{dataorg} ]  [ -t ]  [ -u @var{sym}]
-      [ -X ]  [ -x ] 
-      [-o @var{output} ] @var{objfiles}@dots{}
+$ gld -o output /lib/crt0.o hello.o -lc
 @end example
+This tells @code{gld} to produce a file called @code{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.
 
-Command-line options to GNU @code{gld} may be specified in any order, and
+The command-line options to @code{gld} may be specified in any order, and
 may be repeated at will.  For the most part, repeating an option with a
 different argument will either have no further effect, or override prior
 occurrences (those further to the left on the command line) of an
 option.  
 
-The exceptions which may meaningfully be present several times
+The exceptions---which may meaningfully be used more than once---
 are @code{-L}, @code{-l}, and @code{-u}.
+@c FIXME: probably some new opts can be repeated meaningfully too.
 
-@var{objfiles} may follow, precede, or be mixed in with
-command-line options; save that an @var{objfiles} argument may not be
-placed between an option flag and its argument.
+The list of object files to be linked together, shown as @var{objfiles},
+may follow, precede, or be mixed in with command-line options; save that
+an @var{objfiles} argument may not be placed between an option flag and
+its argument.
 
 Option arguments must follow the option letter without intervening
 whitespace, or be given as separate arguments immediately following the
@@ -117,13 +157,52 @@ option that requires them.
 @item @var{objfiles}@dots{}
 The object files @var{objfiles} to be linked; at least one must be specified.
 
+@item -A@var{architecture}
+In the current release of @code{gld}, this option is useful only for the
+Intel 960 family of architectures.  In that context, the
+@var{architecture} argument is one of the two-letter names identifying
+members of the 960 family; the option specifies the desired output
+target, and warns of any incompatible instructions in the input files.
+It also selects archive libraries supporting the particular
+architecture; its effect in this regard is similar to that of @code{-l}, save
+that @code{-A}@var{architecture} triggers a two-level search; first for a
+library with exactly the name you specify as @var{architecture}, and if
+that fails, for a library named with the @code{-l} convention---i.e.,
+@samp{lib@var{architecture}.a}.   
+
+Future releases of @code{gld} may support similar functionality for
+other architecture families.
+
+@item -b @var{output-format}
+Specify the desired output-file binary format.  You don't usually need
+to specify this.  @code{gld} can determine
+the format of @emph{input} files by inspection, and---in the most frequent
+case, when all input files have the same format, @code{gld} selects the
+same format for output files by default.  
+
+You can use this option if you need to link a variety of object formats
+together, or if you wish to force a different output format even though
+you have homogeneous input files.
+
+@var{output-format} is a text string, the name of a particular format
+supported by the BFD libraries.  @xref{BFD}.
+
+@code{-format @var{output-format}} has the same effect.
+
 @item -Bstatic 
 This flag is accepted for command-line compatibility with the SunOS linker,
 but has no effect on @code{gld}.
 
 @item -c @var{commandfile}
-Directs @code{gld} to read linkage commands from the file @var{commandfile}.
+Directs @code{gld} to read link commands from the file
+@var{commandfile}.  These commands will override @code{gld}'s
+default link format in its entirety; @var{commandfile} must specify
+everything necessary to specify the target format.  @xref{Commands}.
 
+You may also include a script of link commands directly in the command
+line by using the @code{SCRIPT} @dots{} @code{ENDSCRIPT} keywords.
+
+@c FIXME: -D in older GNU linker, not necessarily in new
 @item -D @var{datasize}
 Use this option to specify a target size for the @code{data} segment of
 your linked program.  The option is only obeyed if @var{datasize} is
@@ -132,45 +211,72 @@ larger than the natural size of the program's @code{data} segment.
 @var{datasize} must be an integer specified in hexadecimal.
 
 @code{ld} will simply increase the size of the @code{data} segment,
-padding the created gap with zeros, and reduce the size of the
-@code{bss} segment to match.
-
-@item -d
-Force @code{ld} to assign space to common symbols
-even if a relocatable output file is specified (@code{-r}).
-
-@item -dc | -dp
-This flags is accepted for command-line compatibility with the SunOS linker,
-but has no effect on @code{gld}.
+padding the created gap with zeros (or a fill pattern specified with
+@samp{-f}, or using the command language), and reduce the size of the
+@code{bss} segment by the same amount.
+@c FIXME: double-check this w/Steve.  Open questions: order? Does it
+@c FIXME...matter whether -f before or after -D?  What about -c relative
+@c FIXME...position? fill cmd in default script? Apparently
+@c FIXME...can have multiple fill patterns; which used here?
+
+
+@item -d 
+@itemx -dc
+@itemx -dp
+These three options are equivalent; multiple forms are supported for
+compatibility with other linkers.  Any of them options will force
+@code{ld} to assign space to common symbols even if a relocatable output
+file is specified (@code{-r}).
+
+@item -defsym @var{symbol} = @var{expression}
+Create a global symbol, in the output file, set to the absolute address
+given by @var{expression}.  A limited form of arithmetic is supported
+for the @var{expression} in this context: you may give a hexadecimal
+constant, or use @code{+} and @code{-} to add or subtract hexacedimal
+constants.  If you need more elaborate expressions, consider using the
+linker command language from a script.
 
 @item -e @var{entry} 
 Use @var{entry} as the explicit symbol for beginning execution of your
-program, rather than the default entry point. If this symbol is
-not specified, the symbol @code{start} is used as the entry address.
-If there is no symbol called @code{start}, then the entry address
-is set to the first address in the first output section 
-(usually the @samp{text} section).
+program, rather than the default entry point. @xref{Entry Point}, for a
+discussion of defaults and other ways of specifying the
+entry point.
 
+@c FIXME: -f in older GNU linker, not necessarily in new
 @item -f @var{fill}
 Sets the default fill pattern for ``holes'' in the output file to
 the lowest two bytes of the expression specified.
 
+@item -F
+@itemx -F{format}
+Some older linkers required the specification of object-file format,
+even when all input files were homogeneous, and used this option for
+that purpose.  @code{gld} doesn't usually require this information---it
+automatically recognizes input-file object format---but it accepts the
+option flag for compatibility with old scripts.  
+
+@item -format @var{output-format}
+Synonym for @code{-b} @var{output-format}.
+
+@item -g
+Accepted, but ignored; provided for compatibility with other tools.
+
 @item -i
 Produce an incremental link (same as option @code{-r}).
 
-@item -l @var{arch} 
-Add an archive file @var{arch} to the list of files to link.  This 
+@item -l@var{ar} 
+Add an archive file @var{ar} 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{arch}.a} for every @var{arch}
+path-list for occurrences of @code{lib@var{ar}.a} for every @var{ar}
 specified.
 
-@c This also has a side effect of using the "c++ demangler" if we happen
-@c to specify -llibg++.  Document?  pesch@@cygnus.com, 24jan91
+@c FIXME: -l also has a side effect of using the "c++ demangler" if we happen
+@c FIXME...to specify -llibg++.  Document?  pesch@@cygnus.com, 24jan91
 
-@item -L @var{searchdir} 
-This command adds path @var{searchdir} to the
-list of paths that @code{gld} will search for archive libraries.  You
-may use this option any number of times.
+@item -L@var{searchdir} 
+This command adds path @var{searchdir} to the list of paths that
+@code{gld} will search for archive libraries.  You may use this option
+any number of times.
 
 @c Should we make any attempt to list the standard paths searched
 @c without listing?  When hacking on a new system I often want to know
@@ -184,23 +290,41 @@ Print (to the standard output file) a link map---diagnostic information
 about where symbols are mapped by @code{ld}, and information on global
 common storage allocation.
 
+@c FIXME: -N in older GNU linker, not necessarily in new
 @item -N 
-specifies read and writable @code{text} and @code{data} sections. If
-the output format supports Unix style magic numbers, then OMAGIC is set.
+specifies readable and writable @code{text} and @code{data} sections. If
+the output format supports Unix style magic numbers, the output is
+marked as @code{OMAGIC}.
 
 @item -n 
 sets the text segment to be read only, and @code{NMAGIC} is written
 if possible.
 
+@item -noinhibit-exec
+Normally, the linker will not produce an output file if it encounters
+errors during the link process.  With this flag, you can specify that
+you wish the output file retained for even after non-fatal errors.
+
 @item -o @var{output}
 @var{output} is a name for the program produced by @code{ld}; if this
 option is not specified, the name @samp{a.out} is used by default.
 
+@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.
+@c FIXME: -R accurate?  Motivation?  Kernel memory, shared mem?
+
 @item -r 
+@cindex partial link
 Generates relocatable output---i.e., generate an output file that can in
-turn serve as input to @code{gld}.  As a side effect, this option also
-sets the output file's magic number to @code{OMAGIC}; see @samp{-N}. If this
-option is not specified, an absolute file is produced.
+turn serve as input to @code{gld}.  This is often called @dfn{partial
+linking}.  As a side effect, this option also sets the output file's
+magic number to @code{OMAGIC}; see @samp{-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;
+@samp{-Ur} is an alternative.
 
 @item -S 
 Omits debugger symbol information (but not all symbols) from the output file.
@@ -208,15 +332,28 @@ Omits debugger symbol information (but not all symbols) from the output file.
 @item -s 
 Omits all symbol information from the output file.
 
-@item -T @var{textorg} 
+@item SCRIPT  @dots  @@
+@itemx SCRIPT  @dots  ENDSCRIPT
+You can, if you wish, include a script of linker commands directly in
+the command line instead of referring to it via an input file.  When the
+keyword @code{SCRIPT} occurs on the command line, the linker switches to
+interpreting the command language until the end of the list of commands
+is reached---flagged with either an at sign @samp{@@} or with the
+keyword @code{ENDSCRIPT}.  Other command-line options will not be
+recognized while parsing the script.  @xref{Commands} for a description
+of the command language.
+
+@item -Tbss @var{bssorg}
+@itemx -Tdata @var{dataorg}
 @itemx -Ttext @var{textorg}
-Use @var{textorg} as the starting address for the @code{text} segment of the
-output file.  Both forms of this option are equivalent.  The option
-argument must be a hexadecimal integer.
+Use @var{textorg} as the starting address for---respectively---the
+@code{bss}, @code{data}, or the @code{text} segment of the output file.
+@var{textorg} must be a hexadecimal integer.
 
-@item -Tdata @var{dataorg} 
-Use @var{dataorg} as the starting address for the @code{data} segment of
-the output file.  The option argument must be a hexadecimal integer.
+@item -T @var{commandfile}
+@itemx -T@var{commandfile}
+Equivalent to @code{-c @var{commandfile}}; supported for compatibility with
+other tools.  
 
 @item -t 
 Prints names of input files as @code{ld} processes them.
@@ -228,135 +365,211 @@ standard libraries.  @code{-u} may be repeated with different option
 arguments to enter additional undefined symbols. This option is equivalent
 to the @code{EXTERN} linker command.
 
+@item -Ur 
+@cindex constructors
+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{gld}.  When linking C++ programs, @samp{-Ur}
+@emph{will} resolve references to constructors, unlike @samp{-r}.
+
+@item -v
+@cindex version
+@cindex verbose
+``Verbose'' switch: display informative messages, including the version
+numbers for @code{gld} and BFD, information on files opened, and BFD
+subroutine calls.
+
 @item -X 
 If @code{-s} or @code{-S} is also specified, delete only local symbols
 beginning with @samp{L}.
 
+@item -x
+If @code{-s} or @code{-S} is also specified, delete all local symbols,
+not just those beginning with @samp{L}.
+
+@c FIXME: -z in older GNU linker, not necessarily in new
 @item -z
-@code{-z} sets @code{ZMAGIC}, the default: the @code{text} segment is
-read-only, demand pageable, and shared.  
+Specifies a read-only, demand pageable, and shared @code{text} segment.
+If the output format supports Unix-style magic numbers, @code{-z} also
+marks the output as @code{ZMAGIC}, the default.
 
+@c FIXME: why is following here?.  Is it useful to say '-z -r' for
+@c FIXME...instance, or is this just a ref to other ways of setting
+@c FIXME...magic no?
 Specifying a relocatable output file (@code{-r}) will also set the magic
 number to @code{OMAGIC}.
 
 See description of @samp{-N}.
 
-
 @end table
+
+@node Commands,,,
 @chapter Command Language
+@c FIXME: is this a good place to talk about LDEMULATION env var?
+@c FIXME...Apparently some commands "subtly different" depending on
+@c FIXME...whether this set to eg "link960", "gld960", "gld".  What is
+@c FIXME...full set of possibilities, what is default?  Config-dep?
 
 
-The command language allows explicit control over the linkage process, allowing
-specification of:
-@table @bullet
+The command language allows explicit control over the link process,
+allowing complete specification of the mapping between the linker's
+input files and its output.  This includes:
+@itemize @bullet
 @item input files 
 @item file formats
 @item output file format
 @item addresses of sections
 @item placement of common blocks
-@item and more
-@end table
-
-A command file may be supplied to the linker, either explicitly through the
-@code{-c} option, or implicitly as an ordinary file. If the linker opens
-a file which does not have a reasonable object or archive format, it tries
-to read the file as if it were a command file.
-@section Structure
-To be added
+@end itemize
 
+A command file may be supplied to the linker, either explicitly through
+the @code{-c} 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 tries to interpret the file as a command file.
+
+@node Scripts,,,
+@section Linker Scripts
+The @code{gld} command language is a collection of statements; some are
+simple keywords setting a particular flag, some are used to select and
+group input files or name output files; and two particular statement
+types have a fundamental and pervasive impact on the linking process.
+
+The most fundamental command of the @code{gld} 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; if it is not present,
+sufficient memory is assumed to be available in a contiguous block for
+all output.  @xref{MEMORY}.
+
+@node Expressions,,,
 @section Expressions
-The syntax for expressions in the command language is identical to that of
-C expressions, with the following features:
-@table @bullet
+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 Global variables may be referenced, defined and created.
-@item Build in functions may be called.
-@end table
-
-@section Expressions
-
-The linker has a practice of ``lazy evaluation'' for expressions; it only
-calculates an expression when absolutely necessary. For instance, 
-when the linker reads in the command file it has to know the values
-of the start address and the length of the memory regions for linkage to continue, so these
-values are worked out, but other values (such as symbol values) are not
-known or needed until after storage allocation.
-They are evaluated later, when the other
-information, such as the sizes of output sections are available for use in
-the symbol assignment expression.
-
-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 relocateable 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 @code{SECTION} specification 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 @code{SECTION} specification 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 @code{SECTION} specification by using the absolute assignment
-function @code{ABSOLUTE} For example, to create an absolute symbol
-whose address is the last byte of the output section @code{.data}:
-@example
-.data : 
-        @{
-                *(.data)
-                _edata = ABSOLUTE(.) ;
-        @} 
-@end example
-
-Unless quoted, symbol names start with a letter, underscore, point or
-minus sign and may include any letters, underscores, digits, points,
-and minus signs.  Unquoted symbol names must not conflict with any
-keywords.  To specify a symbol which contains odd characters or has
-the same name as a keyword surround it in double quotes:
-@example
-        ``SECTION'' = 9;
-        ``with a space'' = ``also with a space'' + 10;
-@end example
+@item Built in functions may be called.
+@end itemize
 
+@node Integers,,,
 @subsection Integers
 An octal integer is @samp{0} followed by zero or more of the octal
 digits (@samp{01234567}).
+@example
+@end example
 
 A decimal integer starts with a non-zero digit followed by zero or
 more digits (@samp{0123456789}).
+@example
+_as_octal = 0157255;
+@end example
 
 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
+@example
+_as_hex = 0xdead;
+@end example
 
-Integers have the usual values.  To denote a negative integer, use
-the unary operator @samp{-} discussed under expressions.
+Decimal integers have the usual values.  To denote a negative integer, use
+the prefix operator @samp{-}; @pxref{Operators}.
+@example
+_as_decimal = 57005;
+_as_neg = -57005;
+@end example
 
-Additionally the suffixes @code{K} and @code{M} may be used to multiply the
-previous constant by 1024 or 
+Additionally the suffixes @code{K} and @code{M} may be used to scale a
+constant by 
 @tex
-$1024^2$
+${\rm 1024}$ or ${\rm 1024}^2$
 @end tex
-respectively.
+@ifinfo
+1024 or 1024*1024
+@end ifinfo
+respectively. For example, the following all refer to the same quantity:@refill
 
 @example
-        _as_decimal = 57005;
-        _as_hex = 0xdead;
-        _as_octal = 0157255;
-
         _4k_1 = 4K;
         _4k_2 = 4096;
         _4k_3 = 0x1000;
 @end example
+
+@node Symbols,,,
+@subsection Symbol Names
+Unless quoted, symbol names start with a letter, underscore, point or
+minus sign and may include any letters, underscores, digits, points,
+and minus signs.  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:
+@example
+        "SECTION" = 9;
+        "with a space" = "also with a space" + 10;
+@end example
+
+@subsection The Location Counter
+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.
+This may be used to create holes in the output section.  The location
+counter may never be moved backwards.
+@example
+        SECTIONS
+        @{
+                output :
+                @{
+                file1(.text)
+                . = . + 1000;
+                file2(.text)
+                . += 1000;
+                file3(.text)
+                . -= 32;
+                file4(.text)
+                @} = 0x1234;
+        @}
+@end example
+In the previous example, @code{file1} is located at the beginning of
+the output section, then there is a 1000 byte gap, filled with 0x1234.
+Then @code{file2} appears, also with a 1000 byte gap following before
+@code{file3} is loaded. Then the first 32 bytes of @code{file4} are
+placed over the last 32 bytes of @code{file3}.
+
+@node Operators,,,
 @subsection Operators
-The linker provides the standard C set of arithmetic operators, with
+The linker recognizes  the standard C set of arithmetic operators, with
 the standard bindings and precedence levels:
+@c FIXME: distinguish somehow between prefix, infix in operator table!
+@c FIXME: is it fair to include assignments below?  Don't they
+@c FIXME...require trailing ; when no other exprs do?
+@ifinfo
 @example
-
+precedence	associativity	Operators
+(highest)
+1		left		!  -  ~
+2		left		*  /  %
+3		left		+  -
+4		left		>>  <<
+5		left		==  !=  >  <  <=  >=
+6		left		&
+7		left		|
+8		left		&&
+9		left		||
+10		right		? :
+11		right		&=  +=  -=  *=  /=
+(lowest)
 @end example
+@end ifinfo
+@c FIXME: simplify, debug TeX form of this table!
 @tex
 
 \vbox{\offinterlineskip
@@ -368,7 +581,7 @@ height2pt&&&&&\cr
 height2pt&&&&&\cr
 \noalign{\hrule}
 height2pt&&&&&\cr
-&highest&&&&&&\cr
+&highest&&&&&\cr
 &1&&left&&$ ! -         ~$&\cr
 height2pt&&&&&\cr
 &2&&left&&*        /        \%&\cr
@@ -390,23 +603,115 @@ height2pt&&&&&\cr
 &10&&right&&? :&\cr
 height2pt&&&&&\cr
 &11&&right&&$${\&=        +=        -=        *=        /=}&\cr
-&lowest&&&&&&\cr
+&lowest&&&&&\cr
 height2pt&&&&&\cr}
 \hrule}
 @end tex
 
-@section Built in Functions
+@node Evaluation,,,
+@subsection Evaluation
+
+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
+
+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} ;
+@end table
+
+Two things distinguish assignment from other operators in @code{gld}
+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.
+@item A trailing semicolon is required at the end of an assignment
+statement. 
+@end itemize
+
+Assignment statements may appear:
+@itemize @bullet
+@item as commands in their own right in a @code{gld} 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}).
+
+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 relocateable 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 @code{SECTION} specification 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 @code{SECTION} specification 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 @code{SECTION} specification by using the absolute assignment
+function @code{ABSOLUTE} For example, to create an absolute symbol
+whose address is the last byte of the output section @code{.data}:
+@example
+.data : 
+        @{
+                *(.data)
+                _edata = ABSOLUTE(.) ;
+        @} 
+@end example
+
+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, attempting to use a
+script like the following
+@example
+SECTIONS @{
+      text 9+this_isnt_constant: 
+                @{ @dots{}
+                @}
+        @}
+@end example
+will get the error message ``@code{Non constant expression for initial
+address}''. 
+
+@node Builtins,,,
+@subsection Built in Functions
 The command language provides built in functions for use in
-expressions in linkage scripts.
-@table @bullet 
+expressions in link scripts.
+@itemize @bullet 
 @item @code{ALIGN(@var{exp})}
-returns the result of the current location counter (@code{dot})
-aligned to the next @var{exp} boundary, where @var{exp} is a power of
-two.  This is equivalent to @code{(. + @var{exp} -1) & ~(@var{exp}-1)}.
-As an example, to align the output @code{.data} section to the
-next 0x2000 byte boundary after the preceding section and to set a
-variable within the section to the next 0x8000 boundary after the
-input sections:
+returns 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 @samp{(. + @var{exp} -1)
+& ~(@var{exp}-1)}.  As an example, to align the output @code{.data}
+section to the next 0x2000 byte boundary after the preceding section and
+to set a variable within the section to the next 0x8000 boundary after
+the input sections:
 @example
         .data ALIGN(0x2000) :@{
                 *(.data)
@@ -415,9 +720,10 @@ input sections:
 @end example
 
 @item @code{ADDR(@var{section name})}
-returns the absolute address of the named section if the section has
-already been bound. In the following examples the @code{symbol_1} and
-@code{symbol_2} are assigned identical values:
+returns the absolute address of the named section.  Your script must
+previously have defined the location of that section. In the following
+example the @code{symbol_1} and @code{symbol_2} are assigned identical
+values:
 @example
         .output1:
                 @{ 
@@ -447,54 +753,61 @@ been allocated.  In the following example the @code{symbol_1} and
 
 @item @code{DEFINED(@var{symbol name})}
 Returns 1 if the symbol is in the linker global symbol table and is
-defined, otherwise it returns 0. This example shows the setting of a
-global symbol @code{begin} to the first location in the @code{.text}
-section, only if there is no other symbol
-called @code{begin} already:
+defined, otherwise it returns 0. For example, this command-file fragment
+shows how to set a global symbol @code{begin} to the first location in
+the @code{.text} section---but only if no symbol called @code{begin}
+existed:
 @example
         .text: @{
                 begin = DEFINED(begin) ? begin : . ;
                 ...
         @}
 @end example
-@end table 
-@page
-@section MEMORY Directive
-The linker's default configuration is for all memory to be
-allocatable.  This state may be overridden by using the @code{MEMORY}
-directive.  The @code{MEMORY} directive describes the location and
-size of blocks of memory in the target.  Careful use can describe
-memory regions which may or may not be used by the linker. 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.  The syntax is:
+@end itemize
+
+@node MEMORY,,,
+@section MEMORY Command
+The linker's default configuration permits allocation of all memory.
+You can override this by using the @code{MEMORY} command.  The
+@code{MEMORY} command describes the location and size of blocks of
+memory in the target.  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.  
+
+Command files 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:
 	
 @example
-        MEMORY 
-                @{
-@tex
-                 $\bigl\lbrace {\it name_1} ({\it attr_1}):$ ORIGIN = ${\it origin_1},$ LENGTH $= {\it len_1} \bigr\rbrace $
-@end tex
-
-                @}
+MEMORY 
+      @{
+       @var{name} (@var{attr}): ORIGIN = @var{origin}, LENGTH = @var{len}
+       .
+       .
+       .
+      @}
 @end example
 @table @code
 @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, filenames or section
-names.
-@item @var{attr}
+names.  Use distinct names to specify multiple regions.
+@item (@var{attr})
 is an optional list of attributes, parsed for compatibility with the
-AT+T linker
-but ignored by the both the AT+T and the gnu linker.
+AT@&T linker but ignored by the both the AT@&T and the GNU linker.
+Valid attribute lists must be made up of the characters ``@code{RWXL}''.
+If you omit the attribute list, you may omit the parentheses around it
+as well. 
 @item @var{origin}
-is the start address of the region in physical memory expressed as
-standard linker expression which must evaluate to a constant before
+is the start address of the region in physical memory.  It is expressed as
+an expression, which must evaluate to a constant before
 memory allocation is performed. The keyword @code{ORIGIN} may be
 abbreviated to @code{org} or @code{o}.
 @item @var{len}
-is the size in bytes of the region as a standard linker expression.
+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 
 
@@ -503,155 +816,263 @@ allocation; one starting at 0 for 256k, and the other starting at
 0x40000000 for four megabytes:
 
 @example
-        MEMORY 
-                @{
-                rom : ORIGIN= 0, LENGTH = 256K
-                ram : ORIGIN= 0x40000000, LENGTH = 4M
-                @}
-
+MEMORY 
+        @{
+        rom : ORIGIN= 0, LENGTH = 256K
+        ram : org= 0x40000000, l = 4M
+        @}
 @end example
 
-If the combined output sections directed to a region are too big for
-the region the linker will emit an error message.
-@page
-@section SECTIONS Directive
-The @code{SECTIONS} directive 
-controls exactly where input sections are placed into output sections, their
-order and to which output sections they are allocated.
+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.  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 SECTIONS Command
+The @code{SECTIONS} command controls exactly where input sections are
+placed into output sections, their order and to which output sections
+they are allocated.
+
+You may use at most one @code{SECTIONS} command in a commands 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 what input
+sections make it up.
+@end itemize
+
+The first two possibilities---defining the entry point, and defining
+symbols---can also be done outside the @samp{SECTIONS} command:
+@pxref{Entry Point}, @pxref{Assignment}.  They are permitted here as
+well for your convenience in reading the script, so that symbols or the
+entry point can be defined at meaningful points in your output-file
+layout.
 
-When no @code{SECTIONS} directives are specified, the default action
+When no @code{SECTIONS} command is specified, the default action
 of the linker is to place each input section into an identically named
-output section in the order that the sections appear in the first
-file, and then the order of the files.
+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.
+
+@node Section Definition,,,
+@subsection Section Definitions
+The most frequently used statement in the @code{SECTIONS} command is
+the @dfn{section definition}, which you can use to specify the
+properties of an output section: its location, alignment, contents,
+fill pattern, and target memory region can all be specified.  Most of
+these specifications are optional; the simplest form of a section
+definition is
+@example
+SECTIONS
+@{
+.
+.
+.
+@var{secname} : @{
+                 @var{contents}
+                @}
+.
+.
+.
+@}
+@end example
+@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.  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
+(in the case of @code{a.out}, @code{.text}, @code{.data} or @code{.bss}). If
+the output format supports any number of sections, but with numbers and
+not names (in the case of IEEE), the name should be supplied as a quoted
+numeric string.  A section name may consist of any sequence characters,
+but any name which does not conform to the standard @code{gld} symbol
+name syntax must be quoted.
+
+@node Section Contents,,,
+@subsection Section Contents
+In a section definition, you can specify the contents of an output section by
+listing particular object files; by listing particular input-file
+sections; or 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. 
 
-The syntax of the @code{SECTIONS} directive is:
+@table @code
+@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.
 
+@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.  Since multiple statements may be
+present in the contents of a section definition, you can specify a list
+of particular files by name:
 @example
-   SECTIONS
-   @{
-@tex
-    $\bigl\lbrace {\it name_n}\bigl[options\bigr]\colon$ $\bigl\lbrace {\it statements_n} \bigr\rbrace \bigl[ = {\it fill expression } \bigr] \bigl[ > mem spec \bigr] \bigr\rbrace $
-@end tex
-   @}
+.data: @{ afile.o bfile.o cfile.o @}
 @end example
 
-@table @code
-@item @var{name}
-controls the name of the output section. 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 (in the case of a.out,
-@code{.text}, @code{.data} or @code{.bss}). If the output format
-supports any number of sections, but with numbers and not names (in
-the case of IEEE), the name should be supplied as a quoted numeric
-string.  A section name may consist of any sequence characters, but
-any name which does not conform to the standard @code{gld} symbol name
-syntax must be quoted. To copy sections 1 through 4 from a Oasys file
-into the @code{.text} section of an @code{a.out} file, and sections 13
-and 14 into the @code{data} section:
-@example
-
-        SECTION @{
-                .text :@{
-                        *(``1'' ``2'' ``3'' ``4'')
-                @}
+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.
+
+@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{gld} command
+line: use @samp{*} instead of a particular filename before the
+parenthesized input-file section list.  
+
+For example, to copy sections @code{1} through @code{4} from a 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:
+@example
+SECTION @{
+        .text :@{
+                *("1" "2" "3" "4")
+        @}
 
-                .data :@{
-                        *(``13'' ``14'')
-                @}
+        .data :@{
+                *("13" "14")
         @}
+@}
 @end example
 
-@item @var{fill expression}
-If present this
-expression sets the fill value. 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.
-@page
-@item @var{options}
-the @var{options} parameter is a list of optional arguments specifying
-attributes of the output section, they may be taken from the following
-list:
-@table @bullet{}
-@item @var{addr expression} 
-forces the output section to be loaded at a specified address. The
-address is specified as a standard linker expression. The following
-example generates section @var{output} at location
-@code{0x40000000}:
+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.
+
+@item [ @var{section} ]
+@itemx [ @var{section}, @var{section}, @dots{} ]
+@itemx [ @var{section} @var{section} @dots{} ]
+This is an alternate notation to specify named sections from all
+unallocated input files; its effect is exactly the same as that of
+@samp{* (@var{section}@dots{})}
+
+@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{gld} 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 its 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:
 @example
-         SECTIONS @{
-                 output 0x40000000: @{
-                        ...
-                   @}
-         @}
+SECTIONS 
+{ 
+  .text: { *(.text) }  
+  .data: { *(.data) }  
+  .bss:  { *(.bss)  [COMMON] } 
+} 
 @end example
-Since the built in function @code{ALIGN} references the location
-counter implicitly, a section may be located on a certain boundary by
-using the @code{ALIGN} function in the expression. For example, to
-locate the @code{.data} section on the next 8k boundary after the end
-of the @code{.text} section:
-@example        
-        SECTIONS @{
-                .text @{
-                        ...
+
+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}.
+
+@example
+SECTIONS        
+      @{
+        outputa 0x10000 :
+                @{
+                all.o
+                foo.o (.input1)
                 @}
-                .data ALIGN(4K) @{
-                        ...
+        outputb :
+                @{
+                foo.o (.input2)
+                foo1.o (.input1)
                 @}
-        @}
-@end example
-@end table
-@item @var{statements}
-is a list of file names, input sections and assignments. These statements control what is placed into the
-output section.
-The syntax of a single @var{statement} is one of:
-@table @bullet 
-
-@item @var{symbol}  [ $= | += | -= | *= | /= ] @var{ expression} @code{;}
-
-Global symbols may be created and have their values (addresses)
-altered using the assignment statement. The linker tries to put off
-the evaluation of an assignment until all the terms in the source
-expression are known; 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 @code{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: eg
-@example
-        SECTIONS @{
-              text 9+this_isnt_constant: 
-                        @{
-                        @}
+        outputc :
+                @{
+                *(.input1)
+                *(.input2)
                 @}
-        testscript:21: Non constant expression for initial address
-@end example
+        @}
+@end example        
+
+There are still more kinds of statements permitted in the contents of
+output section definitions!  The foregoing statements permitted you to
+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.
 
-@item @code{CREATE_OBJECT_SYMBOLS}
-causes the linker to create a symbol for each input file and place it
-into the specified section set with the value of the first byte of
+@table @code
+@item CREATE_OBJECT_SYMBOLS
+instructs the linker to create a symbol for each input file and place it
+into the current section, set with the address of the first byte of
 data written from the input file.  For instance, with @code{a.out}
-files it is conventional to have a symbol for each input file.
-@example
-        SECTIONS @{
-                .text 0x2020 :
-                         @{
-                        CREATE_OBJECT_SYMBOLS
-                        *(.text)
-                        _etext = ALIGN(0x2000);
-                        @}
+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:
+@example
+SECTIONS @{
+        .text 0x2020 :
+                 @{
+                CREATE_OBJECT_SYMBOLS
+                *(.text)
+                _etext = ALIGN(0x2000);
                 @}
+        .
+        .
+        .
+        @}
 @end example
-Supplied with four object files, @code{a.o}, @code{b.o}, @code{c.o},
-and @code{d.o} a run of
-@code{gld} could create a map:
+
+If @code{objsym} 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---
 @example
-From functions like :
-a.c:
-        afunction() { }
-        int adata=1;
-        int abss;
+/* a.c */
+
+afunction() { }
+int adata=1;
+int abss;
+@end example
 
+@noindent
+@samp{gld -M sample a.o b.o c.o d.o} would create a map like this,
+containing symbols matching the object file names:
+@example
 00000000 A __DYNAMIC
 00004020 B _abss
 00004000 D _adata
@@ -672,163 +1093,202 @@ a.c:
 00002038 t b.o
 00002050 t c.o
 00002068 t d.o
-
 @end example
 
-@item @var{filename} @code{(} @var{section name list} @code{)}
-This command allocates all the named sections from the input object
-file supplied into the output section at the current point. Sections
-are written in the order they appear in the list so:
-@example
-        SECTIONS @{
-                .text 0x2020 :                
-                        @{
-                        a.o(.data)
-                        b.o(.data)
-                        *(.text)
-                        @}
-                .data :
-                        @{
-                        *(.data)
-                        @}
-                .bss :
-                        @{
-                        *(.bss)
-                        COMMON
-                        @}
-        @}
+@item FORCE_COMMON_ALLOCATION
+@c FIXME!  I don't know what this does.
+
+@item @var{symbol} = @var{expression} ;
+@itemx @var{symbol} @var{f}= @var{expression} ;
+@var{symbol} is any symbol name (@pxref{Symbols}).  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
+@example
+SECTIONS
+{
+  abs = 14 ;
+.
+.
+.
+  .data: { @dots{} rel = 14 ; @dots{} }
+  abs2 = 14 + ADDR(.data);
+.
+.
+.
+}
 @end example
-will produce a map:
+@c FIXME!  Try above example!
+@noindent
+@code{abs} and @var{rel} do not have the same value; @code{rel} has the
+same value as @code{abs2}.
+
+``@var{f}='' here refers to any of the operators @code{&=  +=  -=  *=
+/=} which combine arithmetic and assignment.
+
+@item BYTE(@var{expression})
+@itemx SHORT(@var{expression})
+@itemx LONG(@var{expression})
+By including one of these three statements in a section definition, you
+can explicitly place one, two, or four bytes (respectively) at the
+current address of that section.  Multiple-byte quantities are
+represented in whatever byte order is appropriate for the output file
+format (@pxref{BFD}). 
+
+@item FILL(@var{expression})
+Specifies 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
+Here is the full syntax of a section definition, including all the
+optional portions:
+
 @example
+SECTIONS
+@{
+.
+.
+.
+@var{secname} @var{start} BLOCK(@var{align}) : @var{contents} =@var{fill} >@var{region}
+.
+.
+.
+@}
+@end example
+
+@var{secname} and @var{contents} are required.  @xref{Section
+Definition}, and @pxref{Section Contents} for the details of
+@var{contents}.  @var{start}, @code{BLOCK(@var{align)}},
+@code{=@var{fill}}, and @code{>@var{region}} are all optional.
 
-        insert here 
+@table @code
+@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}:
+@example
+SECTIONS @{
+        .
+        .
+        .
+        output 0x40000000: @{
+               @dots{}
+          @}
+        .
+        .
+        .
+@}
 @end example
-@item @code{* (} @var{section name list} @code{)}
-This command causes all sections from all input files which have not
-yet been assigned output sections to be assigned the current output
-section.
 
-@item @var{filename} @code{[COMMON]}
-This allocates all the common symbols from the specified file and places
-them into the current output section.
+@item BLOCK(@var{align})
+@c FIXME!  Fill in BLOCK(align) description
 
-@item @code{* [COMMON]}
-This allocates all the common symbols from the files which have not
-yet had their common symbols allocated and places them into the current
-output section.
+@item =@var{fill}
+You may use any expression to specify @var{fill}.  Including
+@code{=@var{fill}} in a section definition specifies the initial fill
+value for that section. 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.
 
-@item @var{filename}
-A filename alone within a @code{SECTIONS} statement will cause all the
-input sections from the file to be placed into the current output
-section at the current location. If the file name has been mentioned
-before with a section name list then only those
-sections which have not yet been allocated are noted. 
-
-The following example reads all of the sections from file all.o and
-places them at the start of output section @code{outputa} which starts
-at location @code{0x10000}. All of the data from section @code{.input1} from
-file foo.o is placed next into the same output section.  All of
-section @code{.input2} is read from foo.o and placed into output
-section @code{outputb}.  Next all of section @code{.input1} is read
-from foo1.o. All of the remaining @code{.input1} and @code{.input2}
-sections from any files are written to output section @code{output3}.
-
-@example
-       SECTIONS        
-              @{
-                outputa 0x10000 :
-                        @{
-                        all.o
-                        foo.o (.input1)
-                        @}
-                outputb :
-                        @{
-                        foo.o (.input2)
-                        foo1.o (.input1)
-                        @}
-                outputc :
-                        @{
-                        *(.input1)
-                        *(.input2)
-                        @}
-                @}
+@item >@var{region}
+@c FIXME! Fill in >region description
 
-@end example        
 @end table
-@end table
-@section Using the Location Counter
-The special linker variable @code{dot}, @samp{.} always contains the
-current output location counter. Since the @code{dot} always refers to
-a location in an output section, it must always appear in an
-expression within a @code{SECTIONS} directive. The @code{dot} symbol
-may appear anywhere that an ordinary symbol may appear in an
-expression, but its assignments have a side effect. Assigning a value
-to the @code{dot} symbol will cause the location counter to be moved.
-This may be used to create holes in the output section.  The location
-counter may never be moved backwards.
+
+@node Entry Point,,,
+@section The Entry Point
+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:
 @example
-        SECTIONS
-        @{
-                output :
-                @{
-                file1(.text)
-                . = . + 1000;
-                file2(.text)
-                . += 1000;
-                file3(.text)
-                . -= 32;
-                file4(.text)
-                @} = 0x1234;
-        @}
+ENTRY(@var{symbol})
 @end example
-In the previous example, @code{file1} is located at the beginning of
-the output section, then there is a 1000 byte gap, filled with 0x1234.
-Then @code{file2} appears, also with a 1000 byte gap following before
-@code{file3} is loaded. Then the first 32 bytes of @code{file4} are
-placed over the last 32 bytes of @code{file3}.
-@section Command Language Syntax
-@section The Entry Point
-The linker chooses the first executable instruction in an output file from a list
-of possibilities, in order:
+
+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.
+
+@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 value of the symbol provided to the command line with the @code{-e} option, when
-present.
+the @code{-e} @var{entry} command-line option;
 @item 
-The value of the symbol provided in the @code{ENTRY} directive,
-if present.
+the @code{ENTRY} @var{symbol} command in a linker control script;
 @item 
-The value of the symbol @code{start}, if present.
+the value of the symbol @code{start}, if present;
 @item 
-The value of the symbol @code{_main}, if present.
+the value of the symbol @code{_main}, if present;
 @item 
-The address of the first byte of the @code{.text} section, if present.
+the address of the first byte of the @code{.text} section, if present;
 @item 
-The value 0.
+The address @code{0}.
 @end itemize
-If the symbol @code{start} is not defined within the set of input
-files to a link, it may be generated by a simple assignment
-expression. eg.
+
+For example, you can also generate an entry point with an assignment statement:
+if no symbol @code{start} is  defined within your input files, you can
+simply assign it an appropriate value---
 @example
-        start = 0x2020;
+start = 0x2020;
 @end example
-@section Section Attributes
-@section Allocation of Sections into Memory
-@section Defining Symbols
-@chapter Examples of operation
-The simplest case is linking standard Unix object files on a standard
-Unix system supported by the linker. To link a file hello.o:
+
+@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}:
 @example
-$ gld -o output /lib/crt0.o hello.o -lc
+start = other_symbol;
 @end example
-This tells gld to produce a file called @code{output} after 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.
-@chapter Partial Linking
-Specifying the @code{-r} on the command line causes @code{gld} to
-perform a partial link.
 
+@node Other Commands,,,
+@section Other 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
+@item FLOAT
+@itemx NOFLOAT
+Declare to the linker whether or not floating point support is
+available.  The default assumption is @code{NOFLOAT}.
+@c FIXME: So what?  What does it do once it knows FLOAT or NOFLOAT?
+
+@item HLL ( @var{file}, @var{file}, @dots{} )
+@itemx HLL ( @var{file} @var{file} @dots{} )
+
+@item INPUT ( @var{file}, @var{file}, @dots{} )
+@itemx INPUT ( @var{file} @var{file} @dots{} )
+
+@item MAP ( @var{name} )
+
+@item OUTPUT ( @var{filename} )
 
+@item SEARCH_DIR ( @var{pathname} )
+
+@item STARTUP ( @var{name} )
+
+@item SYSLIB ( @var{file}, @var{file}, @dots{} )
+@itemx SYSLIB ( @var{file} @var{file} @dots{} )
+
+@item TARGET ( @var{format} )
+
+@end table
+
+@node BFD,,,
 @chapter BFD
 
 The linker accesses object and archive files using the @code{bfd}
@@ -841,13 +1301,13 @@ new @code{bfd} back end and adding it to the library.
 Formats currently supported:
 @itemize @bullet
 @item 
-Sun3 68k a.out
+Sun3 68k @code{a.out}
 @item 
 IEEE-695 68k Object Module Format
 @item 
 Oasys 68k Binary Relocatable Object File Format
 @item 
-Sun4 sparc a.out
+Sun4 sparc @code{a.out}
 @item 
 88k bcs coff
 @item 
@@ -855,9 +1315,9 @@ i960 coff little endian
 @item 
 i960 coff big endian
 @item 
-i960 b.out little endian
+i960 @code{b.out} little endian
 @item 
-i960 b.out big endian
+i960 @code{b.out} big endian
 @end itemize
 
 As with most implementations, @code{bfd} is a compromise between
@@ -869,56 +1329,58 @@ been involved. This is partly offset by abstraction payback; since
 may be spent optimizing algorithms for a greater speed.
 
 One minor artifact of the @code{bfd} solution which the
-user should be aware of is information lossage.
+user should be aware of is the potential for information loss.
 There are two places where useful information can be lost using the 
-@code{bfd} mechanism; during conversion and during output. 
+@code{bfd} mechanism; during conversion and during output. @xref{BFD
+information loss}.
 
-@section How it works
-When an object file is opened, @code{bfd}
-tries to automatically determine the format of the input object file, a
-descriptor is built in memory with pointers to routines to access
-elements of the object file's data structures.
+@node BFD outline,,,
+@section How it works: an outline of BFD
+When an object file is opened, @code{bfd} subroutines automatically
+determine the format of the input object file, and build a descriptor in
+memory with pointers to routines that will be used to access elements of
+the object file's data structures.
 
 As different information from the the object files is required
-@code{bfd} reads from different sections of the file and processes
-them. For example a very common operation for the linker is processing
-symbol tables.  Each @code{bfd} back end provides a routine for
-converting between the object file's representation of symbols and an
-internal canonical format. When the linker asks for the symbol table
-of an object file, it calls through the memory pointer to the relevant
-@code{bfd} back end routine which reads and converts the table into
-the canonical form.  Linker then operates upon the common form. When
-the link is finished and the linker writes the symbol table of the
-output file, another @code{bfd} back end routine is called which takes
-the newly created symbol table and converts it into the output format.
-
-@section Information Leaks
-@table @bullet{}
-@item Information lost during output.
-The output formats supported by @code{bfd} do not provide identical 
-facilities, and information which may be described in one form 
-has no where to go in another format. One example of this would be
-alignment information in @code{b.out}. There is no where in an @code{a.out}
-format file to store alignment information on the contained data, so when
-a file is linked from @code{b.out} and an @code{a.out} image is produced,
-alignment information is lost. (Note that in this case the linker has the
-alignment information internally, so the link is performed correctly). 
+@code{bfd} reads from different sections of the file and processes them.
+For example a very common operation for the linker is processing symbol
+tables.  Each @code{bfd} back end provides a routine for converting
+between the object file's representation of symbols and an internal
+canonical format. When the linker asks for the symbol table of an object
+file, it calls through the memory pointer to the relevant @code{bfd}
+back end routine which reads and converts the table into a canonical
+form.  The linker then operates upon the common form. When the link is
+finished and the linker writes the symbol table of the output file,
+another @code{bfd} back end routine is called which takes the newly
+created symbol table and converts it into the chosen output format.
+
+@node BFD information loss,,,
+@section Information Loss
+@emph{Information can be lost during output.} The output formats
+supported by @code{bfd} do not provide identical facilities, and
+information which may be described in one form has nowhere to go in
+another format. One example of this is alignment information in
+@code{b.out}. There is nowhere in an @code{a.out} format file to store
+alignment information on the contained data, so when a file is linked
+from @code{b.out} and an @code{a.out} image is produced, alignment
+information will not propagate to the output file. (The linker will
+still use the alignment information internally, so the link is performed
+correctly).
 
 Another example is COFF section names. COFF files may contain an
 unlimited number of sections, each one with a textual section name. If
-the target of the link is a format which does not have many sections
-(eg @code{a.out}) or has sections without names (eg the Oasys format)
-the link cannot be done simply. It is possible to circumvent this
-problem by describing the desired input section to output section
-mapping with the command language.
-
-@item Information lost during canonicalization.  
-The @code{bfd}
-internal canonical form of the external formats is not exhaustive,
-there are structures in input formats for which there is no direct
-representation internally.  This means that the @code{bfd} back ends
-cannot maintain all the data richness through the transformation
-between external to internal and back to external formats.
+the target of the link is a format which does not have many sections (eg
+@code{a.out}) or has sections without names (eg the Oasys format) the
+link cannot be done simply. You can circumvent this problem by
+describing the desired input-to-output section mapping with the command
+language.
+
+@emph{Information lost during canonicalization.}  The @code{bfd} internal
+canonical form of the external formats is not exhaustive; there are
+structures in input formats for which there is no direct representation
+internally.  This means that the @code{bfd} back ends cannot maintain
+all possible data richness through the transformation between external to
+internal and back to external formats.
 
 This limitation is only a problem when using the linker to read one
 format and write another. Each @code{bfd} back end is responsible for
@@ -927,57 +1389,60 @@ canonical form has structures which are opaque to the @code{bfd} core,
 and exported only to the back ends. When a file is read in one format,
 the canonical form is generated for @code{bfd} and the linker. At the
 same time, the back end saves away any information which may otherwise
-be lost. If the data is then written back to the same back end, the
-back end routine will be able to use the canonical form provided by
-the @code{bfd} core as well as the information it prepared earlier.
-Since there is a great deal of commonality between back ends, this
-mechanism is very useful. There is no information lost when linking
-big endian COFF to little endian COFF, or from a.out to b.out. When a
-mixture of formats are linked, the information is only lost from the
-files with a different format to the destination.  
-@end table 
+be lost. If the data is then written back to the same back end, the back
+end routine will be able to use the canonical form provided by the
+@code{bfd} core as well as the information it prepared earlier.  Since
+there is a great deal of commonality between back ends, this mechanism
+is very useful. There is no information lost for this reason when
+linking big endian COFF to little endian COFF, or from @code{a.out} to
+@code{b.out}.  When a mixture of formats is linked, the information is
+only lost from the files whose format differs from the destination.
+
+@node Mechanism,,,
 @section Mechanism 
-The smallest amount of information is preserved when there
-is a small union between the information provided by the source
-format, that stored by the canonical format and the information needed
-by the destination format. A brief description of the canonical form
-will help the user appreciate what is possible to be maintained
-between conversions.
-
-@table @bullet 
-@item file level Information on target machine
-architecture, particular implementation and format type are stored on
-a per file basis. Other information includes a demand pageable bit and
-a write protected bit.  Note that information like Unix magic numbers
-is not stored here, only the magic numbers meaning, so a ZMAGIC file
-would have both the demand pageable bit and the write protected text
-bit set.
-
-The byte order of the target is stored on a per file basis, so that
-both big and little endian object files may be linked together at the
-same time.
-@item section level
+The greatest potential for loss of information is when there is least
+overlap between the information provided by the source format, that
+stored by the canonical format and the information needed by the
+destination format. A brief description of the canonical form may help
+you appreciate what kinds of data you can count on preserving across
+conversions.
+
+@table @emph
+@item files
+Information on target machine architecture, particular implementation
+and format type are stored on a per-file basis. Other information
+includes a demand pageable bit and a write protected bit.  Note that
+information like Unix magic numbers is not stored here---only the magic
+numbers' meaning, so a @code{ZMAGIC} file would have both the demand pageable
+bit and the write protected text bit set.
+
+The byte order of the target is stored on a per-file basis, so that
+both big- and little-endian object files may be linked with one another.
+
+@item sections
 Each section in the input file contains the name of the section, the
 original address in the object file, various flags, size and alignment
 information and pointers into other @code{bfd} data structures.
-@item symbol level
+
+@item symbols
 Each symbol contains a pointer to the object file which originally
-defined it, its name, value and various flags bits. When a symbol
-table is read in all symbols are relocated to make them relative to
-the base of the section they were defined in, so each symbol points to
-the containing section. Each symbol also has a varying amount of
-hidden data to contain private data for the back end. Since the symbol
-points to the original file, the symbol private data format is
-accessible. Operations may be done to a list of symbols of wildly
+defined it, its name, value and various flag bits. When a symbol table
+is read in, all symbols are relocated to make them relative to the base
+of the section where they were defined, so that each symbol points to
+its containing section. Each symbol also has a varying amount of hidden
+data to contain private data for the BFD back end. Since the symbol
+points to the original file, the private data format for that symbol is
+accessible.  @code{gld} can operate on a collection of symbols of wildly
 different formats without problems.
 
 Normal global and simple local symbols are maintained on output, so an
-output file, no matter the format will retain symbols pointing to
-functions, globals, statics and commons.  Some symbol information is
-not worth retaining; in @code{a.out} type information is stored in the
-symbol table as long symbol names. This information would be useless
-to most coff debuggers and may be thrown away with appropriate command
-line switches. (Note that gdb does support stabs in coff).
+output file (no matter its format) will retain symbols pointing to
+functions and to global, static, and common variables.  Some symbol
+information is not worth retaining; in @code{a.out} type information is
+stored in the symbol table as long symbol names. This information would
+be useless to most COFF debuggers and may be thrown away with
+appropriate command line switches. (The GNU debugger @code{gdb} does
+support @code{a.out} style debugging information in COFF).
 
 There is one word of type information within the symbol, so if the
 format supports symbol type information within symbols - (eg COFF,
@@ -985,6 +1450,8 @@ IEEE, Oasys) and the type is simple enough to fit within one word
 (nearly everything but aggregates) the information will be preserved.
 
 @item relocation level
+@c FIXME: I don't understand "relocation record" from this so I can't
+@c FIXME...improve the explanation to make it clear...
 Each canonical relocation record contains a pointer to the symbol to
 relocate to, the offset of the data to relocate, the section the data
 is in and a pointer to a relocation type descriptor. Relocation is
@@ -999,16 +1466,16 @@ has no such relocation type.
 
 @item line numbers
 Line numbers have to be relocated along with the symbol information.
-Each symbol with an associated list of line number records points to
-the first record of the list.  The head of a line number list consists
-of a pointer to the symbol, which allows divination of the address of
-the function who's line number is being described. The rest of the
-list is tuples offsets into the section and line indexes. Any format
-which can simply derive this information can pass it without lossage
+Each symbol with an associated list of line number records points to the
+first record of the list.  The head of a line number list consists of a
+pointer to the symbol, which allows divination of the address of the
+function whose line number is being described. The rest of the list is
+made up of pairs: offsets into the section and line numbers. Any format
+which can simply derive this information can pass it successfully
 between formats (COFF, IEEE and Oasys).
 @end table
 
-
+@contents
 @bye