Generate manpage out of the texinfo files using texi2mdoc

4 files changed, 22381 insertions, 0 deletions

diff --git a/contrib/binutils/binutils/doc/binutils.7 b/contrib/binutils/binutils/doc/binutils.7
new file mode 100644
index 0000000..2c4c0e1
--- /dev/null
+++ b/contrib/binutils/binutils/doc/binutils.7
@@ -0,0 +1,4917 @@
+.Dd 2015-03-02
+.Dt BINUTILS 7
+.Os
+.Sh NAME
+.Nm binutils
+.Nd GNU Binary Utilities
+.Sh  Introduction
+This brief manual contains documentation for the GNU binary utilities version "2.17.50
+[FreeBSD] 2007-07-03":
+.Pp
+This document is distributed under the terms of the GNU Free Documentation
+License. A copy of the license is included in the section entitled "GNU Free
+Documentation License".
+.Pp
+.Sh  ar
+.Bd -literal -offset indent
+ar [-]p[mod [relpos] [count]] archive [member...]
+ar -M [ <mri-script ]
+.Ed
+.Pp
+The GNU
+.Xr ar
+program creates, modifies, and extracts from archives. An
+.Em archive
+is a single file holding a collection of other files in a structure that makes
+it possible to retrieve the original individual files (called
+.Em members
+of the archive).
+.Pp
+The original files' contents, mode (permissions), timestamp, owner, and group
+are preserved in the archive, and can be restored on extraction.
+.Pp
+GNU
+.Xr ar
+can maintain archives whose members have names of any length; however, depending
+on how
+.Xr ar
+is configured on your system, a limit on member-name length may be imposed
+for compatibility with archive formats maintained with other tools. If it
+exists, the limit is often 15 characters (typical of formats related to a.out)
+or 16 characters (typical of formats related to coff).
+.Pp
+.Xr ar
+is considered a binary utility because archives of this sort are most often
+used as
+.Em libraries
+holding commonly needed subroutines.
+.Pp
+.Xr ar
+creates an index to the symbols defined in relocatable object modules in the
+archive when you specify the modifier
+.Li s .
+Once created, this index is updated in the archive whenever
+.Xr ar
+makes a change to its contents (save for the
+.Li q
+update operation). An archive with such an index speeds up linking to the
+library, and allows routines in the library to call each other without regard
+to their placement in the archive.
+.Pp
+You may use
+.Li nm -s
+or
+.Li nm --print-armap
+to list this index table. If an archive lacks the table, another form of
+.Xr ar
+called
+.Xr ranlib
+can be used to add just the table.
+.Pp
+GNU
+.Xr ar
+is designed to be compatible with two different facilities. You can control
+its activity using command-line options, like the different varieties of
+.Xr ar
+on Unix systems; or, if you specify the single command-line option
+.Op -M ,
+you can control it with a script supplied via standard input, like the MRI
+\(lqlibrarian\(rq program.
+.Pp
+.Ss  Controlling Xr ar on the Command Line
+.Bd -literal -offset indent
+ar [-X32_64] [-]p[mod [relpos] [count]] archive [member...]
+.Ed
+.Pp
+When you use
+.Xr ar
+in the Unix style,
+.Xr ar
+insists on at least two arguments to execute: one keyletter specifying the
+.Em operation
+(optionally accompanied by other keyletters specifying
+.Em modifiers ) ,
+and the archive name to act on.
+.Pp
+Most operations can also accept further
+.Va member
+arguments, specifying particular files to operate on.
+.Pp
+GNU
+.Xr ar
+allows you to mix the operation code
+.Va p
+and modifier flags
+.Va mod
+in any order, within the first command-line argument.
+.Pp
+If you wish, you may begin the first command-line argument with a dash.
+.Pp
+The
+.Va p
+keyletter specifies what operation to execute; it may be any of the following,
+but you must specify only one of them:
+.Pp
+.Bl -tag -width Ds
+.It  d
+.Em Delete
+modules from the archive. Specify the names of modules to be deleted as
+.Va member
+\&...; the archive is untouched if you specify no files to delete.
+.Pp
+If you specify the
+.Li v
+modifier,
+.Xr ar
+lists each module as it is deleted.
+.Pp
+.It  m
+Use this operation to
+.Em move
+members in an archive.
+.Pp
+The ordering of members in an archive can make a difference in how programs
+are linked using the library, if a symbol is defined in more than one member.
+.Pp
+If no modifiers are used with
+.Li m ,
+any members you name in the
+.Va member
+arguments are moved to the
+.Em end
+of the archive; you can use the
+.Li a ,
+.Li b ,
+or
+.Li i
+modifiers to move them to a specified place instead.
+.Pp
+.It  p
+.Em Print
+the specified members of the archive, to the standard output file. If the
+.Li v
+modifier is specified, show the member name before copying its contents to
+standard output.
+.Pp
+If you specify no
+.Va member
+arguments, all the files in the archive are printed.
+.Pp
+.It  q
+.Em Quick append ;
+Historically, add the files
+.Va member
+\&...to the end of
+.Va archive ,
+without checking for replacement.
+.Pp
+The modifiers
+.Li a ,
+.Li b ,
+and
+.Li i
+do
+.Em not
+affect this operation; new members are always placed at the end of the archive.
+.Pp
+The modifier
+.Li v
+makes
+.Xr ar
+list each file as it is appended.
+.Pp
+Since the point of this operation is speed, the archive's symbol table index
+is not updated, even if it already existed; you can use
+.Li ar s
+or
+.Xr ranlib
+explicitly to update the symbol table index.
+.Pp
+However, too many different systems assume quick append rebuilds the index,
+so GNU
+.Xr ar
+implements
+.Li q
+as a synonym for
+.Li r .
+.Pp
+.It  r
+Insert the files
+.Va member
+\&...into
+.Va archive
+(with
+.Em replacement ) .
+This operation differs from
+.Li q
+in that any previously existing members are deleted if their names match those
+being added.
+.Pp
+If one of the files named in
+.Va member
+\&...does not exist,
+.Xr ar
+displays an error message, and leaves undisturbed any existing members of
+the archive matching that name.
+.Pp
+By default, new members are added at the end of the file; but you may use
+one of the modifiers
+.Li a ,
+.Li b ,
+or
+.Li i
+to request placement relative to some existing member.
+.Pp
+The modifier
+.Li v
+used with this operation elicits a line of output for each file inserted,
+along with one of the letters
+.Li a
+or
+.Li r
+to indicate whether the file was appended (no old member deleted) or replaced.
+.Pp
+.It  t
+Display a
+.Em table
+listing the contents of
+.Va archive ,
+or those of the files listed in
+.Va member
+\&...that are present in the archive. Normally only the member name is shown; if
+you also want to see the modes (permissions), timestamp, owner, group, and
+size, you can request that by also specifying the
+.Li v
+modifier.
+.Pp
+If you do not specify a
+.Va member ,
+all files in the archive are listed.
+.Pp
+If there is more than one file with the same name (say,
+.Li fie )
+in an archive (say
+.Li b.a ) ,
+.Li ar t b.a fie
+lists only the first instance; to see them all, you must ask for a complete
+listing---in our example,
+.Li ar t b.a .
+.Pp
+.It  x
+.Em Extract
+members (named
+.Va member )
+from the archive. You can use the
+.Li v
+modifier with this operation, to request that
+.Xr ar
+list each name as it extracts it.
+.Pp
+If you do not specify a
+.Va member ,
+all files in the archive are extracted.
+.Pp
+.El
+A number of modifiers (
+.Va mod )
+may immediately follow the
+.Va p
+keyletter, to specify variations on an operation's behavior:
+.Pp
+.Bl -tag -width Ds
+.It  a
+Add new files
+.Em after
+an existing member of the archive. If you use the modifier
+.Li a ,
+the name of an existing archive member must be present as the
+.Va relpos
+argument, before the
+.Va archive
+specification.
+.Pp
+.It  b
+Add new files
+.Em before
+an existing member of the archive. If you use the modifier
+.Li b ,
+the name of an existing archive member must be present as the
+.Va relpos
+argument, before the
+.Va archive
+specification. (same as
+.Li i ) .
+.Pp
+.It  c
+.Em Create
+the archive. The specified
+.Va archive
+is always created if it did not exist, when you request an update. But a warning
+is issued unless you specify in advance that you expect to create it, by using
+this modifier.
+.Pp
+.It  f
+Truncate names in the archive. GNU
+.Xr ar
+will normally permit file names of any length. This will cause it to create
+archives which are not compatible with the native
+.Xr ar
+program on some systems. If this is a concern, the
+.Li f
+modifier may be used to truncate file names when putting them in the archive.
+.Pp
+.It  i
+Insert new files
+.Em before
+an existing member of the archive. If you use the modifier
+.Li i ,
+the name of an existing archive member must be present as the
+.Va relpos
+argument, before the
+.Va archive
+specification. (same as
+.Li b ) .
+.Pp
+.It  l
+This modifier is accepted but not used.
+.Pp
+.It  N
+Uses the
+.Va count
+parameter. This is used if there are multiple entries in the archive with
+the same name. Extract or delete instance
+.Va count
+of the given name from the archive.
+.Pp
+.It  o
+Preserve the
+.Em original
+dates of members when extracting them. If you do not specify this modifier,
+files extracted from the archive are stamped with the time of extraction.
+.Pp
+.It  P
+Use the full path name when matching names in the archive. GNU
+.Xr ar
+can not create an archive with a full path name (such archives are not POSIX
+complaint), but other archive creators can. This option will cause GNU
+.Xr ar
+to match file names using a complete path name, which can be convenient when
+extracting a single file from an archive created by another tool.
+.Pp
+.It  s
+Write an object-file index into the archive, or update an existing one, even
+if no other change is made to the archive. You may use this modifier flag
+either with any operation, or alone. Running
+.Li ar s
+on an archive is equivalent to running
+.Li ranlib
+on it.
+.Pp
+.It  S
+Do not generate an archive symbol table. This can speed up building a large
+library in several steps. The resulting archive can not be used with the linker.
+In order to build a symbol table, you must omit the
+.Li S
+modifier on the last execution of
+.Li ar ,
+or you must run
+.Li ranlib
+on the archive.
+.Pp
+.It  u
+Normally,
+.Li ar r
+\&...inserts all files listed into the archive. If you would like to insert
+.Em only
+those of the files you list that are newer than existing members of the same
+names, use this modifier. The
+.Li u
+modifier is allowed only for the operation
+.Li r
+(replace). In particular, the combination
+.Li qu
+is not allowed, since checking the timestamps would lose any speed advantage
+from the operation
+.Li q .
+.Pp
+.It  v
+This modifier requests the
+.Em verbose
+version of an operation. Many operations display additional information, such
+as filenames processed, when the modifier
+.Li v
+is appended.
+.Pp
+.It  V
+This modifier shows the version number of
+.Xr ar .
+.El
+.Pp
+.Xr ar
+ignores an initial option spelt
+.Li -X32_64 ,
+for compatibility with AIX. The behaviour produced by this option is the default
+for GNU
+.Xr ar .
+.Xr ar
+does not support any of the other
+.Li -X
+options; in particular, it does not support
+.Op -X32
+which is the default for AIX
+.Xr ar .
+.Pp
+.Ss  Controlling Xr ar with a Script
+.Bd -literal -offset indent
+ar -M [ <script ]
+.Ed
+.Pp
+If you use the single command-line option
+.Li -M
+with
+.Xr ar ,
+you can control its operation with a rudimentary command language. This form
+of
+.Xr ar
+operates interactively if standard input is coming directly from a terminal.
+During interactive use,
+.Xr ar
+prompts for input (the prompt is
+.Li AR > ) ,
+and continues executing even after errors. If you redirect standard input
+to a script file, no prompts are issued, and
+.Xr ar
+abandons execution (with a nonzero exit code) on any error.
+.Pp
+The
+.Xr ar
+command language is
+.Em not
+designed to be equivalent to the command-line options; in fact, it provides
+somewhat less control over archives. The only purpose of the command language
+is to ease the transition to GNU
+.Xr ar
+for developers who already have scripts written for the MRI \(lqlibrarian\(rq program.
+.Pp
+The syntax for the
+.Xr ar
+command language is straightforward:
+.Bl -bullet
+.It
+commands are recognized in upper or lower case; for example,
+.Li LIST
+is the same as
+.Li list .
+In the following descriptions, commands are shown in upper case for clarity.
+.Pp
+.It
+a single command may appear on each line; it is the first word on the line.
+.Pp
+.It
+empty lines are allowed, and have no effect.
+.Pp
+.It
+comments are allowed; text after either of the characters
+.Li *
+or
+.Li ;
+is ignored.
+.Pp
+.It
+Whenever you use a list of names as part of the argument to an
+.Xr ar
+command, you can separate the individual names with either commas or blanks.
+Commas are shown in the explanations below, for clarity.
+.Pp
+.It
+.Li +
+is used as a line continuation character; if
+.Li +
+appears at the end of a line, the text on the following line is considered
+part of the current command.
+.El
+.Pp
+Here are the commands you can use in
+.Xr ar
+scripts, or when using
+.Xr ar
+interactively. Three of them have special significance:
+.Pp
+.Li OPEN
+or
+.Li CREATE
+specify a
+.Em current archive ,
+which is a temporary file required for most of the other commands.
+.Pp
+.Li SAVE
+commits the changes so far specified by the script. Prior to
+.Li SAVE ,
+commands affect only the temporary copy of the current archive.
+.Pp
+.Bl -tag -width Ds
+.It  ADDLIB Va archive
+.It  ADDLIB Va archive ( Va module, Va module, ... Va module)
+Add all the contents of
+.Va archive
+(or, if specified, each named
+.Va module
+from
+.Va archive )
+to the current archive.
+.Pp
+Requires prior use of
+.Li OPEN
+or
+.Li CREATE .
+.Pp
+.It  ADDMOD Va member, Va member, ... Va member
+Add each named
+.Va member
+as a module in the current archive.
+.Pp
+Requires prior use of
+.Li OPEN
+or
+.Li CREATE .
+.Pp
+.It  CLEAR
+Discard the contents of the current archive, canceling the effect of any operations
+since the last
+.Li SAVE .
+May be executed (with no effect) even if no current archive is specified.
+.Pp
+.It  CREATE Va archive
+Creates an archive, and makes it the current archive (required for many other
+commands). The new archive is created with a temporary name; it is not actually
+saved as
+.Va archive
+until you use
+.Li SAVE .
+You can overwrite existing archives; similarly, the contents of any existing
+file named
+.Va archive
+will not be destroyed until
+.Li SAVE .
+.Pp
+.It  DELETE Va module, Va module, ... Va module
+Delete each listed
+.Va module
+from the current archive; equivalent to
+.Li ar -d Va archive Va module ... Va module .
+.Pp
+Requires prior use of
+.Li OPEN
+or
+.Li CREATE .
+.Pp
+.It  DIRECTORY Va archive ( Va module, ... Va module)
+.It  DIRECTORY Va archive ( Va module, ... Va module) Va outputfile
+List each named
+.Va module
+present in
+.Va archive .
+The separate command
+.Li VERBOSE
+specifies the form of the output: when verbose output is off, output is like
+that of
+.Li ar -t Va archive Va module... .
+When verbose output is on, the listing is like
+.Li ar -tv Va archive Va module... .
+.Pp
+Output normally goes to the standard output stream; however, if you specify
+.Va outputfile
+as a final argument,
+.Xr ar
+directs the output to that file.
+.Pp
+.It  END
+Exit from
+.Xr ar ,
+with a
+.Li 0
+exit code to indicate successful completion. This command does not save the
+output file; if you have changed the current archive since the last
+.Li SAVE
+command, those changes are lost.
+.Pp
+.It  EXTRACT Va module, Va module, ... Va module
+Extract each named
+.Va module
+from the current archive, writing them into the current directory as separate
+files. Equivalent to
+.Li ar -x Va archive Va module... .
+.Pp
+Requires prior use of
+.Li OPEN
+or
+.Li CREATE .
+.Pp
+.It  LIST
+Display full contents of the current archive, in \(lqverbose\(rq style regardless
+of the state of
+.Li VERBOSE .
+The effect is like
+.Li ar tv Va archive .
+(This single command is a GNU
+.Xr ar
+enhancement, rather than present for MRI compatibility.)
+.Pp
+Requires prior use of
+.Li OPEN
+or
+.Li CREATE .
+.Pp
+.It  OPEN Va archive
+Opens an existing archive for use as the current archive (required for many
+other commands). Any changes as the result of subsequent commands will not
+actually affect
+.Va archive
+until you next use
+.Li SAVE .
+.Pp
+.It  REPLACE Va module, Va module, ... Va module
+In the current archive, replace each existing
+.Va module
+(named in the
+.Li REPLACE
+arguments) from files in the current working directory. To execute this command
+without errors, both the file, and the module in the current archive, must
+exist.
+.Pp
+Requires prior use of
+.Li OPEN
+or
+.Li CREATE .
+.Pp
+.It  VERBOSE
+Toggle an internal flag governing the output from
+.Li DIRECTORY .
+When the flag is on,
+.Li DIRECTORY
+output matches output from
+.Li ar -tv
+\&...\&.
+.Pp
+.It  SAVE
+Commit your changes to the current archive, and actually save it as a file
+with the name specified in the last
+.Li CREATE
+or
+.Li OPEN
+command.
+.Pp
+Requires prior use of
+.Li OPEN
+or
+.Li CREATE .
+.Pp
+.El
+.Sh  nm
+.Bd -literal -offset indent
+nm [-a|--debug-syms] [-g|--extern-only]
+   [-B] [-C|--demangle[=style]] [-D|--dynamic]
+   [-S|--print-size] [-s|--print-armap]
+   [-A|-o|--print-file-name][--special-syms]
+   [-n|-v|--numeric-sort] [-p|--no-sort]
+   [-r|--reverse-sort] [--size-sort] [-u|--undefined-only]
+   [-t radix|--radix=radix] [-P|--portability]
+   [--target=bfdname] [-fformat|--format=format]
+   [--defined-only] [-l|--line-numbers] [--no-demangle]
+   [-V|--version] [-X 32_64] [--help]  [objfile...]
+.Ed
+.Pp
+GNU
+.Xr nm
+lists the symbols from object files
+.Va objfile
+\&...\&. If no object files are listed as arguments,
+.Xr nm
+assumes the file
+.Pa a.out .
+.Pp
+For each symbol,
+.Xr nm
+shows:
+.Pp
+.Bl -bullet
+.It
+The symbol value, in the radix selected by options (see below), or hexadecimal
+by default.
+.Pp
+.It
+The symbol type. At least the following types are used; others are, as well,
+depending on the object file format. If lowercase, the symbol is local; if
+uppercase, the symbol is global (external).
+.Pp
+.Bl -tag -width Ds
+.It  A
+The symbol's value is absolute, and will not be changed by further linking.
+.Pp
+.It  B
+The symbol is in the uninitialized data section (known as BSS).
+.Pp
+.It  C
+The symbol is common. Common symbols are uninitialized data. When linking,
+multiple common symbols may appear with the same name. If the symbol is defined
+anywhere, the common symbols are treated as undefined references. For more
+details on common symbols, see the discussion of --warn-common in Options,,Linker
+options,ld.info,The GNU linker.
+.Pp
+.It  D
+The symbol is in the initialized data section.
+.Pp
+.It  G
+The symbol is in an initialized data section for small objects. Some object
+file formats permit more efficient access to small data objects, such as a
+global int variable as opposed to a large global array.
+.Pp
+.It  I
+The symbol is an indirect reference to another symbol. This is a GNU extension
+to the a.out object file format which is rarely used.
+.Pp
+.It  N
+The symbol is a debugging symbol.
+.Pp
+.It  R
+The symbol is in a read only data section.
+.Pp
+.It  S
+The symbol is in an uninitialized data section for small objects.
+.Pp
+.It  T
+The symbol is in the text (code) section.
+.Pp
+.It  U
+The symbol is undefined.
+.Pp
+.It  V
+The symbol is a weak object. When a weak defined symbol is linked with a normal
+defined symbol, the normal defined symbol is used with no error. When a weak
+undefined symbol is linked and the symbol is not defined, the value of the
+weak symbol becomes zero with no error.
+.Pp
+.It  W
+The symbol is a weak symbol that has not been specifically tagged as a weak
+object symbol. When a weak defined symbol is linked with a normal defined
+symbol, the normal defined symbol is used with no error. When a weak undefined
+symbol is linked and the symbol is not defined, the value of the symbol is
+determined in a system-specific manner without error. On some systems, uppercase
+indicates that a default value has been specified.
+.Pp
+.It  -
+The symbol is a stabs symbol in an a.out object file. In this case, the next
+values printed are the stabs other field, the stabs desc field, and the stab
+type. Stabs symbols are used to hold debugging information. For more information,
+see Top,Stabs,Stabs Overview,stabs.info, The \(lqstabs\(rq debug format.
+.Pp
+.It  ?
+The symbol type is unknown, or object file format specific.
+.El
+.Pp
+.It
+The symbol name.
+.El
+.Pp
+The long and short forms of options, shown here as alternatives, are equivalent.
+.Pp
+.Bl -tag -width Ds
+.It  -A
+.It  -o
+.It  --print-file-name
+Precede each symbol by the name of the input file (or archive member) in which
+it was found, rather than identifying the input file once only, before all
+of its symbols.
+.Pp
+.It  -a
+.It  --debug-syms
+Display all symbols, even debugger-only symbols; normally these are not listed.
+.Pp
+.It  -B
+The same as
+.Op --format=bsd
+(for compatibility with the MIPS
+.Xr nm ) .
+.Pp
+.It  -C
+.It  --demangle[= Va style]
+Decode (
+.Em demangle )
+low-level symbol names into user-level names. Besides removing any initial
+underscore prepended by the system, this makes C++ function names readable.
+Different compilers have different mangling styles. The optional demangling
+style argument can be used to choose an appropriate demangling style for your
+compiler.See Section
+.Dq c++filt ,
+for more information on demangling.
+.Pp
+.It  --no-demangle
+Do not demangle low-level symbol names. This is the default.
+.Pp
+.It  -D
+.It  --dynamic
+Display the dynamic symbols rather than the normal symbols. This is only meaningful
+for dynamic objects, such as certain types of shared libraries.
+.Pp
+.It  -f Va format
+.It  --format= Va format
+Use the output format
+.Va format ,
+which can be
+.Li bsd ,
+.Li sysv ,
+or
+.Li posix .
+The default is
+.Li bsd .
+Only the first character of
+.Va format
+is significant; it can be either upper or lower case.
+.Pp
+.It  -g
+.It  --extern-only
+Display only external symbols.
+.Pp
+.It  -l
+.It  --line-numbers
+For each symbol, use debugging information to try to find a filename and line
+number. For a defined symbol, look for the line number of the address of the
+symbol. For an undefined symbol, look for the line number of a relocation
+entry which refers to the symbol. If line number information can be found,
+print it after the other symbol information.
+.Pp
+.It  -n
+.It  -v
+.It  --numeric-sort
+Sort symbols numerically by their addresses, rather than alphabetically by
+their names.
+.Pp
+.It  -p
+.It  --no-sort
+Do not bother to sort the symbols in any order; print them in the order encountered.
+.Pp
+.It  -P
+.It  --portability
+Use the POSIX.2 standard output format instead of the default format. Equivalent
+to
+.Li -f posix .
+.Pp
+.It  -S
+.It  --print-size
+Print size, not the value, of defined symbols for the
+.Li bsd
+output format.
+.Pp
+.It  -s
+.It  --print-armap
+When listing symbols from archive members, include the index: a mapping (stored
+in the archive by
+.Xr ar
+or
+.Xr ranlib )
+of which modules contain definitions for which names.
+.Pp
+.It  -r
+.It  --reverse-sort
+Reverse the order of the sort (whether numeric or alphabetic); let the last
+come first.
+.Pp
+.It  --size-sort
+Sort symbols by size. The size is computed as the difference between the value
+of the symbol and the value of the symbol with the next higher value. If the
+.Li bsd
+output format is used the size of the symbol is printed, rather than the value,
+and
+.Li -S
+must be used in order both size and value to be printed.
+.Pp
+.It  --special-syms
+Display symbols which have a target-specific special meaning. These symbols
+are usually used by the target for some special processing and are not normally
+helpful when included included in the normal symbol lists. For example for
+ARM targets this option would skip the mapping symbols used to mark transitions
+between ARM code, THUMB code and data.
+.Pp
+.It  -t Va radix
+.It  --radix= Va radix
+Use
+.Va radix
+as the radix for printing the symbol values. It must be
+.Li d
+for decimal,
+.Li o
+for octal, or
+.Li x
+for hexadecimal.
+.Pp
+.It  --target= Va bfdname
+Specify an object code format other than your system's default format.See Section
+.Dq Target Selection ,
+for more information.
+.Pp
+.It  -u
+.It  --undefined-only
+Display only undefined symbols (those external to each object file).
+.Pp
+.It  --defined-only
+Display only defined symbols for each object file.
+.Pp
+.It  -V
+.It  --version
+Show the version number of
+.Xr nm
+and exit.
+.Pp
+.It  -X
+This option is ignored for compatibility with the AIX version of
+.Xr nm .
+It takes one parameter which must be the string
+.Op 32_64 .
+The default mode of AIX
+.Xr nm
+corresponds to
+.Op -X 32 ,
+which is not supported by GNU
+.Xr nm .
+.Pp
+.It  --help
+Show a summary of the options to
+.Xr nm
+and exit.
+.El
+.Pp
+.Sh  objcopy
+.Bd -literal -offset indent
+objcopy [-F bfdname|--target=bfdname]
+        [-I bfdname|--input-target=bfdname]
+        [-O bfdname|--output-target=bfdname]
+        [-B bfdarch|--binary-architecture=bfdarch]
+        [-S|--strip-all]
+        [-g|--strip-debug]
+        [-K symbolname|--keep-symbol=symbolname]
+        [-N symbolname|--strip-symbol=symbolname]
+        [--strip-unneeded-symbol=symbolname]
+        [-G symbolname|--keep-global-symbol=symbolname]
+        [--localize-hidden]
+        [-L symbolname|--localize-symbol=symbolname]
+        [--globalize-symbol=symbolname]
+        [-W symbolname|--weaken-symbol=symbolname]
+        [-w|--wildcard]
+        [-x|--discard-all]
+        [-X|--discard-locals]
+        [-b byte|--byte=byte]
+        [-i interleave|--interleave=interleave]
+        [-j sectionname|--only-section=sectionname]
+        [-R sectionname|--remove-section=sectionname]
+        [-p|--preserve-dates]
+        [--debugging]
+        [--gap-fill=val]
+        [--pad-to=address]
+        [--set-start=val]
+        [--adjust-start=incr]
+        [--change-addresses=incr]
+        [--change-section-address section{=,+,-}val]
+        [--change-section-lma section{=,+,-}val]
+        [--change-section-vma section{=,+,-}val]
+        [--change-warnings] [--no-change-warnings]
+        [--set-section-flags section=flags]
+        [--add-section sectionname=filename]
+        [--rename-section oldname=newname[,flags]]
+        [--change-leading-char] [--remove-leading-char]
+        [--reverse-bytes=num]
+        [--srec-len=ival] [--srec-forceS3]
+        [--redefine-sym old=new]
+        [--redefine-syms=filename]
+        [--weaken]
+        [--keep-symbols=filename]
+        [--strip-symbols=filename]
+        [--strip-unneeded-symbols=filename]
+        [--keep-global-symbols=filename]
+        [--localize-symbols=filename]
+        [--globalize-symbols=filename]
+        [--weaken-symbols=filename]
+        [--alt-machine-code=index]
+        [--prefix-symbols=string]
+        [--prefix-sections=string]
+        [--prefix-alloc-sections=string]
+        [--add-GNU-debuglink=path-to-file]
+        [--keep-file-symbols]
+        [--only-keep-debug]
+        [--extract-symbol]
+        [--writable-text]
+        [--readonly-text]
+        [--pure]
+        [--impure]
+        [-v|--verbose]
+        [-V|--version]
+        [--help] [--info]
+        infile [outfile]
+.Ed
+.Pp
+The GNU
+.Xr objcopy
+utility copies the contents of an object file to another.
+.Xr objcopy
+uses the GNU bfd Library to read and write the object files. It can write
+the destination object file in a format different from that of the source
+object file. The exact behavior of
+.Xr objcopy
+is controlled by command-line options. Note that
+.Xr objcopy
+should be able to copy a fully linked file between any two formats. However,
+copying a relocatable object file between any two formats may not work as
+expected.
+.Pp
+.Xr objcopy
+creates temporary files to do its translations and deletes them afterward.
+.Xr objcopy
+uses bfd to do all its translation work; it has access to all the formats
+described in bfd and thus is able to recognize most formats without being
+told explicitly.See Section
+.Dq BFD .
+.Pp
+.Xr objcopy
+can be used to generate S-records by using an output target of
+.Li srec
+(e.g., use
+.Li -O srec ) .
+.Pp
+.Xr objcopy
+can be used to generate a raw binary file by using an output target of
+.Li binary
+(e.g., use
+.Op -O binary ) .
+When
+.Xr objcopy
+generates a raw binary file, it will essentially produce a memory dump of
+the contents of the input object file. All symbols and relocation information
+will be discarded. The memory dump will start at the load address of the lowest
+section copied into the output file.
+.Pp
+When generating an S-record or a raw binary file, it may be helpful to use
+.Op -S
+to remove sections containing debugging information. In some cases
+.Op -R
+will be useful to remove sections which contain information that is not needed
+by the binary file.
+.Pp
+Note---
+.Xr objcopy
+is not able to change the endianness of its input files. If the input format
+has an endianness (some formats do not),
+.Xr objcopy
+can only copy the inputs into file formats that have the same endianness or
+which have no endianness (e.g.,
+.Li srec ) .
+(However, see the
+.Op --reverse-bytes
+option.)
+.Pp
+.Bl -tag -width Ds
+.It  Va infile
+.It  Va outfile
+The input and output files, respectively. If you do not specify
+.Va outfile ,
+.Xr objcopy
+creates a temporary file and destructively renames the result with the name
+of
+.Va infile .
+.Pp
+.It  -I Va bfdname
+.It  --input-target= Va bfdname
+Consider the source file's object format to be
+.Va bfdname ,
+rather than attempting to deduce it.See Section
+.Dq Target Selection ,
+for more information.
+.Pp
+.It  -O Va bfdname
+.It  --output-target= Va bfdname
+Write the output file using the object format
+.Va bfdname .
+See Section.Dq Target Selection ,
+for more information.
+.Pp
+.It  -F Va bfdname
+.It  --target= Va bfdname
+Use
+.Va bfdname
+as the object format for both the input and the output file; i.e., simply
+transfer data from source to destination with no translation.See Section
+.Dq Target Selection ,
+for more information.
+.Pp
+.It  -B Va bfdarch
+.It  --binary-architecture= Va bfdarch
+Useful when transforming a raw binary input file into an object file. In this
+case the output architecture can be set to
+.Va bfdarch .
+This option will be ignored if the input file has a known
+.Va bfdarch .
+You can access this binary data inside a program by referencing the special
+symbols that are created by the conversion process. These symbols are called
+_binary_
+.Va objfile
+_start, _binary_
+.Va objfile
+_end and _binary_
+.Va objfile
+_size. e.g. you can transform a picture file into an object file and then
+access it in your code using these symbols.
+.Pp
+.It  -j Va sectionname
+.It  --only-section= Va sectionname
+Copy only the named section from the input file to the output file. This option
+may be given more than once. Note that using this option inappropriately may
+make the output file unusable.
+.Pp
+.It  -R Va sectionname
+.It  --remove-section= Va sectionname
+Remove any section named
+.Va sectionname
+from the output file. This option may be given more than once. Note that using
+this option inappropriately may make the output file unusable.
+.Pp
+.It  -S
+.It  --strip-all
+Do not copy relocation and symbol information from the source file.
+.Pp
+.It  -g
+.It  --strip-debug
+Do not copy debugging symbols or sections from the source file.
+.Pp
+.It  --strip-unneeded
+Strip all symbols that are not needed for relocation processing.
+.Pp
+.It  -K Va symbolname
+.It  --keep-symbol= Va symbolname
+When stripping symbols, keep symbol
+.Va symbolname
+even if it would normally be stripped. This option may be given more than
+once.
+.Pp
+.It  -N Va symbolname
+.It  --strip-symbol= Va symbolname
+Do not copy symbol
+.Va symbolname
+from the source file. This option may be given more than once.
+.Pp
+.It  --strip-unneeded-symbol= Va symbolname
+Do not copy symbol
+.Va symbolname
+from the source file unless it is needed by a relocation. This option may
+be given more than once.
+.Pp
+.It  -G Va symbolname
+.It  --keep-global-symbol= Va symbolname
+Keep only symbol
+.Va symbolname
+global. Make all other symbols local to the file, so that they are not visible
+externally. This option may be given more than once.
+.Pp
+.It  --localize-hidden
+In an ELF object, mark all symbols that have hidden or internal visibility
+as local. This option applies on top of symbol-specific localization options
+such as
+.Op -L .
+.Pp
+.It  -L Va symbolname
+.It  --localize-symbol= Va symbolname
+Make symbol
+.Va symbolname
+local to the file, so that it is not visible externally. This option may be
+given more than once.
+.Pp
+.It  -W Va symbolname
+.It  --weaken-symbol= Va symbolname
+Make symbol
+.Va symbolname
+weak. This option may be given more than once.
+.Pp
+.It  --globalize-symbol= Va symbolname
+Give symbol
+.Va symbolname
+global scoping so that it is visible outside of the file in which it is defined.
+This option may be given more than once.
+.Pp
+.It  -w
+.It  --wildcard
+Permit regular expressions in
+.Va symbolname
+s used in other command line options. The question mark (?), asterisk (*),
+backslash (\e) and square brackets ([]) operators can be used anywhere in the
+symbol name. If the first character of the symbol name is the exclamation
+point (!) then the sense of the switch is reversed for that symbol. For example:
+.Pp
+.Bd -literal -offset indent
+  -w -W !foo -W fo*
+.Ed
+.Pp
+would cause objcopy to weaken all symbols that start with \(lqfo\(rq except for the
+symbol \(lqfoo\(rq.
+.Pp
+.It  -x
+.It  --discard-all
+Do not copy non-global symbols from the source file.
+.Pp
+.It  -X
+.It  --discard-locals
+Do not copy compiler-generated local symbols. (These usually start with
+.Li L
+or
+.Li . . )
+.Pp
+.It  -b Va byte
+.It  --byte= Va byte
+Keep only every
+.Va byte
+th byte of the input file (header data is not affected).
+.Va byte
+can be in the range from 0 to
+.Va interleave
+-1, where
+.Va interleave
+is given by the
+.Op -i
+or
+.Op --interleave
+option, or the default of 4. This option is useful for creating files to program
+rom. It is typically used with an
+.Li srec
+output target.
+.Pp
+.It  -i Va interleave
+.It  --interleave= Va interleave
+Only copy one out of every
+.Va interleave
+bytes. Select which byte to copy with the
+.Op -b
+or
+.Op --byte
+option. The default is 4.
+.Xr objcopy
+ignores this option if you do not specify either
+.Op -b
+or
+.Op --byte .
+.Pp
+.It  -p
+.It  --preserve-dates
+Set the access and modification dates of the output file to be the same as
+those of the input file.
+.Pp
+.It  --debugging
+Convert debugging information, if possible. This is not the default because
+only certain debugging formats are supported, and the conversion process can
+be time consuming.
+.Pp
+.It  --gap-fill Va val
+Fill gaps between sections with
+.Va val .
+This operation applies to the
+.Em load address
+(LMA) of the sections. It is done by increasing the size of the section with
+the lower address, and filling in the extra space created with
+.Va val .
+.Pp
+.It  --pad-to Va address
+Pad the output file up to the load address
+.Va address .
+This is done by increasing the size of the last section. The extra space is
+filled in with the value specified by
+.Op --gap-fill
+(default zero).
+.Pp
+.It  --set-start Va val
+Set the start address of the new file to
+.Va val .
+Not all object file formats support setting the start address.
+.Pp
+.It  --change-start Va incr
+.It  --adjust-start Va incr
+Change the start address by adding
+.Va incr .
+Not all object file formats support setting the start address.
+.Pp
+.It  --change-addresses Va incr
+.It  --adjust-vma Va incr
+Change the VMA and LMA addresses of all sections, as well as the start address,
+by adding
+.Va incr .
+Some object file formats do not permit section addresses to be changed arbitrarily.
+Note that this does not relocate the sections; if the program expects sections
+to be loaded at a certain address, and this option is used to change the sections
+such that they are loaded at a different address, the program may fail.
+.Pp
+.It  --change-section-address Va section{=,+,-} Va val
+.It  --adjust-section-vma Va section{=,+,-} Va val
+Set or change both the VMA address and the LMA address of the named
+.Va section .
+If
+.Li =
+is used, the section address is set to
+.Va val .
+Otherwise,
+.Va val
+is added to or subtracted from the section address. See the comments under
+.Op --change-addresses ,
+above. If
+.Va section
+does not exist in the input file, a warning will be issued, unless
+.Op --no-change-warnings
+is used.
+.Pp
+.It  --change-section-lma Va section{=,+,-} Va val
+Set or change the LMA address of the named
+.Va section .
+The LMA address is the address where the section will be loaded into memory
+at program load time. Normally this is the same as the VMA address, which
+is the address of the section at program run time, but on some systems, especially
+those where a program is held in ROM, the two can be different. If
+.Li =
+is used, the section address is set to
+.Va val .
+Otherwise,
+.Va val
+is added to or subtracted from the section address. See the comments under
+.Op --change-addresses ,
+above. If
+.Va section
+does not exist in the input file, a warning will be issued, unless
+.Op --no-change-warnings
+is used.
+.Pp
+.It  --change-section-vma Va section{=,+,-} Va val
+Set or change the VMA address of the named
+.Va section .
+The VMA address is the address where the section will be located once the
+program has started executing. Normally this is the same as the LMA address,
+which is the address where the section will be loaded into memory, but on
+some systems, especially those where a program is held in ROM, the two can
+be different. If
+.Li =
+is used, the section address is set to
+.Va val .
+Otherwise,
+.Va val
+is added to or subtracted from the section address. See the comments under
+.Op --change-addresses ,
+above. If
+.Va section
+does not exist in the input file, a warning will be issued, unless
+.Op --no-change-warnings
+is used.
+.Pp
+.It  --change-warnings
+.It  --adjust-warnings
+If
+.Op --change-section-address
+or
+.Op --change-section-lma
+or
+.Op --change-section-vma
+is used, and the named section does not exist, issue a warning. This is the
+default.
+.Pp
+.It  --no-change-warnings
+.It  --no-adjust-warnings
+Do not issue a warning if
+.Op --change-section-address
+or
+.Op --adjust-section-lma
+or
+.Op --adjust-section-vma
+is used, even if the named section does not exist.
+.Pp
+.It  --set-section-flags Va section= Va flags
+Set the flags for the named section. The
+.Va flags
+argument is a comma separated string of flag names. The recognized names are
+.Li alloc ,
+.Li contents ,
+.Li load ,
+.Li noload ,
+.Li readonly ,
+.Li code ,
+.Li data ,
+.Li rom ,
+.Li share ,
+and
+.Li debug .
+You can set the
+.Li contents
+flag for a section which does not have contents, but it is not meaningful
+to clear the
+.Li contents
+flag of a section which does have contents--just remove the section instead.
+Not all flags are meaningful for all object file formats.
+.Pp
+.It  --add-section Va sectionname= Va filename
+Add a new section named
+.Va sectionname
+while copying the file. The contents of the new section are taken from the
+file
+.Va filename .
+The size of the section will be the size of the file. This option only works
+on file formats which can support sections with arbitrary names.
+.Pp
+.It  --rename-section Va oldname= Va newname[, Va flags]
+Rename a section from
+.Va oldname
+to
+.Va newname ,
+optionally changing the section's flags to
+.Va flags
+in the process. This has the advantage over usng a linker script to perform
+the rename in that the output stays as an object file and does not become
+a linked executable.
+.Pp
+This option is particularly helpful when the input format is binary, since
+this will always create a section called .data. If for example, you wanted
+instead to create a section called .rodata containing binary data you could
+use the following command line to achieve it:
+.Pp
+.Bd -literal -offset indent
+  objcopy -I binary -O <output_format> -B <architecture> \e
+   --rename-section .data=.rodata,alloc,load,readonly,data,contents \e
+   <input_binary_file> <output_object_file>
+.Ed
+.Pp
+.It  --change-leading-char
+Some object file formats use special characters at the start of symbols. The
+most common such character is underscore, which compilers often add before
+every symbol. This option tells
+.Xr objcopy
+to change the leading character of every symbol when it converts between object
+file formats. If the object file formats use the same leading character, this
+option has no effect. Otherwise, it will add a character, or remove a character,
+or change a character, as appropriate.
+.Pp
+.It  --remove-leading-char
+If the first character of a global symbol is a special symbol leading character
+used by the object file format, remove the character. The most common symbol
+leading character is underscore. This option will remove a leading underscore
+from all global symbols. This can be useful if you want to link together objects
+of different file formats with different conventions for symbol names. This
+is different from
+.Op --change-leading-char
+because it always changes the symbol name when appropriate, regardless of
+the object file format of the output file.
+.Pp
+.It  --reverse-bytes= Va num
+Reverse the bytes in a section with output contents. A section length must
+be evenly divisible by the value given in order for the swap to be able to
+take place. Reversing takes place before the interleaving is performed.
+.Pp
+This option is used typically in generating ROM images for problematic target
+systems. For example, on some target boards, the 32-bit words fetched from
+8-bit ROMs are re-assembled in little-endian byte order regardless of the
+CPU byte order. Depending on the programming model, the endianness of the
+ROM may need to be modified.
+.Pp
+Consider a simple file with a section containing the following eight bytes:
+.Li 12345678 .
+.Pp
+Using
+.Li --reverse-bytes=2
+for the above example, the bytes in the output file would be ordered
+.Li 21436587 .
+.Pp
+Using
+.Li --reverse-bytes=4
+for the above example, the bytes in the output file would be ordered
+.Li 43218765 .
+.Pp
+By using
+.Li --reverse-bytes=2
+for the above example, followed by
+.Li --reverse-bytes=4
+on the output file, the bytes in the second output file would be ordered
+.Li 34127856 .
+.Pp
+.It  --srec-len= Va ival
+Meaningful only for srec output. Set the maximum length of the Srecords being
+produced to
+.Va ival .
+This length covers both address, data and crc fields.
+.Pp
+.It  --srec-forceS3
+Meaningful only for srec output. Avoid generation of S1/S2 records, creating
+S3-only record format.
+.Pp
+.It  --redefine-sym Va old= Va new
+Change the name of a symbol
+.Va old ,
+to
+.Va new .
+This can be useful when one is trying link two things together for which you
+have no source, and there are name collisions.
+.Pp
+.It  --redefine-syms= Va filename
+Apply
+.Op --redefine-sym
+to each symbol pair "
+.Va old
+.Va new "
+listed in the file
+.Va filename .
+.Va filename
+is simply a flat file, with one symbol pair per line. Line comments may be
+introduced by the hash character. This option may be given more than once.
+.Pp
+.It  --weaken
+Change all global symbols in the file to be weak. This can be useful when
+building an object which will be linked against other objects using the
+.Op -R
+option to the linker. This option is only effective when using an object file
+format which supports weak symbols.
+.Pp
+.It  --keep-symbols= Va filename
+Apply
+.Op --keep-symbol
+option to each symbol listed in the file
+.Va filename .
+.Va filename
+is simply a flat file, with one symbol name per line. Line comments may be
+introduced by the hash character. This option may be given more than once.
+.Pp
+.It  --strip-symbols= Va filename
+Apply
+.Op --strip-symbol
+option to each symbol listed in the file
+.Va filename .
+.Va filename
+is simply a flat file, with one symbol name per line. Line comments may be
+introduced by the hash character. This option may be given more than once.
+.Pp
+.It  --strip-unneeded-symbols= Va filename
+Apply
+.Op --strip-unneeded-symbol
+option to each symbol listed in the file
+.Va filename .
+.Va filename
+is simply a flat file, with one symbol name per line. Line comments may be
+introduced by the hash character. This option may be given more than once.
+.Pp
+.It  --keep-global-symbols= Va filename
+Apply
+.Op --keep-global-symbol
+option to each symbol listed in the file
+.Va filename .
+.Va filename
+is simply a flat file, with one symbol name per line. Line comments may be
+introduced by the hash character. This option may be given more than once.
+.Pp
+.It  --localize-symbols= Va filename
+Apply
+.Op --localize-symbol
+option to each symbol listed in the file
+.Va filename .
+.Va filename
+is simply a flat file, with one symbol name per line. Line comments may be
+introduced by the hash character. This option may be given more than once.
+.Pp
+.It  --globalize-symbols= Va filename
+Apply
+.Op --globalize-symbol
+option to each symbol listed in the file
+.Va filename .
+.Va filename
+is simply a flat file, with one symbol name per line. Line comments may be
+introduced by the hash character. This option may be given more than once.
+.Pp
+.It  --weaken-symbols= Va filename
+Apply
+.Op --weaken-symbol
+option to each symbol listed in the file
+.Va filename .
+.Va filename
+is simply a flat file, with one symbol name per line. Line comments may be
+introduced by the hash character. This option may be given more than once.
+.Pp
+.It  --alt-machine-code= Va index
+If the output architecture has alternate machine codes, use the
+.Va index
+th code instead of the default one. This is useful in case a machine is assigned
+an official code and the tool-chain adopts the new code, but other applications
+still depend on the original code being used. For ELF based architectures
+if the
+.Va index
+alternative does not exist then the value is treated as an absolute number
+to be stored in the e_machine field of the ELF header.
+.Pp
+.It  --writable-text
+Mark the output text as writable. This option isn't meaningful for all object
+file formats.
+.Pp
+.It  --readonly-text
+Make the output text write protected. This option isn't meaningful for all
+object file formats.
+.Pp
+.It  --pure
+Mark the output file as demand paged. This option isn't meaningful for all
+object file formats.
+.Pp
+.It  --impure
+Mark the output file as impure. This option isn't meaningful for all object
+file formats.
+.Pp
+.It  --prefix-symbols= Va string
+Prefix all symbols in the output file with
+.Va string .
+.Pp
+.It  --prefix-sections= Va string
+Prefix all section names in the output file with
+.Va string .
+.Pp
+.It  --prefix-alloc-sections= Va string
+Prefix all the names of all allocated sections in the output file with
+.Va string .
+.Pp
+.It  --add-GNU-debuglink= Va path-to-file
+Creates a .GNU_debuglink section which contains a reference to
+.Va path-to-file
+and adds it to the output file.
+.Pp
+.It  --keep-file-symbols
+When stripping a file, perhaps with
+.Op --strip-debug
+or
+.Op --strip-unneeded ,
+retain any symbols specifying source file names, which would otherwise get
+stripped.
+.Pp
+.It  --only-keep-debug
+Strip a file, removing contents of any sections that would not be stripped
+by
+.Op --strip-debug
+and leaving the debugging sections intact. In ELF files, this preserves all
+note sections in the output.
+.Pp
+The intention is that this option will be used in conjunction with
+.Op --add-GNU-debuglink
+to create a two part executable. One a stripped binary which will occupy less
+space in RAM and in a distribution and the second a debugging information
+file which is only needed if debugging abilities are required. The suggested
+procedure to create these files is as follows:
+.Pp
+.Bl -enum
+.It
+Link the executable as normal. Assuming that is is called
+.Li foo
+then...
+.It
+Run
+.Li objcopy --only-keep-debug foo foo.dbg
+to
+create a file containing the debugging info.
+.It
+Run
+.Li objcopy --strip-debug foo
+to create a
+stripped executable.
+.It
+Run
+.Li objcopy --add-GNU-debuglink=foo.dbg foo
+to add a link to the debugging info into the stripped executable.
+.El
+.Pp
+Note - the choice of
+.Li .dbg
+as an extension for the debug info file is arbitrary. Also the
+.Li --only-keep-debug
+step is optional. You could instead do this:
+.Pp
+.Bl -enum
+.It
+Link the executable as normal.
+.It
+Copy
+.Li foo
+to
+.Li foo.full
+.It
+Run
+.Li objcopy --strip-debug foo
+.It
+Run
+.Li objcopy --add-GNU-debuglink=foo.full foo
+.El
+.Pp
+i.e., the file pointed to by the
+.Op --add-GNU-debuglink
+can be the full executable. It does not have to be a file created by the
+.Op --only-keep-debug
+switch.
+.Pp
+Note - this switch is only intended for use on fully linked files. It does
+not make sense to use it on object files where the debugging information may
+be incomplete. Besides the GNU_debuglink feature currently only supports the
+presence of one filename containing debugging information, not multiple filenames
+on a one-per-object-file basis.
+.Pp
+.It  --extract-symbol
+Keep the file's section flags and symbols but remove all section data. Specifically,
+the option:
+.Pp
+.Bl -bullet
+.It
+sets the virtual and load addresses of every section to zero;
+.It
+removes the contents of all sections;
+.It
+sets the size of every section to zero; and
+.It
+sets the file's start address to zero.
+.El
+.Pp
+This option is used to build a
+.Pa .sym
+file for a VxWorks kernel. It can also be a useful way of reducing the size
+of a
+.Op --just-symbols
+linker input file.
+.Pp
+.It  -V
+.It  --version
+Show the version number of
+.Xr objcopy .
+.Pp
+.It  -v
+.It  --verbose
+Verbose output: list all object files modified. In the case of archives,
+.Li objcopy -V
+lists all members of the archive.
+.Pp
+.It  --help
+Show a summary of the options to
+.Xr objcopy .
+.Pp
+.It  --info
+Display a list showing all architectures and object formats available.
+.El
+.Pp
+.Sh  objdump
+.Bd -literal -offset indent
+objdump [-a|--archive-headers]
+        [-b bfdname|--target=bfdname]
+        [-C|--demangle[=style] ]
+        [-d|--disassemble]
+        [-D|--disassemble-all]
+        [-z|--disassemble-zeroes]
+        [-EB|-EL|--endian={big | little }]
+        [-f|--file-headers]
+        [--file-start-context]
+        [-g|--debugging]
+        [-e|--debugging-tags]
+        [-h|--section-headers|--headers]
+        [-i|--info]
+        [-j section|--section=section]
+        [-l|--line-numbers]
+        [-S|--source]
+        [-m machine|--architecture=machine]
+        [-M options|--disassembler-options=options]
+        [-p|--private-headers]
+        [-r|--reloc]
+        [-R|--dynamic-reloc]
+        [-s|--full-contents]
+        [-W|--dwarf]
+        [-G|--stabs]
+        [-t|--syms]
+        [-T|--dynamic-syms]
+        [-x|--all-headers]
+        [-w|--wide]
+        [--start-address=address]
+        [--stop-address=address]
+        [--prefix-addresses]
+        [--[no-]show-raw-insn]
+        [--adjust-vma=offset]
+        [--special-syms]
+        [-V|--version]
+        [-H|--help]
+        objfile...
+.Ed
+.Pp
+.Xr objdump
+displays information about one or more object files. The options control what
+particular information to display. This information is mostly useful to programmers
+who are working on the compilation tools, as opposed to programmers who just
+want their program to compile and work.
+.Pp
+.Va objfile
+\&...are the object files to be examined. When you specify archives,
+.Xr objdump
+shows information on each of the member object files.
+.Pp
+The long and short forms of options, shown here as alternatives, are equivalent.
+At least one option from the list
+.Op -a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-r,-R,-s,-S,-t,-T,-V,-x
+must be given.
+.Pp
+.Bl -tag -width Ds
+.It  -a
+.It  --archive-header
+If any of the
+.Va objfile
+files are archives, display the archive header information (in a format similar
+to
+.Li ls -l ) .
+Besides the information you could list with
+.Li ar tv ,
+.Li objdump -a
+shows the object file format of each archive member.
+.Pp
+.It  --adjust-vma= Va offset
+When dumping information, first add
+.Va offset
+to all the section addresses. This is useful if the section addresses do not
+correspond to the symbol table, which can happen when putting sections at
+particular addresses when using a format which can not represent section addresses,
+such as a.out.
+.Pp
+.It  -b Va bfdname
+.It  --target= Va bfdname
+Specify that the object-code format for the object files is
+.Va bfdname .
+This option may not be necessary;
+.Va objdump
+can automatically recognize many formats.
+.Pp
+For example,
+.Bd -literal -offset indent
+objdump -b oasys -m vax -h fu.o
+.Ed
+displays summary information from the section headers (
+.Op -h )
+of
+.Pa fu.o ,
+which is explicitly identified (
+.Op -m )
+as a VAX object file in the format produced by Oasys compilers. You can list
+the formats available with the
+.Op -i
+option.See Section
+.Dq Target Selection ,
+for more information.
+.Pp
+.It  -C
+.It  --demangle[= Va style]
+Decode (
+.Em demangle )
+low-level symbol names into user-level names. Besides removing any initial
+underscore prepended by the system, this makes C++ function names readable.
+Different compilers have different mangling styles. The optional demangling
+style argument can be used to choose an appropriate demangling style for your
+compiler.See Section
+.Dq c++filt ,
+for more information on demangling.
+.Pp
+.It  -g
+.It  --debugging
+Display debugging information. This attempts to parse debugging information
+stored in the file and print it out using a C like syntax. Only certain types
+of debugging information have been implemented. Some other types are supported
+by
+.Xr readelf -w .
+See Section.Dq readelf .
+.Pp
+.It  -e
+.It  --debugging-tags
+Like
+.Op -g ,
+but the information is generated in a format compatible with ctags tool.
+.Pp
+.It  -d
+.It  --disassemble
+Display the assembler mnemonics for the machine instructions from
+.Va objfile .
+This option only disassembles those sections which are expected to contain
+instructions.
+.Pp
+.It  -D
+.It  --disassemble-all
+Like
+.Op -d ,
+but disassemble the contents of all sections, not just those expected to contain
+instructions.
+.Pp
+.It  --prefix-addresses
+When disassembling, print the complete address on each line. This is the older
+disassembly format.
+.Pp
+.It  -EB
+.It  -EL
+.It  --endian={big|little}
+Specify the endianness of the object files. This only affects disassembly.
+This can be useful when disassembling a file format which does not describe
+endianness information, such as S-records.
+.Pp
+.It  -f
+.It  --file-headers
+Display summary information from the overall header of each of the
+.Va objfile
+files.
+.Pp
+.It  --file-start-context
+Specify that when displaying interlisted source code/disassembly (assumes
+.Op -S )
+from a file that has not yet been displayed, extend the context to the start
+of the file.
+.Pp
+.It  -h
+.It  --section-headers
+.It  --headers
+Display summary information from the section headers of the object file.
+.Pp
+File segments may be relocated to nonstandard addresses, for example by using
+the
+.Op -Ttext ,
+.Op -Tdata ,
+or
+.Op -Tbss
+options to
+.Xr ld .
+However, some object file formats, such as a.out, do not store the starting
+address of the file segments. In those situations, although
+.Xr ld
+relocates the sections correctly, using
+.Li objdump -h
+to list the file section headers cannot show the correct addresses. Instead,
+it shows the usual addresses, which are implicit for the target.
+.Pp
+.It  -H
+.It  --help
+Print a summary of the options to
+.Xr objdump
+and exit.
+.Pp
+.It  -i
+.It  --info
+Display a list showing all architectures and object formats available for
+specification with
+.Op -b
+or
+.Op -m .
+.Pp
+.It  -j Va name
+.It  --section= Va name
+Display information only for section
+.Va name .
+.Pp
+.It  -l
+.It  --line-numbers
+Label the display (using debugging information) with the filename and source
+line numbers corresponding to the object code or relocs shown. Only useful
+with
+.Op -d ,
+.Op -D ,
+or
+.Op -r .
+.Pp
+.It  -m Va machine
+.It  --architecture= Va machine
+Specify the architecture to use when disassembling object files. This can
+be useful when disassembling object files which do not describe architecture
+information, such as S-records. You can list the available architectures with
+the
+.Op -i
+option.
+.Pp
+.It  -M Va options
+.It  --disassembler-options= Va options
+Pass target specific information to the disassembler. Only supported on some
+targets. If it is necessary to specify more than one disassembler option then
+multiple
+.Op -M
+options can be used or can be placed together into a comma separated list.
+.Pp
+If the target is an ARM architecture then this switch can be used to select
+which register name set is used during disassembler. Specifying
+.Op -M reg-names-std
+(the default) will select the register names as used in ARM's instruction
+set documentation, but with register 13 called 'sp', register 14 called 'lr'
+and register 15 called 'pc'. Specifying
+.Op -M reg-names-apcs
+will select the name set used by the ARM Procedure Call Standard, whilst specifying
+.Op -M reg-names-raw
+will just use
+.Li r
+followed by the register number.
+.Pp
+There are also two variants on the APCS register naming scheme enabled by
+.Op -M reg-names-atpcs
+and
+.Op -M reg-names-special-atpcs
+which use the ARM/Thumb Procedure Call Standard naming conventions. (Either
+with the normal register names or the special register names).
+.Pp
+This option can also be used for ARM architectures to force the disassembler
+to interpret all instructions as Thumb instructions by using the switch
+.Op --disassembler-options=force-thumb .
+This can be useful when attempting to disassemble thumb code produced by other
+compilers.
+.Pp
+For the x86, some of the options duplicate functions of the
+.Op -m
+switch, but allow finer grained control. Multiple selections from the following
+may be specified as a comma separated string.
+.Op x86-64 ,
+.Op i386
+and
+.Op i8086
+select disassembly for the given architecture.
+.Op intel
+and
+.Op att
+select between intel syntax mode and AT&T syntax mode.
+.Op addr64 ,
+.Op addr32 ,
+.Op addr16 ,
+.Op data32
+and
+.Op data16
+specify the default address size and operand size. These four options will
+be overridden if
+.Op x86-64 ,
+.Op i386
+or
+.Op i8086
+appear later in the option string. Lastly,
+.Op suffix ,
+when in AT&T mode, instructs the disassembler to print a mnemonic suffix even
+when the suffix could be inferred by the operands.
+.Pp
+For PPC,
+.Op booke ,
+.Op booke32
+and
+.Op booke64
+select disassembly of BookE instructions.
+.Op 32
+and
+.Op 64
+select PowerPC and PowerPC64 disassembly, respectively.
+.Op e300
+selects disassembly for the e300 family.
+.Op 440
+selects disassembly for the PowerPC 440.
+.Pp
+For MIPS, this option controls the printing of instruction mnemonic names
+and register names in disassembled instructions. Multiple selections from
+the following may be specified as a comma separated string, and invalid options
+are ignored:
+.Pp
+.Bl -tag -width Ds
+.It  no-aliases
+Print the 'raw' instruction mnemonic instead of some pseudo instruction mnemonic.
+I.e., print 'daddu' or 'or' instead of 'move', 'sll' instead of 'nop', etc.
+.Pp
+.It  gpr-names= Va ABI
+Print GPR (general-purpose register) names as appropriate for the specified
+ABI. By default, GPR names are selected according to the ABI of the binary
+being disassembled.
+.Pp
+.It  fpr-names= Va ABI
+Print FPR (floating-point register) names as appropriate for the specified
+ABI. By default, FPR numbers are printed rather than names.
+.Pp
+.It  cp0-names= Va ARCH
+Print CP0 (system control coprocessor; coprocessor 0) register names as appropriate
+for the CPU or architecture specified by
+.Va ARCH .
+By default, CP0 register names are selected according to the architecture
+and CPU of the binary being disassembled.
+.Pp
+.It  hwr-names= Va ARCH
+Print HWR (hardware register, used by the
+.Li rdhwr
+instruction) names as appropriate for the CPU or architecture specified by
+.Va ARCH .
+By default, HWR names are selected according to the architecture and CPU of
+the binary being disassembled.
+.Pp
+.It  reg-names= Va ABI
+Print GPR and FPR names as appropriate for the selected ABI.
+.Pp
+.It  reg-names= Va ARCH
+Print CPU-specific register names (CP0 register and HWR names) as appropriate
+for the selected CPU or architecture.
+.El
+.Pp
+For any of the options listed above,
+.Va ABI
+or
+.Va ARCH
+may be specified as
+.Li numeric
+to have numbers printed rather than names, for the selected types of registers.
+You can list the available values of
+.Va ABI
+and
+.Va ARCH
+using the
+.Op --help
+option.
+.Pp
+For VAX, you can specify function entry addresses with
+.Op -M entry:0xf00ba .
+You can use this multiple times to properly disassemble VAX binary files that
+don't contain symbol tables (like ROM dumps). In these cases, the function
+entry mask would otherwise be decoded as VAX instructions, which would probably
+lead the rest of the function being wrongly disassembled.
+.Pp
+.It  -p
+.It  --private-headers
+Print information that is specific to the object file format. The exact information
+printed depends upon the object file format. For some object file formats,
+no additional information is printed.
+.Pp
+.It  -r
+.It  --reloc
+Print the relocation entries of the file. If used with
+.Op -d
+or
+.Op -D ,
+the relocations are printed interspersed with the disassembly.
+.Pp
+.It  -R
+.It  --dynamic-reloc
+Print the dynamic relocation entries of the file. This is only meaningful
+for dynamic objects, such as certain types of shared libraries.
+.Pp
+.It  -s
+.It  --full-contents
+Display the full contents of any sections requested. By default all non-empty
+sections are displayed.
+.Pp
+.It  -S
+.It  --source
+Display source code intermixed with disassembly, if possible. Implies
+.Op -d .
+.Pp
+.It  --show-raw-insn
+When disassembling instructions, print the instruction in hex as well as in
+symbolic form. This is the default except when
+.Op --prefix-addresses
+is used.
+.Pp
+.It  --no-show-raw-insn
+When disassembling instructions, do not print the instruction bytes. This
+is the default when
+.Op --prefix-addresses
+is used.
+.Pp
+.It  -W
+.It  --dwarf
+Displays the contents of the DWARF debug sections in the file, if any are
+present.
+.Pp
+.It  -G
+.It  --stabs
+Display the full contents of any sections requested. Display the contents
+of the .stab and .stab.index and .stab.excl sections from an ELF file. This
+is only useful on systems (such as Solaris 2.0) in which
+.Li .stab
+debugging symbol-table entries are carried in an ELF section. In most other
+file formats, debugging symbol-table entries are interleaved with linkage
+symbols, and are visible in the
+.Op --syms
+output. For more information on stabs symbols, see Top,Stabs,Stabs Overview,stabs.info,
+The \(lqstabs\(rq debug format.
+.Pp
+.It  --start-address= Va address
+Start displaying data at the specified address. This affects the output of
+the
+.Op -d ,
+.Op -r
+and
+.Op -s
+options.
+.Pp
+.It  --stop-address= Va address
+Stop displaying data at the specified address. This affects the output of
+the
+.Op -d ,
+.Op -r
+and
+.Op -s
+options.
+.Pp
+.It  -t
+.It  --syms
+Print the symbol table entries of the file. This is similar to the information
+provided by the
+.Li nm
+program.
+.Pp
+.It  -T
+.It  --dynamic-syms
+Print the dynamic symbol table entries of the file. This is only meaningful
+for dynamic objects, such as certain types of shared libraries. This is similar
+to the information provided by the
+.Li nm
+program when given the
+.Op -D
+(
+.Op --dynamic )
+option.
+.Pp
+.It  --special-syms
+When displaying symbols include those which the target considers to be special
+in some way and which would not normally be of interest to the user.
+.Pp
+.It  -V
+.It  --version
+Print the version number of
+.Xr objdump
+and exit.
+.Pp
+.It  -x
+.It  --all-headers
+Display all available header information, including the symbol table and relocation
+entries. Using
+.Op -x
+is equivalent to specifying all of
+.Op -a -f -h -p -r -t .
+.Pp
+.It  -w
+.It  --wide
+Format some lines for output devices that have more than 80 columns. Also
+do not truncate symbol names when they are displayed.
+.Pp
+.It  -z
+.It  --disassemble-zeroes
+Normally the disassembly output will skip blocks of zeroes. This option directs
+the disassembler to disassemble those blocks, just like any other data.
+.El
+.Pp
+.Sh  ranlib
+.Bd -literal -offset indent
+ranlib [-vV] archive
+.Ed
+.Pp
+.Xr ranlib
+generates an index to the contents of an archive and stores it in the archive.
+The index lists each symbol defined by a member of an archive that is a relocatable
+object file.
+.Pp
+You may use
+.Li nm -s
+or
+.Li nm --print-armap
+to list this index.
+.Pp
+An archive with such an index speeds up linking to the library and allows
+routines in the library to call each other without regard to their placement
+in the archive.
+.Pp
+The GNU
+.Xr ranlib
+program is another form of GNU
+.Xr ar ;
+running
+.Xr ranlib
+is completely equivalent to executing
+.Li ar -s .
+See Section.Dq ar .
+.Pp
+.Bl -tag -width Ds
+.It  -v
+.It  -V
+.It  --version
+Show the version number of
+.Xr ranlib .
+.El
+.Pp
+.Sh  size
+.Bd -literal -offset indent
+size [-A|-B|--format=compatibility]
+     [--help]
+     [-d|-o|-x|--radix=number]
+     [-t|--totals]
+     [--target=bfdname] [-V|--version]
+     [objfile...]
+.Ed
+.Pp
+The GNU
+.Xr size
+utility lists the section sizes---and the total size---for each of the object
+or archive files
+.Va objfile
+in its argument list. By default, one line of output is generated for each
+object file or each module in an archive.
+.Pp
+.Va objfile
+\&...are the object files to be examined. If none are specified, the file
+.Li a.out
+will be used.
+.Pp
+The command line options have the following meanings:
+.Pp
+.Bl -tag -width Ds
+.It  -A
+.It  -B
+.It  --format= Va compatibility
+Using one of these options, you can choose whether the output from GNU
+.Xr size
+resembles output from System V
+.Xr size
+(using
+.Op -A ,
+or
+.Op --format=sysv ) ,
+or Berkeley
+.Xr size
+(using
+.Op -B ,
+or
+.Op --format=berkeley ) .
+The default is the one-line format similar to Berkeley's.
+.Pp
+Here is an example of the Berkeley (default) format of output from
+.Xr size :
+.Bd -literal -offset indent
+$ size --format=Berkeley ranlib size
+text    data    bss     dec     hex     filename
+294880  81920   11592   388392  5ed28   ranlib
+294880  81920   11888   388688  5ee50   size
+.Ed
+.Pp
+This is the same data, but displayed closer to System V conventions:
+.Pp
+.Bd -literal -offset indent
+$ size --format=SysV ranlib size
+ranlib  :
+section         size         addr
+\&.text         294880         8192
+\&.data          81920       303104
+\&.bss           11592       385024
+Total         388392
+
+
+size  :
+section         size         addr
+\&.text         294880         8192
+\&.data          81920       303104
+\&.bss           11888       385024
+Total         388688
+.Ed
+.Pp
+.It  --help
+Show a summary of acceptable arguments and options.
+.Pp
+.It  -d
+.It  -o
+.It  -x
+.It  --radix= Va number
+Using one of these options, you can control whether the size of each section
+is given in decimal (
+.Op -d ,
+or
+.Op --radix=10 ) ;
+octal (
+.Op -o ,
+or
+.Op --radix=8 ) ;
+or hexadecimal (
+.Op -x ,
+or
+.Op --radix=16 ) .
+In
+.Op --radix= Va number ,
+only the three values (8, 10, 16) are supported. The total size is always
+given in two radices; decimal and hexadecimal for
+.Op -d
+or
+.Op -x
+output, or octal and hexadecimal if you're using
+.Op -o .
+.Pp
+.It  -t
+.It  --totals
+Show totals of all objects listed (Berkeley format listing mode only).
+.Pp
+.It  --target= Va bfdname
+Specify that the object-code format for
+.Va objfile
+is
+.Va bfdname .
+This option may not be necessary;
+.Xr size
+can automatically recognize many formats.See Section
+.Dq Target Selection ,
+for more information.
+.Pp
+.It  -V
+.It  --version
+Display the version number of
+.Xr size .
+.El
+.Pp
+.Sh  strings
+.Bd -literal -offset indent
+strings [-afov] [-min-len]
+        [-n min-len] [--bytes=min-len]
+        [-t radix] [--radix=radix]
+        [-e encoding] [--encoding=encoding]
+        [-] [--all] [--print-file-name]
+        [-T bfdname] [--target=bfdname]
+        [--help] [--version] file...
+.Ed
+.Pp
+For each
+.Va file
+given, GNU
+.Xr strings
+prints the printable character sequences that are at least 4 characters long
+(or the number given with the options below) and are followed by an unprintable
+character. By default, it only prints the strings from the initialized and
+loaded sections of object files; for other types of files, it prints the strings
+from the whole file.
+.Pp
+.Xr strings
+is mainly useful for determining the contents of non-text files.
+.Pp
+.Bl -tag -width Ds
+.It  -a
+.It  --all
+.It  -
+Do not scan only the initialized and loaded sections of object files; scan
+the whole files.
+.Pp
+.It  -f
+.It  --print-file-name
+Print the name of the file before each string.
+.Pp
+.It  --help
+Print a summary of the program usage on the standard output and exit.
+.Pp
+.It  - Va min-len
+.It  -n Va min-len
+.It  --bytes= Va min-len
+Print sequences of characters that are at least
+.Va min-len
+characters long, instead of the default 4.
+.Pp
+.It  -o
+Like
+.Li -t o .
+Some other versions of
+.Xr strings
+have
+.Op -o
+act like
+.Li -t d
+instead. Since we can not be compatible with both ways, we simply chose one.
+.Pp
+.It  -t Va radix
+.It  --radix= Va radix
+Print the offset within the file before each string. The single character
+argument specifies the radix of the offset---
+.Li o
+for octal,
+.Li x
+for hexadecimal, or
+.Li d
+for decimal.
+.Pp
+.It  -e Va encoding
+.It  --encoding= Va encoding
+Select the character encoding of the strings that are to be found. Possible
+values for
+.Va encoding
+are:
+.Li s
+= single-7-bit-byte characters (ASCII, ISO 8859, etc., default),
+.Li S
+= single-8-bit-byte characters,
+.Li b
+= 16-bit bigendian,
+.Li l
+= 16-bit littleendian,
+.Li B
+= 32-bit bigendian,
+.Li L
+= 32-bit littleendian. Useful for finding wide character strings.
+.Pp
+.It  -T Va bfdname
+.It  --target= Va bfdname
+Specify an object code format other than your system's default format.See Section
+.Dq Target Selection ,
+for more information.
+.Pp
+.It  -v
+.It  --version
+Print the program version number on the standard output and exit.
+.El
+.Pp
+.Sh  strip
+.Bd -literal -offset indent
+strip [-F bfdname |--target=bfdname]
+      [-I bfdname |--input-target=bfdname]
+      [-O bfdname |--output-target=bfdname]
+      [-s|--strip-all]
+      [-S|-g|-d|--strip-debug]
+      [-K symbolname |--keep-symbol=symbolname]
+      [-N symbolname |--strip-symbol=symbolname]
+      [-w|--wildcard]
+      [-x|--discard-all] [-X |--discard-locals]
+      [-R sectionname |--remove-section=sectionname]
+      [-o file] [-p|--preserve-dates]
+      [--keep-file-symbols]
+      [--only-keep-debug]
+      [-v |--verbose] [-V|--version]
+      [--help] [--info]
+      objfile...
+.Ed
+.Pp
+GNU
+.Xr strip
+discards all symbols from object files
+.Va objfile .
+The list of object files may include archives. At least one object file must
+be given.
+.Pp
+.Xr strip
+modifies the files named in its argument, rather than writing modified copies
+under different names.
+.Pp
+.Bl -tag -width Ds
+.It  -F Va bfdname
+.It  --target= Va bfdname
+Treat the original
+.Va objfile
+as a file with the object code format
+.Va bfdname ,
+and rewrite it in the same format.See Section
+.Dq Target Selection ,
+for more information.
+.Pp
+.It  --help
+Show a summary of the options to
+.Xr strip
+and exit.
+.Pp
+.It  --info
+Display a list showing all architectures and object formats available.
+.Pp
+.It  -I Va bfdname
+.It  --input-target= Va bfdname
+Treat the original
+.Va objfile
+as a file with the object code format
+.Va bfdname .
+See Section.Dq Target Selection ,
+for more information.
+.Pp
+.It  -O Va bfdname
+.It  --output-target= Va bfdname
+Replace
+.Va objfile
+with a file in the output format
+.Va bfdname .
+See Section.Dq Target Selection ,
+for more information.
+.Pp
+.It  -R Va sectionname
+.It  --remove-section= Va sectionname
+Remove any section named
+.Va sectionname
+from the output file. This option may be given more than once. Note that using
+this option inappropriately may make the output file unusable.
+.Pp
+.It  -s
+.It  --strip-all
+Remove all symbols.
+.Pp
+.It  -g
+.It  -S
+.It  -d
+.It  --strip-debug
+Remove debugging symbols only.
+.Pp
+.It  --strip-unneeded
+Remove all symbols that are not needed for relocation processing.
+.Pp
+.It  -K Va symbolname
+.It  --keep-symbol= Va symbolname
+When stripping symbols, keep symbol
+.Va symbolname
+even if it would normally be stripped. This option may be given more than
+once.
+.Pp
+.It  -N Va symbolname
+.It  --strip-symbol= Va symbolname
+Remove symbol
+.Va symbolname
+from the source file. This option may be given more than once, and may be
+combined with strip options other than
+.Op -K .
+.Pp
+.It  -o Va file
+Put the stripped output in
+.Va file ,
+rather than replacing the existing file. When this argument is used, only
+one
+.Va objfile
+argument may be specified.
+.Pp
+.It  -p
+.It  --preserve-dates
+Preserve the access and modification dates of the file.
+.Pp
+.It  -w
+.It  --wildcard
+Permit regular expressions in
+.Va symbolname
+s used in other command line options. The question mark (?), asterisk (*),
+backslash (\e) and square brackets ([]) operators can be used anywhere in the
+symbol name. If the first character of the symbol name is the exclamation
+point (!) then the sense of the switch is reversed for that symbol. For example:
+.Pp
+.Bd -literal -offset indent
+  -w -K !foo -K fo*
+.Ed
+.Pp
+would cause strip to only keep symbols that start with the letters \(lqfo\(rq, but
+to discard the symbol \(lqfoo\(rq.
+.Pp
+.It  -x
+.It  --discard-all
+Remove non-global symbols.
+.Pp
+.It  -X
+.It  --discard-locals
+Remove compiler-generated local symbols. (These usually start with
+.Li L
+or
+.Li . . )
+.Pp
+.It  --keep-file-symbols
+When stripping a file, perhaps with
+.Op --strip-debug
+or
+.Op --strip-unneeded ,
+retain any symbols specifying source file names, which would otherwise get
+stripped.
+.Pp
+.It  --only-keep-debug
+Strip a file, removing contents of any sections that would not be stripped
+by
+.Op --strip-debug
+and leaving the debugging sections intact. In ELF files, this preserves all
+note sections in the output.
+.Pp
+The intention is that this option will be used in conjunction with
+.Op --add-GNU-debuglink
+to create a two part executable. One a stripped binary which will occupy less
+space in RAM and in a distribution and the second a debugging information
+file which is only needed if debugging abilities are required. The suggested
+procedure to create these files is as follows:
+.Pp
+.Bl -enum
+.It
+Link the executable as normal. Assuming that is is called
+.Li foo
+then...
+.It
+Run
+.Li objcopy --only-keep-debug foo foo.dbg
+to
+create a file containing the debugging info.
+.It
+Run
+.Li objcopy --strip-debug foo
+to create a
+stripped executable.
+.It
+Run
+.Li objcopy --add-GNU-debuglink=foo.dbg foo
+to add a link to the debugging info into the stripped executable.
+.El
+.Pp
+Note - the choice of
+.Li .dbg
+as an extension for the debug info file is arbitrary. Also the
+.Li --only-keep-debug
+step is optional. You could instead do this:
+.Pp
+.Bl -enum
+.It
+Link the executable as normal.
+.It
+Copy
+.Li foo
+to
+.Li foo.full
+.It
+Run
+.Li strip --strip-debug foo
+.It
+Run
+.Li objcopy --add-GNU-debuglink=foo.full foo
+.El
+.Pp
+ie the file pointed to by the
+.Op --add-GNU-debuglink
+can be the full executable. It does not have to be a file created by the
+.Op --only-keep-debug
+switch.
+.Pp
+Note - this switch is only intended for use on fully linked files. It does
+not make sense to use it on object files where the debugging information may
+be incomplete. Besides the GNU_debuglink feature currently only supports the
+presence of one filename containing debugging information, not multiple filenames
+on a one-per-object-file basis.
+.Pp
+.It  -V
+.It  --version
+Show the version number for
+.Xr strip .
+.Pp
+.It  -v
+.It  --verbose
+Verbose output: list all object files modified. In the case of archives,
+.Li strip -v
+lists all members of the archive.
+.El
+.Pp
+.Sh  c++filt
+.Bd -literal -offset indent
+c++filt [-_|--strip-underscores]
+        [-n|--no-strip-underscores]
+        [-p|--no-params]
+        [-t|--types]
+        [-i|--no-verbose]
+        [-s format|--format=format]
+        [--help]  [--version]  [symbol...]
+.Ed
+.Pp
+The C++ and Java languages provide function overloading, which means that
+you can write many functions with the same name, providing that each function
+takes parameters of different types. In order to be able to distinguish these
+similarly named functions C++ and Java encode them into a low-level assembler
+name which uniquely identifies each different version. This process is known
+as
+.Em mangling .
+The
+.Xr c++filt
+program does the inverse mapping: it decodes (
+.Em demangles )
+low-level names into user-level names so that they can be read.
+.Pp
+Every alphanumeric word (consisting of letters, digits, underscores, dollars,
+or periods) seen in the input is a potential mangled name. If the name decodes
+into a C++ name, the C++ name replaces the low-level name in the output, otherwise
+the original word is output. In this way you can pass an entire assembler
+source file, containing mangled names, through
+.Xr c++filt
+and see the same source file containing demangled names.
+.Pp
+You can also use
+.Xr c++filt
+to decipher individual symbols by passing them on the command line:
+.Pp
+.Bd -literal -offset indent
+c++filt symbol
+.Ed
+.Pp
+If no
+.Va symbol
+arguments are given,
+.Xr c++filt
+reads symbol names from the standard input instead. All the results are printed
+on the standard output. The difference between reading names from the command
+line versus reading names from the standard input is that command line arguments
+are expected to be just mangled names and no checking is performed to separate
+them from surrounding text. Thus for example:
+.Pp
+.Bd -literal -offset indent
+c++filt -n _Z1fv
+.Ed
+.Pp
+will work and demangle the name to \(lqf()\(rq whereas:
+.Pp
+.Bd -literal -offset indent
+c++filt -n _Z1fv,
+.Ed
+.Pp
+will not work. (Note the extra comma at the end of the mangled name which
+makes it invalid). This command however will work:
+.Pp
+.Bd -literal -offset indent
+echo _Z1fv, | c++filt -n
+.Ed
+.Pp
+and will display \(lqf(),\(rq ie the demangled name followed by a trailing comma.
+This behaviour is because when the names are read from the standard input
+it is expected that they might be part of an assembler source file where there
+might be extra, extraneous characters trailing after a mangled name. eg:
+.Pp
+.Bd -literal -offset indent
+    .type   _Z1fv, @function
+.Ed
+.Pp
+.Bl -tag -width Ds
+.It  -_
+.It  --strip-underscores
+On some systems, both the C and C++ compilers put an underscore in front of
+every name. For example, the C name
+.Li foo
+gets the low-level name
+.Li _foo .
+This option removes the initial underscore. Whether
+.Xr c++filt
+removes the underscore by default is target dependent.
+.Pp
+.It  -j
+.It  --java
+Prints demangled names using Java syntax. The default is to use C++ syntax.
+.Pp
+.It  -n
+.It  --no-strip-underscores
+Do not remove the initial underscore.
+.Pp
+.It  -p
+.It  --no-params
+When demangling the name of a function, do not display the types of the function's
+parameters.
+.Pp
+.It  -t
+.It  --types
+Attempt to demangle types as well as function names. This is disabled by default
+since mangled types are normally only used internally in the compiler, and
+they can be confused with non-mangled names. eg a function called \(lqa\(rq treated
+as a mangled type name would be demangled to \(lqsigned char\(rq.
+.Pp
+.It  -i
+.It  --no-verbose
+Do not include implementation details (if any) in the demangled output.
+.Pp
+.It  -s Va format
+.It  --format= Va format
+.Xr c++filt
+can decode various methods of mangling, used by different compilers. The argument
+to this option selects which method it uses:
+.Pp
+.Bl -tag -width Ds
+.It  auto
+Automatic selection based on executable (the default method)
+.It  GNU
+the one used by the GNU C++ compiler (g++)
+.It  lucid
+the one used by the Lucid compiler (lcc)
+.It  arm
+the one specified by the C++ Annotated Reference Manual
+.It  hp
+the one used by the HP compiler (aCC)
+.It  edg
+the one used by the EDG compiler
+.It  GNU-v3
+the one used by the GNU C++ compiler (g++) with the V3 ABI.
+.It  java
+the one used by the GNU Java compiler (gcj)
+.It  gnat
+the one used by the GNU Ada compiler (GNAT).
+.El
+.Pp
+.It  --help
+Print a summary of the options to
+.Xr c++filt
+and exit.
+.Pp
+.It  --version
+Print the version number of
+.Xr c++filt
+and exit.
+.El
+.Pp
+.Qo
+.Em Warning:
+.Xr c++filt
+is a new utility, and the details of its user interface are subject to change
+in future releases. In particular, a command-line option may be required in
+the future to decode a name passed as an argument on the command line; in
+other words,
+.Pp
+.Bd -literal -offset indent
+c++filt symbol
+.Ed
+.Pp
+may in a future release become
+.Pp
+.Bd -literal -offset indent
+c++filt option symbol
+.Ed
+.Qc
+.Pp
+.Sh  addr2line
+.Bd -literal -offset indent
+addr2line [-b bfdname|--target=bfdname]
+          [-C|--demangle[=style]]
+          [-e filename|--exe=filename]
+          [-f|--functions] [-s|--basename]
+          [-i|--inlines]
+          [-j|--section=name]
+          [-H|--help] [-V|--version]
+          [addr addr ...]
+.Ed
+.Pp
+.Xr addr2line
+translates addresses into file names and line numbers. Given an address in
+an executable or an offset in a section of a relocatable object, it uses the
+debugging information to figure out which file name and line number are associated
+with it.
+.Pp
+The executable or relocatable object to use is specified with the
+.Op -e
+option. The default is the file
+.Pa a.out .
+The section in the relocatable object to use is specified with the
+.Op -j
+option.
+.Pp
+.Xr addr2line
+has two modes of operation.
+.Pp
+In the first, hexadecimal addresses are specified on the command line, and
+.Xr addr2line
+displays the file name and line number for each address.
+.Pp
+In the second,
+.Xr addr2line
+reads hexadecimal addresses from standard input, and prints the file name
+and line number for each address on standard output. In this mode,
+.Xr addr2line
+may be used in a pipe to convert dynamically chosen addresses.
+.Pp
+The format of the output is
+.Li FILENAME:LINENO .
+The file name and line number for each address is printed on a separate line.
+If the
+.Xr -f
+option is used, then each
+.Li FILENAME:LINENO
+line is preceded by a
+.Li FUNCTIONNAME
+line which is the name of the function containing the address.
+.Pp
+If the file name or function name can not be determined,
+.Xr addr2line
+will print two question marks in their place. If the line number can not be
+determined,
+.Xr addr2line
+will print 0.
+.Pp
+The long and short forms of options, shown here as alternatives, are equivalent.
+.Pp
+.Bl -tag -width Ds
+.It  -b Va bfdname
+.It  --target= Va bfdname
+Specify that the object-code format for the object files is
+.Va bfdname .
+.Pp
+.It  -C
+.It  --demangle[= Va style]
+Decode (
+.Em demangle )
+low-level symbol names into user-level names. Besides removing any initial
+underscore prepended by the system, this makes C++ function names readable.
+Different compilers have different mangling styles. The optional demangling
+style argument can be used to choose an appropriate demangling style for your
+compiler.See Section
+.Dq c++filt ,
+for more information on demangling.
+.Pp
+.It  -e Va filename
+.It  --exe= Va filename
+Specify the name of the executable for which addresses should be translated.
+The default file is
+.Pa a.out .
+.Pp
+.It  -f
+.It  --functions
+Display function names as well as file and line number information.
+.Pp
+.It  -s
+.It  --basenames
+Display only the base of each file name.
+.Pp
+.It  -i
+.It  --inlines
+If the address belongs to a function that was inlined, the source information
+for all enclosing scopes back to the first non-inlined function will also
+be printed. For example, if
+.Li main
+inlines
+.Li callee1
+which inlines
+.Li callee2 ,
+and address is from
+.Li callee2 ,
+the source information for
+.Li callee1
+and
+.Li main
+will also be printed.
+.Pp
+.It  -j
+.It  --section
+Read offsets relative to the specified section instead of absolute addresses.
+.El
+.Pp
+.Sh  nlmconv
+.Xr nlmconv
+converts a relocatable object file into a NetWare Loadable Module.
+.Pp
+.Qo
+.Em Warning:
+.Xr nlmconv
+is not always built as part of the binary utilities, since it is only useful
+for NLM targets.
+.Qc
+.Pp
+.Bd -literal -offset indent
+nlmconv [-I bfdname|--input-target=bfdname]
+        [-O bfdname|--output-target=bfdname]
+        [-T headerfile|--header-file=headerfile]
+        [-d|--debug] [-l linker|--linker=linker]
+        [-h|--help] [-V|--version]
+        infile outfile
+.Ed
+.Pp
+.Xr nlmconv
+converts the relocatable
+.Li i386
+object file
+.Va infile
+into the NetWare Loadable Module
+.Va outfile ,
+optionally reading
+.Va headerfile
+for NLM header information. For instructions on writing the NLM command file
+language used in header files, see the
+.Li linkers
+section,
+.Li NLMLINK
+in particular, of the
+.Em NLM Development and Tools Overview ,
+which is part of the NLM Software Developer's Kit (\(lqNLM SDK\(rq), available from
+Novell, Inc.
+.Xr nlmconv
+uses the GNU Binary File Descriptor library to read
+.Va infile ;
+see BFD,,BFD,ld.info,Using LD, for more information.
+.Pp
+.Xr nlmconv
+can perform a link step. In other words, you can list more than one object
+file for input if you list them in the definitions file (rather than simply
+specifying one input file on the command line). In this case,
+.Xr nlmconv
+calls the linker for you.
+.Pp
+.Bl -tag -width Ds
+.It  -I Va bfdname
+.It  --input-target= Va bfdname
+Object format of the input file.
+.Xr nlmconv
+can usually determine the format of a given file (so no default is necessary).See Section
+.Dq Target Selection ,
+for more information.
+.Pp
+.It  -O Va bfdname
+.It  --output-target= Va bfdname
+Object format of the output file.
+.Xr nlmconv
+infers the output format based on the input format, e.g. for a
+.Li i386
+input file the output format is
+.Li nlm32-i386 .
+See Section.Dq Target Selection ,
+for more information.
+.Pp
+.It  -T Va headerfile
+.It  --header-file= Va headerfile
+Reads
+.Va headerfile
+for NLM header information. For instructions on writing the NLM command file
+language used in header files, see see the
+.Li linkers
+section, of the
+.Em NLM Development and Tools Overview ,
+which is part of the NLM Software Developer's Kit, available from Novell,
+Inc.
+.Pp
+.It  -d
+.It  --debug
+Displays (on standard error) the linker command line used by
+.Xr nlmconv .
+.Pp
+.It  -l Va linker
+.It  --linker= Va linker
+Use
+.Va linker
+for any linking.
+.Va linker
+can be an absolute or a relative pathname.
+.Pp
+.It  -h
+.It  --help
+Prints a usage summary.
+.Pp
+.It  -V
+.It  --version
+Prints the version number for
+.Xr nlmconv .
+.El
+.Pp
+.Sh  windmc
+.Xr windmc
+may be used to generator Windows message resources.
+.Pp
+.Qo
+.Em Warning:
+.Xr windmc
+is not always built as part of the binary utilities, since it is only useful
+for Windows targets.
+.Qc
+.Pp
+.Bd -literal -offset indent
+windmc [options] input-file
+.Ed
+.Pp
+.Xr windmc
+reads message definitions from an input file (.mc) and translate them into
+a set of output files. The output files may be of four kinds:
+.Pp
+.Bl -tag -width Ds
+.It  h
+A C header file containing the message definitions.
+.Pp
+.It  rc
+A resource file compilable by the
+.Xr windres
+tool.
+.Pp
+.It  bin
+One or more binary files containing the resource data for a specific message
+language.
+.Pp
+.It  dbg
+A C include file that maps message id's to their symbolic name.
+.El
+.Pp
+The exact description of these different formats is available in documentation
+from Microsoft.
+.Pp
+When
+.Xr windmc
+converts from the
+.Li mc
+format to the
+.Li bin
+format,
+.Li rc ,
+.Li h ,
+and optional
+.Li dbg
+it is acting like the Windows Message Compiler.
+.Pp
+.Bl -tag -width Ds
+.It  -a
+.It  --ascii_in
+Specifies that the input file specified is ANSI. This is the default behaviour.
+.Pp
+.It  -A
+.It  --ascii_out
+Specifies that messages in the output
+.Li bin
+files should be in ANSI format.
+.Pp
+.It  -b
+.It  --binprefix
+Specifies that
+.Li bin
+filenames should have to be prefixed by the basename of the source file.
+.Pp
+.It  -c
+.It  --customflag
+Sets the customer bit in all message id's.
+.Pp
+.It  -C Va codepage
+.It  --codepage_in Va codepage
+Sets the default codepage to be used to convert input file to UTF16. The default
+is ocdepage 1252.
+.Pp
+.It  -d
+.It  --decimal_values
+Outputs the constants in the header file in decimal. Default is using hexadecimal
+output.
+.Pp
+.It  -e Va ext
+.It  --extension Va ext
+The extension for the header file. The default is .h extension.
+.Pp
+.It  -F Va target
+.It  --target Va target
+Specify the BFD format to use for a bin file as output. This is a BFD target
+name; you can use the
+.Op --help
+option to see a list of supported targets. Normally
+.Xr windmc
+will use the default format, which is the first one listed by the
+.Op --help
+option. Target Selection.
+.Pp
+.It  -h Va path
+.It  --headerdir Va path
+The target directory of the generated header file. The default is the current
+directory.
+.Pp
+.It  -H
+.It  --help
+Displays a list of command line options and then exits.
+.Pp
+.It  -m Va characters
+.It  --maxlength Va characters
+Instructs
+.Xr windmc
+to generate a warning if the length of any message exceeds the number specified.
+.Pp
+.It  -n
+.It  --nullterminate
+Terminate message text in
+.Li bin
+files by zero. By default they are terminated by CR/LF.
+.Pp
+.It  -o
+.It  --hresult_use
+Not yet implemented. Instructs
+.Li windmc
+to generate an OLE2 header file, using HRESULT definitions. Status codes are
+used if the flag is not specified.
+.Pp
+.It  -O Va codepage
+.It  --codepage_out Va codepage
+Sets the default codepage to be used to output text files. The default is
+ocdepage 1252.
+.Pp
+.It  -r Va path
+.It  --rcdir Va path
+The target directory for the generated
+.Li rc
+script and the generated
+.Li bin
+files that the resource compiler script includes. The default is the current
+directory.
+.Pp
+.It  -u
+.It  --unicode_in
+Specifies that the input file is UTF16.
+.Pp
+.It  -U
+.It  --unicode_out
+Specifies that messages in the output
+.Li bin
+file should be in UTF16 format. This is the default behaviour.
+.Pp
+.It  -v
+.It  --verbose
+Enable verbose mode. This tells you what the preprocessor is if you didn't
+specify one.
+.Pp
+.It  -V
+.It  --version
+Prints the version number for
+.Xr windres .
+.Pp
+.It  -x Va path
+.It  --xdgb Va path
+The path of the
+.Li dbg
+C include file that maps message id's to the symbolic name. No such file is
+generated without specifying the switch.
+.El
+.Pp
+.Sh  windres
+.Xr windres
+may be used to manipulate Windows resources.
+.Pp
+.Qo
+.Em Warning:
+.Xr windres
+is not always built as part of the binary utilities, since it is only useful
+for Windows targets.
+.Qc
+.Pp
+.Bd -literal -offset indent
+windres [options] [input-file] [output-file]
+.Ed
+.Pp
+.Xr windres
+reads resources from an input file and copies them into an output file. Either
+file may be in one of three formats:
+.Pp
+.Bl -tag -width Ds
+.It  rc
+A text format read by the Resource Compiler.
+.Pp
+.It  res
+A binary format generated by the Resource Compiler.
+.Pp
+.It  coff
+A COFF object or executable.
+.El
+.Pp
+The exact description of these different formats is available in documentation
+from Microsoft.
+.Pp
+When
+.Xr windres
+converts from the
+.Li rc
+format to the
+.Li res
+format, it is acting like the Windows Resource Compiler. When
+.Xr windres
+converts from the
+.Li res
+format to the
+.Li coff
+format, it is acting like the Windows
+.Li CVTRES
+program.
+.Pp
+When
+.Xr windres
+generates an
+.Li rc
+file, the output is similar but not identical to the format expected for the
+input. When an input
+.Li rc
+file refers to an external filename, an output
+.Li rc
+file will instead include the file contents.
+.Pp
+If the input or output format is not specified,
+.Xr windres
+will guess based on the file name, or, for the input file, the file contents.
+A file with an extension of
+.Pa .rc
+will be treated as an
+.Li rc
+file, a file with an extension of
+.Pa .res
+will be treated as a
+.Li res
+file, and a file with an extension of
+.Pa .o
+or
+.Pa .exe
+will be treated as a
+.Li coff
+file.
+.Pp
+If no output file is specified,
+.Xr windres
+will print the resources in
+.Li rc
+format to standard output.
+.Pp
+The normal use is for you to write an
+.Li rc
+file, use
+.Xr windres
+to convert it to a COFF object file, and then link the COFF file into your
+application. This will make the resources described in the
+.Li rc
+file available to Windows.
+.Pp
+.Bl -tag -width Ds
+.It  -i Va filename
+.It  --input Va filename
+The name of the input file. If this option is not used, then
+.Xr windres
+will use the first non-option argument as the input file name. If there are
+no non-option arguments, then
+.Xr windres
+will read from standard input.
+.Xr windres
+can not read a COFF file from standard input.
+.Pp
+.It  -o Va filename
+.It  --output Va filename
+The name of the output file. If this option is not used, then
+.Xr windres
+will use the first non-option argument, after any used for the input file
+name, as the output file name. If there is no non-option argument, then
+.Xr windres
+will write to standard output.
+.Xr windres
+can not write a COFF file to standard output. Note, for compatibility with
+.Xr rc
+the option
+.Op -fo
+is also accepted, but its use is not recommended.
+.Pp
+.It  -J Va format
+.It  --input-format Va format
+The input format to read.
+.Va format
+may be
+.Li res ,
+.Li rc ,
+or
+.Li coff .
+If no input format is specified,
+.Xr windres
+will guess, as described above.
+.Pp
+.It  -O Va format
+.It  --output-format Va format
+The output format to generate.
+.Va format
+may be
+.Li res ,
+.Li rc ,
+or
+.Li coff .
+If no output format is specified,
+.Xr windres
+will guess, as described above.
+.Pp
+.It  -F Va target
+.It  --target Va target
+Specify the BFD format to use for a COFF file as input or output. This is
+a BFD target name; you can use the
+.Op --help
+option to see a list of supported targets. Normally
+.Xr windres
+will use the default format, which is the first one listed by the
+.Op --help
+option. Target Selection.
+.Pp
+.It  --preprocessor Va program
+When
+.Xr windres
+reads an
+.Li rc
+file, it runs it through the C preprocessor first. This option may be used
+to specify the preprocessor to use, including any leading arguments. The default
+preprocessor argument is
+.Li gcc -E -xc-header -DRC_INVOKED .
+.Pp
+.It  -I Va directory
+.It  --include-dir Va directory
+Specify an include directory to use when reading an
+.Li rc
+file.
+.Xr windres
+will pass this to the preprocessor as an
+.Op -I
+option.
+.Xr windres
+will also search this directory when looking for files named in the
+.Li rc
+file. If the argument passed to this command matches any of the supported
+.Va formats
+(as described in the
+.Op -J
+option), it will issue a deprecation warning, and behave just like the
+.Op -J
+option. New programs should not use this behaviour. If a directory happens
+to match a
+.Va format ,
+simple prefix it with
+.Li ./
+to disable the backward compatibility.
+.Pp
+.It  -D Va target
+.It  --define Va sym[= Va val]
+Specify a
+.Op -D
+option to pass to the preprocessor when reading an
+.Li rc
+file.
+.Pp
+.It  -U Va target
+.It  --undefine Va sym
+Specify a
+.Op -U
+option to pass to the preprocessor when reading an
+.Li rc
+file.
+.Pp
+.It  -r
+Ignored for compatibility with rc.
+.Pp
+.It  -v
+Enable verbose mode. This tells you what the preprocessor is if you didn't
+specify one.
+.Pp
+.It  -c Va val
+.It  --codepage Va val
+Specify the default codepage to use when reading an
+.Li rc
+file.
+.Va val
+should be a hexadecimal prefixed by
+.Li 0x
+or decimal codepage code. The valid range is from zero up to 0xffff, but the
+validity of the codepage is host and configuration dependent.
+.Pp
+.It  -l Va val
+.It  --language Va val
+Specify the default language to use when reading an
+.Li rc
+file.
+.Va val
+should be a hexadecimal language code. The low eight bits are the language,
+and the high eight bits are the sublanguage.
+.Pp
+.It  --use-temp-file
+Use a temporary file to instead of using popen to read the output of the preprocessor.
+Use this option if the popen implementation is buggy on the host (eg., certain
+non-English language versions of Windows 95 and Windows 98 are known to have
+buggy popen where the output will instead go the console).
+.Pp
+.It  --no-use-temp-file
+Use popen, not a temporary file, to read the output of the preprocessor. This
+is the default behaviour.
+.Pp
+.It  -h
+.It  --help
+Prints a usage summary.
+.Pp
+.It  -V
+.It  --version
+Prints the version number for
+.Xr windres .
+.Pp
+.It  --yydebug
+If
+.Xr windres
+is compiled with
+.Li YYDEBUG
+defined as
+.Li 1 ,
+this will turn on parser debugging.
+.El
+.Pp
+.Sh  dlltool
+.Xr dlltool
+is used to create the files needed to create dynamic link libraries (DLLs)
+on systems which understand PE format image files such as Windows. A DLL contains
+an export table which contains information that the runtime loader needs to
+resolve references from a referencing program.
+.Pp
+The export table is generated by this program by reading in a
+.Pa .def
+file or scanning the
+.Pa .a
+and
+.Pa .o
+files which will be in the DLL. A
+.Pa .o
+file can contain information in special
+.Li .drectve
+sections with export information.
+.Pp
+.Qo
+.Em Note:
+.Xr dlltool
+is not always built as part of the binary utilities, since it is only useful
+for those targets which support DLLs.
+.Qc
+.Pp
+.Bd -literal -offset indent
+dlltool [-d|--input-def def-file-name]
+        [-b|--base-file base-file-name]
+        [-e|--output-exp exports-file-name]
+        [-z|--output-def def-file-name]
+        [-l|--output-lib library-file-name]
+        [--export-all-symbols] [--no-export-all-symbols]
+        [--exclude-symbols list]
+        [--no-default-excludes]
+        [-S|--as path-to-assembler] [-f|--as-flags options]
+        [-D|--dllname name] [-m|--machine machine]
+        [-a|--add-indirect]
+        [-U|--add-underscore] [--add-stdcall-underscore]
+        [-k|--kill-at] [-A|--add-stdcall-alias]
+        [-p|--ext-prefix-alias prefix]
+        [-x|--no-idata4] [-c|--no-idata5] [-i|--interwork]
+        [-n|--nodelete] [-t|--temp-prefix prefix]
+        [-v|--verbose]
+        [-h|--help] [-V|--version]
+        [object-file ...]
+.Ed
+.Pp
+.Xr dlltool
+reads its inputs, which can come from the
+.Op -d
+and
+.Op -b
+options as well as object files specified on the command line. It then processes
+these inputs and if the
+.Op -e
+option has been specified it creates a exports file. If the
+.Op -l
+option has been specified it creates a library file and if the
+.Op -z
+option has been specified it creates a def file. Any or all of the
+.Op -e ,
+.Op -l
+and
+.Op -z
+options can be present in one invocation of dlltool.
+.Pp
+When creating a DLL, along with the source for the DLL, it is necessary to
+have three other files.
+.Xr dlltool
+can help with the creation of these files.
+.Pp
+The first file is a
+.Pa .def
+file which specifies which functions are exported from the DLL, which functions
+the DLL imports, and so on. This is a text file and can be created by hand,
+or
+.Xr dlltool
+can be used to create it using the
+.Op -z
+option. In this case
+.Xr dlltool
+will scan the object files specified on its command line looking for those
+functions which have been specially marked as being exported and put entries
+for them in the
+.Pa .def
+file it creates.
+.Pp
+In order to mark a function as being exported from a DLL, it needs to have
+an
+.Op -export:<name_of_function>
+entry in the
+.Li .drectve
+section of the object file. This can be done in C by using the asm() operator:
+.Pp
+.Bd -literal -offset indent
+  asm (".section .drectve");
+  asm (".ascii \e"-export:my_func\e"");
+
+  int my_func (void) { ... }
+.Ed
+.Pp
+The second file needed for DLL creation is an exports file. This file is linked
+with the object files that make up the body of the DLL and it handles the
+interface between the DLL and the outside world. This is a binary file and
+it can be created by giving the
+.Op -e
+option to
+.Xr dlltool
+when it is creating or reading in a
+.Pa .def
+file.
+.Pp
+The third file needed for DLL creation is the library file that programs will
+link with in order to access the functions in the DLL. This file can be created
+by giving the
+.Op -l
+option to dlltool when it is creating or reading in a
+.Pa .def
+file.
+.Pp
+.Xr dlltool
+builds the library file by hand, but it builds the exports file by creating
+temporary files containing assembler statements and then assembling these.
+The
+.Op -S
+command line option can be used to specify the path to the assembler that
+dlltool will use, and the
+.Op -f
+option can be used to pass specific flags to that assembler. The
+.Op -n
+can be used to prevent dlltool from deleting these temporary assembler files
+when it is done, and if
+.Op -n
+is specified twice then this will prevent dlltool from deleting the temporary
+object files it used to build the library.
+.Pp
+Here is an example of creating a DLL from a source file
+.Li dll.c
+and also creating a program (from an object file called
+.Li program.o )
+that uses that DLL:
+.Pp
+.Bd -literal -offset indent
+  gcc -c dll.c
+  dlltool -e exports.o -l dll.lib dll.o
+  gcc dll.o exports.o -o dll.dll
+  gcc program.o dll.lib -o program
+.Ed
+.Pp
+The command line options have the following meanings:
+.Pp
+.Bl -tag -width Ds
+.It  -d Va filename
+.It  --input-def Va filename
+Specifies the name of a
+.Pa .def
+file to be read in and processed.
+.Pp
+.It  -b Va filename
+.It  --base-file Va filename
+Specifies the name of a base file to be read in and processed. The contents
+of this file will be added to the relocation section in the exports file generated
+by dlltool.
+.Pp
+.It  -e Va filename
+.It  --output-exp Va filename
+Specifies the name of the export file to be created by dlltool.
+.Pp
+.It  -z Va filename
+.It  --output-def Va filename
+Specifies the name of the
+.Pa .def
+file to be created by dlltool.
+.Pp
+.It  -l Va filename
+.It  --output-lib Va filename
+Specifies the name of the library file to be created by dlltool.
+.Pp
+.It  --export-all-symbols
+Treat all global and weak defined symbols found in the input object files
+as symbols to be exported. There is a small list of symbols which are not
+exported by default; see the
+.Op --no-default-excludes
+option. You may add to the list of symbols to not export by using the
+.Op --exclude-symbols
+option.
+.Pp
+.It  --no-export-all-symbols
+Only export symbols explicitly listed in an input
+.Pa .def
+file or in
+.Li .drectve
+sections in the input object files. This is the default behaviour. The
+.Li .drectve
+sections are created by
+.Li dllexport
+attributes in the source code.
+.Pp
+.It  --exclude-symbols Va list
+Do not export the symbols in
+.Va list .
+This is a list of symbol names separated by comma or colon characters. The
+symbol names should not contain a leading underscore. This is only meaningful
+when
+.Op --export-all-symbols
+is used.
+.Pp
+.It  --no-default-excludes
+When
+.Op --export-all-symbols
+is used, it will by default avoid exporting certain special symbols. The current
+list of symbols to avoid exporting is
+.Li DllMain@12 ,
+.Li DllEntryPoint@0 ,
+.Li impure_ptr .
+You may use the
+.Op --no-default-excludes
+option to go ahead and export these special symbols. This is only meaningful
+when
+.Op --export-all-symbols
+is used.
+.Pp
+.It  -S Va path
+.It  --as Va path
+Specifies the path, including the filename, of the assembler to be used to
+create the exports file.
+.Pp
+.It  -f Va options
+.It  --as-flags Va options
+Specifies any specific command line options to be passed to the assembler
+when building the exports file. This option will work even if the
+.Op -S
+option is not used. This option only takes one argument, and if it occurs
+more than once on the command line, then later occurrences will override earlier
+occurrences. So if it is necessary to pass multiple options to the assembler
+they should be enclosed in double quotes.
+.Pp
+.It  -D Va name
+.It  --dll-name Va name
+Specifies the name to be stored in the
+.Pa .def
+file as the name of the DLL when the
+.Op -e
+option is used. If this option is not present, then the filename given to
+the
+.Op -e
+option will be used as the name of the DLL.
+.Pp
+.It  -m Va machine
+.It  -machine Va machine
+Specifies the type of machine for which the library file should be built.
+.Xr dlltool
+has a built in default type, depending upon how it was created, but this option
+can be used to override that. This is normally only useful when creating DLLs
+for an ARM processor, when the contents of the DLL are actually encode using
+Thumb instructions.
+.Pp
+.It  -a
+.It  --add-indirect
+Specifies that when
+.Xr dlltool
+is creating the exports file it should add a section which allows the exported
+functions to be referenced without using the import library. Whatever the
+hell that means!
+.Pp
+.It  -U
+.It  --add-underscore
+Specifies that when
+.Xr dlltool
+is creating the exports file it should prepend an underscore to the names
+of
+.Em all
+exported symbols.
+.Pp
+.It  --add-stdcall-underscore
+Specifies that when
+.Xr dlltool
+is creating the exports file it should prepend an underscore to the names
+of exported
+.Em stdcall
+functions. Variable names and non-stdcall function names are not modified.
+This option is useful when creating GNU-compatible import libs for third party
+DLLs that were built with MS-Windows tools.
+.Pp
+.It  -k
+.It  --kill-at
+Specifies that when
+.Xr dlltool
+is creating the exports file it should not append the string
+.Li @ <number> .
+These numbers are called ordinal numbers and they represent another way of
+accessing the function in a DLL, other than by name.
+.Pp
+.It  -A
+.It  --add-stdcall-alias
+Specifies that when
+.Xr dlltool
+is creating the exports file it should add aliases for stdcall symbols without
+.Li @ <number>
+in addition to the symbols with
+.Li @ <number> .
+.Pp
+.It  -p
+.It  --ext-prefix-alias Va prefix
+Causes
+.Xr dlltool
+to create external aliases for all DLL imports with the specified prefix.
+The aliases are created for both external and import symbols with no leading
+underscore.
+.Pp
+.It  -x
+.It  --no-idata4
+Specifies that when
+.Xr dlltool
+is creating the exports and library files it should omit the
+.Li .idata4
+section. This is for compatibility with certain operating systems.
+.Pp
+.It  -c
+.It  --no-idata5
+Specifies that when
+.Xr dlltool
+is creating the exports and library files it should omit the
+.Li .idata5
+section. This is for compatibility with certain operating systems.
+.Pp
+.It  -i
+.It  --interwork
+Specifies that
+.Xr dlltool
+should mark the objects in the library file and exports file that it produces
+as supporting interworking between ARM and Thumb code.
+.Pp
+.It  -n
+.It  --nodelete
+Makes
+.Xr dlltool
+preserve the temporary assembler files it used to create the exports file.
+If this option is repeated then dlltool will also preserve the temporary object
+files it uses to create the library file.
+.Pp
+.It  -t Va prefix
+.It  --temp-prefix Va prefix
+Makes
+.Xr dlltool
+use
+.Va prefix
+when constructing the names of temporary assembler and object files. By default,
+the temp file prefix is generated from the pid.
+.Pp
+.It  -v
+.It  --verbose
+Make dlltool describe what it is doing.
+.Pp
+.It  -h
+.It  --help
+Displays a list of command line options and then exits.
+.Pp
+.It  -V
+.It  --version
+Displays dlltool's version number and then exits.
+.Pp
+.El
+.Ss  The format of the Xr dlltool Pa .def file
+A
+.Pa .def
+file contains any number of the following commands:
+.Pp
+.Bl -tag -width Ds
+.It  Li NAME Va name Li [ , Va base Li ]
+The result is going to be named
+.Va name
+.Li .exe .
+.Pp
+.It  Li LIBRARY Va name Li [ , Va base Li ]
+The result is going to be named
+.Va name
+.Li .dll .
+.Pp
+.It  Li EXPORTS ( ( ( Va name1 Li [ = Va name2 Li ] ) | ( Va name1 Li = Va module-name Li . Va external-name Li ) )
+.It  Li [ Va integer Li ] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) *
+Declares
+.Va name1
+as an exported symbol from the DLL, with optional ordinal number
+.Va integer ,
+or declares
+.Va name1
+as an alias (forward) of the function
+.Va external-name
+in the DLL
+.Va module-name .
+.Pp
+.It  Li IMPORTS ( ( Va internal-name Li = Va module-name Li . Va integer Li ) | [ Va internal-name Li = ] Va module-name Li . Va external-name Li ) ) *
+Declares that
+.Va external-name
+or the exported function whose ordinal number is
+.Va integer
+is to be imported from the file
+.Va module-name .
+If
+.Va internal-name
+is specified then this is the name that the imported function will be referred
+to in the body of the DLL.
+.Pp
+.It  Li DESCRIPTION Va string
+Puts
+.Va string
+into the output
+.Pa .exp
+file in the
+.Li .rdata
+section.
+.Pp
+.It  Li STACKSIZE Va number-reserve Li [, Va number-commit Li ]
+.It  Li HEAPSIZE Va number-reserve Li [, Va number-commit Li ]
+Generates
+.Li --stack
+or
+.Li --heap
+.Va number-reserve
+,
+.Va number-commit
+in the output
+.Li .drectve
+section. The linker will see this and act upon it.
+.Pp
+.It  Li CODE Va attr Li +
+.It  Li DATA Va attr Li +
+.It  Li SECTIONS ( Va section-name Va attr Li  + ) *
+Generates
+.Li --attr
+.Va section-name
+.Va attr
+in the output
+.Li .drectve
+section, where
+.Va attr
+is one of
+.Li READ ,
+.Li WRITE ,
+.Li EXECUTE
+or
+.Li SHARED .
+The linker will see this and act upon it.
+.Pp
+.El
+.Sh  readelf
+.Bd -literal -offset indent
+readelf [-a|--all]
+        [-h|--file-header]
+        [-l|--program-headers|--segments]
+        [-S|--section-headers|--sections]
+        [-g|--section-groups]
+        [-t|--section-details]
+        [-e|--headers]
+        [-s|--syms|--symbols]
+        [-n|--notes]
+        [-r|--relocs]
+        [-u|--unwind]
+        [-d|--dynamic]
+        [-V|--version-info]
+        [-A|--arch-specific]
+        [-D|--use-dynamic]
+        [-x <number or name>|--hex-dump=<number or name>]
+        [-w[liaprmfFsoR]|
+         --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]]
+        [-I|-histogram]
+        [-v|--version]
+        [-W|--wide]
+        [-H|--help]
+        elffile...
+.Ed
+.Pp
+.Xr readelf
+displays information about one or more ELF format object files. The options
+control what particular information to display.
+.Pp
+.Va elffile
+\&...are the object files to be examined. 32-bit and 64-bit ELF files are supported,
+as are archives containing ELF files.
+.Pp
+This program performs a similar function to
+.Xr objdump
+but it goes into more detail and it exists independently of the bfd library,
+so if there is a bug in bfd then readelf will not be affected.
+.Pp
+The long and short forms of options, shown here as alternatives, are equivalent.
+At least one option besides
+.Li -v
+or
+.Li -H
+must be given.
+.Pp
+.Bl -tag -width Ds
+.It  -a
+.It  --all
+Equivalent to specifying
+.Op --file-header ,
+.Op --program-headers ,
+.Op --sections ,
+.Op --symbols ,
+.Op --relocs ,
+.Op --dynamic ,
+.Op --notes
+and
+.Op --version-info .
+.Pp
+.It  -h
+.It  --file-header
+Displays the information contained in the ELF header at the start of the file.
+.Pp
+.It  -l
+.It  --program-headers
+.It  --segments
+Displays the information contained in the file's segment headers, if it has
+any.
+.Pp
+.It  -S
+.It  --sections
+.It  --section-headers
+Displays the information contained in the file's section headers, if it has
+any.
+.Pp
+.It  -g
+.It  --section-groups
+Displays the information contained in the file's section groups, if it has
+any.
+.Pp
+.It  -t
+.It  --section-details
+Displays the detailed section information. Implies
+.Op -S .
+.Pp
+.It  -s
+.It  --symbols
+.It  --syms
+Displays the entries in symbol table section of the file, if it has one.
+.Pp
+.It  -e
+.It  --headers
+Display all the headers in the file. Equivalent to
+.Op -h -l -S .
+.Pp
+.It  -n
+.It  --notes
+Displays the contents of the NOTE segments and/or sections, if any.
+.Pp
+.It  -r
+.It  --relocs
+Displays the contents of the file's relocation section, if it has one.
+.Pp
+.It  -u
+.It  --unwind
+Displays the contents of the file's unwind section, if it has one. Only the
+unwind sections for IA64 ELF files are currently supported.
+.Pp
+.It  -d
+.It  --dynamic
+Displays the contents of the file's dynamic section, if it has one.
+.Pp
+.It  -V
+.It  --version-info
+Displays the contents of the version sections in the file, it they exist.
+.Pp
+.It  -A
+.It  --arch-specific
+Displays architecture-specific information in the file, if there is any.
+.Pp
+.It  -D
+.It  --use-dynamic
+When displaying symbols, this option makes
+.Xr readelf
+use the symbol table in the file's dynamic section, rather than the one in
+the symbols section.
+.Pp
+.It  -x <number or name>
+.It  --hex-dump=<number or name>
+Displays the contents of the indicated section as a hexadecimal dump. A number
+identifies a particular section by index in the section table; any other string
+identifies all sections with that name in the object file.
+.Pp
+.It  -w[liaprmfFsoR]
+.It  --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]
+Displays the contents of the debug sections in the file, if any are present.
+If one of the optional letters or words follows the switch then only data
+found in those specific sections will be dumped.
+.Pp
+.It  -I
+.It  --histogram
+Display a histogram of bucket list lengths when displaying the contents of
+the symbol tables.
+.Pp
+.It  -v
+.It  --version
+Display the version number of readelf.
+.Pp
+.It  -W
+.It  --wide
+Don't break output lines to fit into 80 columns. By default
+.Xr readelf
+breaks section header and segment listing lines for 64-bit ELF files, so that
+they fit into 80 columns. This option causes
+.Xr readelf
+to print each section header resp. each segment one a single line, which is
+far more readable on terminals wider than 80 columns.
+.Pp
+.It  -H
+.It  --help
+Display the command line options understood by
+.Xr readelf .
+.Pp
+.El
+.Sh  Common Options
+The following command-line options are supported by all of the programs described
+in this manual.
+.Pp
+.Bl -tag -width Ds
+.It  @ Va file
+Read command-line options from
+.Va file .
+The options read are inserted in place of the original @
+.Va file
+option. If
+.Va file
+does not exist, or cannot be read, then the option will be treated literally,
+and not removed.
+.Pp
+Options in
+.Va file
+are separated by whitespace. A whitespace character may be included in an
+option by surrounding the entire option in either single or double quotes.
+Any character (including a backslash) may be included by prefixing the character
+to be included with a backslash. The
+.Va file
+may itself contain additional @
+.Va file
+options; any such options will be processed recursively.
+.Pp
+.It  --help
+Display the command-line options supported by the program.
+.Pp
+.It  --version
+Display the version number of the program.
+.Pp
+.El
+.Sh  Selecting the Target System
+You can specify two aspects of the target system to the GNU binary file utilities,
+each in several ways:
+.Pp
+.Bl -bullet
+.It
+the target
+.Pp
+.It
+the architecture
+.El
+.Pp
+In the following summaries, the lists of ways to specify values are in order
+of decreasing precedence. The ways listed first override those listed later.
+.Pp
+The commands to list valid values only list the values for which the programs
+you are running were configured. If they were configured with
+.Op --enable-targets=all ,
+the commands list most of the available values, but a few are left out; not
+all targets can be configured in at once because some of them can only be
+configured
+.Em native
+(on hosts with the same type as the target system).
+.Pp
+.Ss  Target Selection
+A
+.Em target
+is an object file format. A given target may be supported for multiple architectures
+(see Section
+.Dq Architecture Selection ) .
+A target selection may also have variations for different operating systems
+or architectures.
+.Pp
+The command to list valid target values is
+.Li objdump -i
+(the first column of output contains the relevant information).
+.Pp
+Some sample values are:
+.Li a.out-hp300bsd ,
+.Li ecoff-littlemips ,
+.Li a.out-sunos-big .
+.Pp
+You can also specify a target using a configuration triplet. This is the same
+sort of name that is passed to
+.Pa configure
+to specify a target. When you use a configuration triplet as an argument,
+it must be fully canonicalized. You can see the canonical version of a triplet
+by running the shell script
+.Pa config.sub
+which is included with the sources.
+.Pp
+Some sample configuration triplets are:
+.Li m68k-hp-bsd ,
+.Li mips-dec-ultrix ,
+.Li sparc-sun-sunos .
+.Pp
+.Em  Xr objdump Target
+.Pp
+Ways to specify:
+.Pp
+.Bl -enum
+.It
+command line option:
+.Op -b
+or
+.Op --target
+.Pp
+.It
+environment variable
+.Li GNUTARGET
+.Pp
+.It
+deduced from the input file
+.El
+.Pp
+.Em  Xr objcopy and Xr strip Input Target
+.Pp
+Ways to specify:
+.Pp
+.Bl -enum
+.It
+command line options:
+.Op -I
+or
+.Op --input-target ,
+or
+.Op -F
+or
+.Op --target
+.Pp
+.It
+environment variable
+.Li GNUTARGET
+.Pp
+.It
+deduced from the input file
+.El
+.Pp
+.Em  Xr objcopy and Xr strip Output Target
+.Pp
+Ways to specify:
+.Pp
+.Bl -enum
+.It
+command line options:
+.Op -O
+or
+.Op --output-target ,
+or
+.Op -F
+or
+.Op --target
+.Pp
+.It
+the input target (see \(lq
+.Xr objcopy
+and
+.Xr strip
+Input Target\(rq above)
+.Pp
+.It
+environment variable
+.Li GNUTARGET
+.Pp
+.It
+deduced from the input file
+.El
+.Pp
+.Em  Xr nm, Xr size, and Xr strings Target
+.Pp
+Ways to specify:
+.Pp
+.Bl -enum
+.It
+command line option:
+.Op --target
+.Pp
+.It
+environment variable
+.Li GNUTARGET
+.Pp
+.It
+deduced from the input file
+.El
+.Pp
+.Ss  Architecture Selection
+An
+.Em architecture
+is a type of cpu on which an object file is to run. Its name may contain a
+colon, separating the name of the processor family from the name of the particular
+cpu.
+.Pp
+The command to list valid architecture values is
+.Li objdump -i
+(the second column contains the relevant information).
+.Pp
+Sample values:
+.Li m68k:68020 ,
+.Li mips:3000 ,
+.Li sparc .
+.Pp
+.Em  Xr objdump Architecture
+.Pp
+Ways to specify:
+.Pp
+.Bl -enum
+.It
+command line option:
+.Op -m
+or
+.Op --architecture
+.Pp
+.It
+deduced from the input file
+.El
+.Pp
+.Em  Xr objcopy, Xr nm, Xr size, Xr strings Architecture
+.Pp
+Ways to specify:
+.Pp
+.Bl -enum
+.It
+deduced from the input file
+.El
+.Pp
+.Sh  Reporting Bugs
+Your bug reports play an essential role in making the binary utilities reliable.
+.Pp
+Reporting a bug may help you by bringing a solution to your problem, or it
+may not. But in any case the principal function of a bug report is to help
+the entire community by making the next version of the binary utilities work
+better. Bug reports are your contribution to their maintenance.
+.Pp
+In order for a bug report to serve its purpose, you must include the information
+that enables us to fix the bug.
+.Pp
+.Ss  Have You Found a Bug?
+If you are not sure whether you have found a bug, here are some guidelines:
+.Pp
+.Bl -bullet
+.It
+If a binary utility gets a fatal signal, for any input whatever, that is a
+bug. Reliable utilities never crash.
+.Pp
+.It
+If a binary utility produces an error message for valid input, that is a bug.
+.Pp
+.It
+If you are an experienced user of binary utilities, your suggestions for improvement
+are welcome in any case.
+.El
+.Pp
+.Ss  How to Report Bugs
+A number of companies and individuals offer support for GNU products. If you
+obtained the binary utilities from a support organization, we recommend you
+contact that organization first.
+.Pp
+You can find contact information for many support companies and individuals
+in the file
+.Pa etc/SERVICE
+in the GNU Emacs distribution.
+.Pp
+The fundamental principle of reporting bugs usefully is this:
+.Sy report all the facts .
+If you are not sure whether to state a fact or leave it out, state it!
+.Pp
+Often people omit facts because they think they know what causes the problem
+and assume that some details do not matter. Thus, you might assume that the
+name of a file you use in an example does not matter. Well, probably it does
+not, but one cannot be sure. Perhaps the bug is a stray memory reference which
+happens to fetch from the location where that pathname is stored in memory;
+perhaps, if the pathname were different, the contents of that location would
+fool the utility into doing the right thing despite the bug. Play it safe
+and give a specific, complete example. That is the easiest thing for you to
+do, and the most helpful.
+.Pp
+Keep in mind that the purpose of a bug report is to enable us to fix the bug
+if it is new to us. Therefore, always write your bug reports on the assumption
+that the bug has not been reported previously.
+.Pp
+Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq
+This cannot help us fix a bug, so it is basically useless. We respond by asking
+for enough details to enable us to investigate. You might as well expedite
+matters by sending them to begin with.
+.Pp
+To enable us to fix the bug, you should include all these things:
+.Pp
+.Bl -bullet
+.It
+The version of the utility. Each utility announces it if you start it with
+the
+.Op --version
+argument.
+.Pp
+Without this, we will not know whether there is any point in looking for the
+bug in the current version of the binary utilities.
+.Pp
+.It
+Any patches you may have applied to the source, including any patches made
+to the
+.Li BFD
+library.
+.Pp
+.It
+The type of machine you are using, and the operating system name and version
+number.
+.Pp
+.It
+What compiler (and its version) was used to compile the utilities---e.g. \(lq
+.Li gcc-2.7
+\(rq\&.
+.Pp
+.It
+The command arguments you gave the utility to observe the bug. To guarantee
+you will not omit something important, list them all. A copy of the Makefile
+(or the output from make) is sufficient.
+.Pp
+If we were to try to guess the arguments, we would probably guess wrong and
+then we might not encounter the bug.
+.Pp
+.It
+A complete input file, or set of input files, that will reproduce the bug.
+If the utility is reading an object file or files, then it is generally most
+helpful to send the actual object files.
+.Pp
+If the source files were produced exclusively using GNU programs (e.g.,
+.Xr gcc ,
+.Xr gas ,
+and/or the GNU
+.Xr ld ) ,
+then it may be OK to send the source files rather than the object files. In
+this case, be sure to say exactly what version of
+.Xr gcc ,
+or whatever, was used to produce the object files. Also say how
+.Xr gcc ,
+or whatever, was configured.
+.Pp
+.It
+A description of what behavior you observe that you believe is incorrect.
+For example, \(lqIt gets a fatal signal.\(rq
+.Pp
+Of course, if the bug is that the utility gets a fatal signal, then we will
+certainly notice it. But if the bug is incorrect output, we might not notice
+unless it is glaringly wrong. You might as well not give us a chance to make
+a mistake.
+.Pp
+Even if the problem you experience is a fatal signal, you should still say
+so explicitly. Suppose something strange is going on, such as your copy of
+the utility is out of sync, or you have encountered a bug in the C library
+on your system. (This has happened!) Your copy might crash and ours would
+not. If you told us to expect a crash, then when ours fails to crash, we would
+know that the bug was not happening for us. If you had not told us to expect
+a crash, then we would not be able to draw any conclusion from our observations.
+.Pp
+.It
+If you wish to suggest changes to the source, send us context diffs, as generated
+by
+.Xr diff
+with the
+.Op -u ,
+.Op -c ,
+or
+.Op -p
+option. Always send diffs from the old file to the new file. If you wish to
+discuss something in the
+.Xr ld
+source, refer to it by context, not by line number.
+.Pp
+The line numbers in our development sources will not match those in your sources.
+Your line numbers would convey no useful information to us.
+.El
+.Pp
+Here are some things that are not necessary:
+.Pp
+.Bl -bullet
+.It
+A description of the envelope of the bug.
+.Pp
+Often people who encounter a bug spend a lot of time investigating which changes
+to the input file will make the bug go away and which changes will not affect
+it.
+.Pp
+This is often time consuming and not very useful, because the way we will
+find the bug is by running a single example under the debugger with breakpoints,
+not by pure deduction from a series of examples. We recommend that you save
+your time for something else.
+.Pp
+Of course, if you can find a simpler example to report
+.Em instead
+of the original one, that is a convenience for us. Errors in the output will
+be easier to spot, running under the debugger will take less time, and so
+on.
+.Pp
+However, simplification is not vital; if you do not want to do this, report
+the bug anyway and send us the entire test case you used.
+.Pp
+.It
+A patch for the bug.
+.Pp
+A patch for the bug does help us if it is a good one. But do not omit the
+necessary information, such as the test case, on the assumption that a patch
+is all we need. We might see problems with your patch and decide to fix the
+problem another way, or we might not understand it at all.
+.Pp
+Sometimes with programs as complicated as the binary utilities it is very
+hard to construct an example that will make the program follow a certain path
+through the code. If you do not send us the example, we will not be able to
+construct one, so we will not be able to verify that the bug is fixed.
+.Pp
+And if we cannot understand what bug you are trying to fix, or why your patch
+should be an improvement, we will not install it. A test case will help us
+to understand.
+.Pp
+.It
+A guess about what the bug is or what it depends on.
+.Pp
+Such guesses are usually wrong. Even we cannot guess right about such things
+without first using the debugger to find the facts.
+.El
+.Pp
+.Sh  GNU Free Documentation License
+.Bd -filled -offset indent
+Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street,
+Fifth Floor, Boston, MA 02110-1301 USA
+.Pp
+Everyone is permitted to copy and distribute verbatim copies of this license
+document, but changing it is not allowed.
+.Ed
+.Pp
+.Bl -enum
+.It
+PREAMBLE
+.Pp
+The purpose of this License is to make a manual, textbook, or other written
+document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom
+to copy and redistribute it, with or without modifying it, either commercially
+or noncommercially. Secondarily, this License preserves for the author and
+publisher a way to get credit for their work, while not being considered responsible
+for modifications made by others.
+.Pp
+This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the
+document must themselves be free in the same sense. It complements the GNU
+General Public License, which is a copyleft license designed for free software.
+.Pp
+We have designed this License in order to use it for manuals for free software,
+because free software needs free documentation: a free program should come
+with manuals providing the same freedoms that the software does. But this
+License is not limited to software manuals; it can be used for any textual
+work, regardless of subject matter or whether it is published as a printed
+book. We recommend this License principally for works whose purpose is instruction
+or reference.
+.Pp
+.It
+APPLICABILITY AND DEFINITIONS
+.Pp
+This License applies to any manual or other work that contains a notice placed
+by the copyright holder saying it can be distributed under the terms of this
+License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member
+of the public is a licensee, and is addressed as \(lqyou.\(rq
+.Pp
+A \(lqModified Version\(rq of the Document means any work containing the Document
+or a portion of it, either copied verbatim, or with modifications and/or translated
+into another language.
+.Pp
+A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document
+that deals exclusively with the relationship of the publishers or authors
+of the Document to the Document's overall subject (or to related matters)
+and contains nothing that could fall directly within that overall subject.
+(For example, if the Document is in part a textbook of mathematics, a Secondary
+Section may not explain any mathematics.) The relationship could be a matter
+of historical connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding them.
+.Pp
+The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated,
+as being those of Invariant Sections, in the notice that says that the Document
+is released under this License.
+.Pp
+The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover
+Texts or Back-Cover Texts, in the notice that says that the Document is released
+under this License.
+.Pp
+A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented
+in a format whose specification is available to the general public, whose
+contents can be viewed and edited directly and straightforwardly with generic
+text editors or (for images composed of pixels) generic paint programs or
+(for drawings) some widely available drawing editor, and that is suitable
+for input to text formatters or for automatic translation to a variety of
+formats suitable for input to text formatters. A copy made in an otherwise
+Transparent file format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is not
+\(lqTransparent\(rq is called \(lqOpaque.\(rq
+.Pp
+Examples of suitable formats for Transparent copies include plain ASCII without
+markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly
+available DTD, and standard-conforming simple HTML designed for human modification.
+Opaque formats include PostScript, PDF, proprietary formats that can be read
+and edited only by proprietary word processors, SGML or XML for which the
+DTD and/or processing tools are not generally available, and the machine-generated
+HTML produced by some word processors for output purposes only.
+.Pp
+The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such
+following pages as are needed to hold, legibly, the material this License
+requires to appear in the title page. For works in formats which do not have
+any title page as such, \(lqTitle Page\(rq means the text near the most prominent
+appearance of the work's title, preceding the beginning of the body of the
+text.
+.Pp
+.It
+VERBATIM COPYING
+.Pp
+You may copy and distribute the Document in any medium, either commercially
+or noncommercially, provided that this License, the copyright notices, and
+the license notice saying this License applies to the Document are reproduced
+in all copies, and that you add no other conditions whatsoever to those of
+this License. You may not use technical measures to obstruct or control the
+reading or further copying of the copies you make or distribute. However,
+you may accept compensation in exchange for copies. If you distribute a large
+enough number of copies you must also follow the conditions in section 3.
+.Pp
+You may also lend copies, under the same conditions stated above, and you
+may publicly display copies.
+.Pp
+.It
+COPYING IN QUANTITY
+.Pp
+If you publish printed copies of the Document numbering more than 100, and
+the Document's license notice requires Cover Texts, you must enclose the copies
+in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover
+Texts on the front cover, and Back-Cover Texts on the back cover. Both covers
+must also clearly and legibly identify you as the publisher of these copies.
+The front cover must present the full title with all words of the title equally
+prominent and visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve the title
+of the Document and satisfy these conditions, can be treated as verbatim copying
+in other respects.
+.Pp
+If the required texts for either cover are too voluminous to fit legibly,
+you should put the first ones listed (as many as fit reasonably) on the actual
+cover, and continue the rest onto adjacent pages.
+.Pp
+If you publish or distribute Opaque copies of the Document numbering more
+than 100, you must either include a machine-readable Transparent copy along
+with each Opaque copy, or state in or with each Opaque copy a publicly-accessible
+computer-network location containing a complete Transparent copy of the Document,
+free of added material, which the general network-using public has access
+to download anonymously at no charge using public-standard network protocols.
+If you use the latter option, you must take reasonably prudent steps, when
+you begin distribution of Opaque copies in quantity, to ensure that this Transparent
+copy will remain thus accessible at the stated location until at least one
+year after the last time you distribute an Opaque copy (directly or through
+your agents or retailers) of that edition to the public.
+.Pp
+It is requested, but not required, that you contact the authors of the Document
+well before redistributing any large number of copies, to give them a chance
+to provide you with an updated version of the Document.
+.Pp
+.It
+MODIFICATIONS
+.Pp
+You may copy and distribute a Modified Version of the Document under the conditions
+of sections 2 and 3 above, provided that you release the Modified Version
+under precisely this License, with the Modified Version filling the role of
+the Document, thus licensing distribution and modification of the Modified
+Version to whoever possesses a copy of it. In addition, you must do these
+things in the Modified Version:
+.Pp
+A. Use in the Title Page (and on the covers, if any) a title distinct from
+that of the Document, and from those of previous versions (which should, if
+there were any, be listed in the History section of the Document). You may
+use the same title as a previous version if the original publisher of that
+version gives permission.  B. List on the Title Page, as authors, one or more
+persons or entities responsible for authorship of the modifications in the
+Modified Version, together with at least five of the principal authors of
+the Document (all of its principal authors, if it has less than five).  C.
+State on the Title page the name of the publisher of the Modified Version,
+as the publisher.  D. Preserve all the copyright notices of the Document. 
+E. Add an appropriate copyright notice for your modifications adjacent to
+the other copyright notices.  F. Include, immediately after the copyright
+notices, a license notice giving the public permission to use the Modified
+Version under the terms of this License, in the form shown in the Addendum
+below.  G. Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.  H. Include
+an unaltered copy of this License.  I. Preserve the section entitled \(lqHistory\(rq,
+and its title, and add to it an item stating at least the title, year, new
+authors, and publisher of the Modified Version as given on the Title Page.
+If there is no section entitled \(lqHistory\(rq in the Document, create one stating
+the title, year, authors, and publisher of the Document as given on its Title
+Page, then add an item describing the Modified Version as stated in the previous
+sentence.  J. Preserve the network location, if any, given in the Document
+for public access to a Transparent copy of the Document, and likewise the
+network locations given in the Document for previous versions it was based
+on. These may be placed in the \(lqHistory\(rq section. You may omit a network location
+for a work that was published at least four years before the Document itself,
+or if the original publisher of the version it refers to gives permission. 
+K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's
+title, and preserve in the section all the substance and tone of each of the
+contributor acknowledgements and/or dedications given therein.  L. Preserve
+all the Invariant Sections of the Document, unaltered in their text and in
+their titles. Section numbers or the equivalent are not considered part of
+the section titles.  M. Delete any section entitled \(lqEndorsements.\(rq Such a section
+may not be included in the Modified Version.  N. Do not retitle any existing
+section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. 
+.Pp
+If the Modified Version includes new front-matter sections or appendices that
+qualify as Secondary Sections and contain no material copied from the Document,
+you may at your option designate some or all of these sections as invariant.
+To do this, add their titles to the list of Invariant Sections in the Modified
+Version's license notice. These titles must be distinct from any other section
+titles.
+.Pp
+You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing
+but endorsements of your Modified Version by various parties--for example,
+statements of peer review or that the text has been approved by an organization
+as the authoritative definition of a standard.
+.Pp
+You may add a passage of up to five words as a Front-Cover Text, and a passage
+of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts
+in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover
+Text may be added by (or through arrangements made by) any one entity. If
+the Document already includes a cover text for the same cover, previously
+added by you or by arrangement made by the same entity you are acting on behalf
+of, you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+.Pp
+The author(s) and publisher(s) of the Document do not by this License give
+permission to use their names for publicity for or to assert or imply endorsement
+of any Modified Version.
+.Pp
+.It
+COMBINING DOCUMENTS
+.Pp
+You may combine the Document with other documents released under this License,
+under the terms defined in section 4 above for modified versions, provided
+that you include in the combination all of the Invariant Sections of all of
+the original documents, unmodified, and list them all as Invariant Sections
+of your combined work in its license notice.
+.Pp
+The combined work need only contain one copy of this License, and multiple
+identical Invariant Sections may be replaced with a single copy. If there
+are multiple Invariant Sections with the same name but different contents,
+make the title of each such section unique by adding at the end of it, in
+parentheses, the name of the original author or publisher of that section
+if known, or else a unique number. Make the same adjustment to the section
+titles in the list of Invariant Sections in the license notice of the combined
+work.
+.Pp
+In the combination, you must combine any sections entitled \(lqHistory\(rq in the
+various original documents, forming one section entitled \(lqHistory\(rq; likewise
+combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled
+\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq
+.Pp
+.It
+COLLECTIONS OF DOCUMENTS
+.Pp
+You may make a collection consisting of the Document and other documents released
+under this License, and replace the individual copies of this License in the
+various documents with a single copy that is included in the collection, provided
+that you follow the rules of this License for verbatim copying of each of
+the documents in all other respects.
+.Pp
+You may extract a single document from such a collection, and distribute it
+individually under this License, provided you insert a copy of this License
+into the extracted document, and follow this License in all other respects
+regarding verbatim copying of that document.
+.Pp
+.It
+AGGREGATION WITH INDEPENDENT WORKS
+.Pp
+A compilation of the Document or its derivatives with other separate and independent
+documents or works, in or on a volume of a storage or distribution medium,
+does not as a whole count as a Modified Version of the Document, provided
+no compilation copyright is claimed for the compilation. Such a compilation
+is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained
+works thus compiled with the Document, on account of their being thus compiled,
+if they are not themselves derivative works of the Document.
+.Pp
+If the Cover Text requirement of section 3 is applicable to these copies of
+the Document, then if the Document is less than one quarter of the entire
+aggregate, the Document's Cover Texts may be placed on covers that surround
+only the Document within the aggregate. Otherwise they must appear on covers
+around the whole aggregate.
+.Pp
+.It
+TRANSLATION
+.Pp
+Translation is considered a kind of modification, so you may distribute translations
+of the Document under the terms of section 4. Replacing Invariant Sections
+with translations requires special permission from their copyright holders,
+but you may include translations of some or all Invariant Sections in addition
+to the original versions of these Invariant Sections. You may include a translation
+of this License provided that you also include the original English version
+of this License. In case of a disagreement between the translation and the
+original English version of this License, the original English version will
+prevail.
+.Pp
+.It
+TERMINATION
+.Pp
+You may not copy, modify, sublicense, or distribute the Document except as
+expressly provided for under this License. Any other attempt to copy, modify,
+sublicense or distribute the Document is void, and will automatically terminate
+your rights under this License. However, parties who have received copies,
+or rights, from you under this License will not have their licenses terminated
+so long as such parties remain in full compliance.
+.Pp
+.It
+FUTURE REVISIONS OF THIS LICENSE
+.Pp
+The Free Software Foundation may publish new, revised versions of the GNU
+Free Documentation License from time to time. Such new versions will be similar
+in spirit to the present version, but may differ in detail to address new
+problems or concerns. See http://www.gnu.org/copyleft/.
+.Pp
+Each version of the License is given a distinguishing version number. If the
+Document specifies that a particular numbered version of this License \(lqor any
+later version\(rq applies to it, you have the option of following the terms and
+conditions either of that specified version or of any later version that has
+been published (not as a draft) by the Free Software Foundation. If the Document
+does not specify a version number of this License, you may choose any version
+ever published (not as a draft) by the Free Software Foundation.
+.Pp
+.El
+.Ss  ADDENDUM: How to use this License for your documents
+To use this License in a document you have written, include a copy of the
+License in the document and put the following copyright and license notices
+just after the title page:
+.Pp
+.Bd -literal -offset indent
+
+Copyright (C)  year  your name.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with the Invariant Sections being list their titles, with the
+Front-Cover Texts being list, and with the Back-Cover Texts being list.
+A copy of the license is included in the section entitled "GNU
+Free Documentation License."
+
+.Ed
+.Pp
+If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead
+of saying which ones are invariant. If you have no Front-Cover Texts, write
+\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being
+.Va list
+\(rq; likewise for Back-Cover Texts.
+.Pp
+If your document contains nontrivial examples of program code, we recommend
+releasing these examples in parallel under your choice of free software license,
+such as the GNU General Public License, to permit their use in free software.
+.Pp
+.Sh  Binutils Index
diff --git a/contrib/binutils/gas/doc/as.7 b/contrib/binutils/gas/doc/as.7
new file mode 100644
index 0000000..4d33557
--- /dev/null
+++ b/contrib/binutils/gas/doc/as.7
@@ -0,0 +1,8368 @@
+.Dd 2015-03-02
+.Dt AS 7
+.Os
+.Sh NAME
+.Nm as
+.Nd Using as (machine specific)
+.Sh  Using as
+This file is a user guide to the GNU assembler
+.Xr as
+version "2.17.50 [FreeBSD] 2007-07-03". This version of the file describes
+.Xr as
+configured to generate code for machine specific architectures.
+.Pp
+This document is distributed under the terms of the GNU Free Documentation
+License. A copy of the license is included in the section entitled \(lqGNU Free
+Documentation License\(rq.
+.Pp
+.Sh  Overview
+Here is a brief summary of how to invoke
+.Xr as .
+For details, see Invoking,,Command-Line Options.
+.Pp
+.Bd -literal -offset indent
+as [-a[cdhlns][=file]] [--alternate] [-D]
+ [--defsym sym=val] [-f] [-g] [--gstabs]
+ [--gstabs+] [--gdwarf-2] [--help] [-I dir] [-J]
+ [-K] [-L] [--listing-lhs-width=NUM]
+ [--listing-lhs-width2=NUM] [--listing-rhs-width=NUM]
+ [--listing-cont-lines=NUM] [--keep-locals] [-o
+ objfile] [-R] [--reduce-memory-overheads] [--statistics]
+ [-v] [-version] [--version] [-W] [--warn]
+ [--fatal-warnings] [-w] [-x] [-Z] [@FILE]
+ [--target-help] [target-options]
+ [--|files ...]
+
+Target ARM options:
+   [-mcpu=processor[+extension...]]
+   [-march=architecture[+extension...]]
+   [-mfpu=floating-point-format]
+   [-mfloat-abi=abi]
+   [-meabi=ver]
+   [-mthumb]
+   [-EB|-EL]
+   [-mapcs-32|-mapcs-26|-mapcs-float|
+    -mapcs-reentrant]
+   [-mthumb-interwork] [-k]
+
+
+Target i386 options:
+   [--32|--64] [-n]
+   [-march=CPU] [-mtune=CPU] 
+
+
+Target IA-64 options:
+   [-mconstant-gp|-mauto-pic]
+   [-milp32|-milp64|-mlp64|-mp64]
+   [-mle|mbe]
+   [-mtune=itanium1|-mtune=itanium2]
+   [-munwind-check=warning|-munwind-check=error]
+   [-mhint.b=ok|-mhint.b=warning|-mhint.b=error]
+   [-x|-xexplicit] [-xauto] [-xdebug]
+
+
+Target MIPS options:
+   [-nocpp] [-EL] [-EB] [-O[optimization level]]
+   [-g[debug level]] [-G num] [-KPIC] [-call_shared]
+   [-non_shared] [-xgot [-mvxworks-pic]
+   [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32]
+   [-march=CPU] [-mtune=CPU] [-mips1] [-mips2]
+   [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2]
+   [-mips64] [-mips64r2]
+   [-construct-floats] [-no-construct-floats]
+   [-trap] [-no-break] [-break] [-no-trap]
+   [-mfix7000] [-mno-fix7000]
+   [-mips16] [-no-mips16]
+   [-msmartmips] [-mno-smartmips]
+   [-mips3d] [-no-mips3d]
+   [-mdmx] [-no-mdmx]
+   [-mdsp] [-mno-dsp]
+   [-mdspr2] [-mno-dspr2]
+   [-mmt] [-mno-mt]
+   [-mdebug] [-no-mdebug]
+   [-mpdr] [-mno-pdr]
+
+
+Target PowerPC options:
+   [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604|
+    -m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke|
+    -mbooke32|-mbooke64]
+   [-mcom|-many|-maltivec] [-memb]
+   [-mregnames|-mno-regnames]
+   [-mrelocatable|-mrelocatable-lib]
+   [-mlittle|-mlittle-endian|-mbig|-mbig-endian]
+   [-msolaris|-mno-solaris]
+
+
+Target SPARC options:
+   [-Av6|-Av7|-Av8|-Asparclet|-Asparclite
+    -Av8plus|-Av8plusa|-Av9|-Av9a]
+   [-xarch=v8plus|-xarch=v8plusa] [-bump]
+   [-32|-64]
+
+
+
+.Ed
+.Pp
+.Bl -tag -width Ds
+.It  @ Va file
+Read command-line options from
+.Va file .
+The options read are inserted in place of the original @
+.Va file
+option. If
+.Va file
+does not exist, or cannot be read, then the option will be treated literally,
+and not removed.
+.Pp
+Options in
+.Va file
+are separated by whitespace. A whitespace character may be included in an
+option by surrounding the entire option in either single or double quotes.
+Any character (including a backslash) may be included by prefixing the character
+to be included with a backslash. The
+.Va file
+may itself contain additional @
+.Va file
+options; any such options will be processed recursively.
+.Pp
+.It  -a[cdhlmns]
+Turn on listings, in any of a variety of ways:
+.Pp
+.Bl -tag -width Ds
+.It  -ac
+omit false conditionals
+.Pp
+.It  -ad
+omit debugging directives
+.Pp
+.It  -ah
+include high-level source
+.Pp
+.It  -al
+include assembly
+.Pp
+.It  -am
+include macro expansions
+.Pp
+.It  -an
+omit forms processing
+.Pp
+.It  -as
+include symbols
+.Pp
+.It  =file
+set the name of the listing file
+.El
+.Pp
+You may combine these options; for example, use
+.Li -aln
+for assembly listing without forms processing. The
+.Li =file
+option, if used, must be the last one. By itself,
+.Li -a
+defaults to
+.Li -ahls .
+.Pp
+.It  --alternate
+Begin in alternate macro mode.See Section
+.Dq Altmacro .
+.Pp
+.It  -D
+Ignored. This option is accepted for script compatibility with calls to other
+assemblers.
+.Pp
+.It  --defsym Va sym= Va value
+Define the symbol
+.Va sym
+to be
+.Va value
+before assembling the input file.
+.Va value
+must be an integer constant. As in C, a leading
+.Li 0x
+indicates a hexadecimal value, and a leading
+.Li 0
+indicates an octal value. The value of the symbol can be overridden inside
+a source file via the use of a
+.Li .set
+pseudo-op.
+.Pp
+.It  -f
+\(lqfast\(rq---skip whitespace and comment preprocessing (assume source is compiler
+output).
+.Pp
+.It  -g
+.It  --gen-debug
+Generate debugging information for each assembler source line using whichever
+debug format is preferred by the target. This currently means either STABS,
+ECOFF or DWARF2.
+.Pp
+.It  --gstabs
+Generate stabs debugging information for each assembler line. This may help
+debugging assembler code, if the debugger can handle it.
+.Pp
+.It  --gstabs+
+Generate stabs debugging information for each assembler line, with GNU extensions
+that probably only gdb can handle, and that could make other debuggers crash
+or refuse to read your program. This may help debugging assembler code. Currently
+the only GNU extension is the location of the current working directory at
+assembling time.
+.Pp
+.It  --gdwarf-2
+Generate DWARF2 debugging information for each assembler line. This may help
+debugging assembler code, if the debugger can handle it. Note---this option
+is only supported by some targets, not all of them.
+.Pp
+.It  --help
+Print a summary of the command line options and exit.
+.Pp
+.It  --target-help
+Print a summary of all target specific options and exit.
+.Pp
+.It  -I Va dir
+Add directory
+.Va dir
+to the search list for
+.Li .include
+directives.
+.Pp
+.It  -J
+Don't warn about signed overflow.
+.Pp
+.It  -K
+This option is accepted but has no effect on the machine specific family.
+.Pp
+.It  -L
+.It  --keep-locals
+Keep (in the symbol table) local symbols. These symbols start with system-specific
+local label prefixes, typically
+.Li .L
+for ELF systems or
+.Li L
+for traditional a.out systems.See Section
+.Dq Symbol Names .
+.Pp
+.It  --listing-lhs-width= Va number
+Set the maximum width, in words, of the output data column for an assembler
+listing to
+.Va number .
+.Pp
+.It  --listing-lhs-width2= Va number
+Set the maximum width, in words, of the output data column for continuation
+lines in an assembler listing to
+.Va number .
+.Pp
+.It  --listing-rhs-width= Va number
+Set the maximum width of an input source line, as displayed in a listing,
+to
+.Va number
+bytes.
+.Pp
+.It  --listing-cont-lines= Va number
+Set the maximum number of lines printed in a listing for a single line of
+input to
+.Va number
++ 1.
+.Pp
+.It  -o Va objfile
+Name the object-file output from
+.Xr as
+.Va objfile .
+.Pp
+.It  -R
+Fold the data section into the text section.
+.Pp
+Set the default size of GAS's hash tables to a prime number close to
+.Va number .
+Increasing this value can reduce the length of time it takes the assembler
+to perform its tasks, at the expense of increasing the assembler's memory
+requirements. Similarly reducing this value can reduce the memory requirements
+at the expense of speed.
+.Pp
+.It  --reduce-memory-overheads
+This option reduces GAS's memory requirements, at the expense of making the
+assembly processes slower. Currently this switch is a synonym for
+.Li --hash-size=4051 ,
+but in the future it may have other effects as well.
+.Pp
+.It  --statistics
+Print the maximum space (in bytes) and total time (in seconds) used by assembly.
+.Pp
+.It  --strip-local-absolute
+Remove local absolute symbols from the outgoing symbol table.
+.Pp
+.It  -v
+.It  -version
+Print the
+.Xr as
+version.
+.Pp
+.It  --version
+Print the
+.Xr as
+version and exit.
+.Pp
+.It  -W
+.It  --no-warn
+Suppress warning messages.
+.Pp
+.It  --fatal-warnings
+Treat warnings as errors.
+.Pp
+.It  --warn
+Don't suppress warning messages or treat them as errors.
+.Pp
+.It  -w
+Ignored.
+.Pp
+.It  -x
+Ignored.
+.Pp
+.It  -Z
+Generate an object file even after errors.
+.Pp
+.It  -- | Va files ...
+Standard input, or source files to assemble.
+.Pp
+.El
+The following options are available when as is configured for the ARM processor
+family.
+.Pp
+.Bl -tag -width Ds
+.It  -mcpu= Va processor[+ Va extension...]
+Specify which ARM processor variant is the target.
+.It  -march= Va architecture[+ Va extension...]
+Specify which ARM architecture variant is used by the target.
+.It  -mfpu= Va floating-point-format
+Select which Floating Point architecture is the target.
+.It  -mfloat-abi= Va abi
+Select which floating point ABI is in use.
+.It  -mthumb
+Enable Thumb only instruction decoding.
+.It  -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant
+Select which procedure calling convention is in use.
+.It  -EB | -EL
+Select either big-endian (-EB) or little-endian (-EL) output.
+.It  -mthumb-interwork
+Specify that the code has been generated with interworking between Thumb and
+ARM code in mind.
+.It  -k
+Specify that PIC code has been generated.
+.El
+.Pp
+The following options are available when
+.Xr as
+is configured for the SPARC architecture:
+.Pp
+.Bl -tag -width Ds
+.It  -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
+.It  -Av8plus | -Av8plusa | -Av9 | -Av9a
+Explicitly select a variant of the SPARC architecture.
+.Pp
+.Li -Av8plus
+and
+.Li -Av8plusa
+select a 32 bit environment.
+.Li -Av9
+and
+.Li -Av9a
+select a 64 bit environment.
+.Pp
+.Li -Av8plusa
+and
+.Li -Av9a
+enable the SPARC V9 instruction set with UltraSPARC extensions.
+.Pp
+.It  -xarch=v8plus | -xarch=v8plusa
+For compatibility with the Solaris v9 assembler. These options are equivalent
+to -Av8plus and -Av8plusa, respectively.
+.Pp
+.It  -bump
+Warn when the assembler switches to another architecture.
+.El
+.Pp
+The following options are available when as is configured for a mips processor.
+.Pp
+.Bl -tag -width Ds
+.It  -G Va num
+This option sets the largest size of an object that can be referenced implicitly
+with the
+.Li gp
+register. It is only accepted for targets that use ECOFF format, such as a
+DECstation running Ultrix. The default value is 8.
+.Pp
+.It  -EB
+Generate \(lqbig endian\(rq format output.
+.Pp
+.It  -EL
+Generate \(lqlittle endian\(rq format output.
+.Pp
+.It  -mips1
+.It  -mips2
+.It  -mips3
+.It  -mips4
+.It  -mips5
+.It  -mips32
+.It  -mips32r2
+.It  -mips64
+.It  -mips64r2
+Generate code for a particular mips Instruction Set Architecture level.
+.Li -mips1
+is an alias for
+.Li -march=r3000 ,
+.Li -mips2
+is an alias for
+.Li -march=r6000 ,
+.Li -mips3
+is an alias for
+.Li -march=r4000
+and
+.Li -mips4
+is an alias for
+.Li -march=r8000 .
+.Li -mips5 ,
+.Li -mips32 ,
+.Li -mips32r2 ,
+.Li -mips64 ,
+and
+.Li -mips64r2
+correspond to generic
+.Li MIPS V ,
+.Li MIPS32 ,
+.Li MIPS32 Release 2 ,
+.Li MIPS64 ,
+and
+.Li MIPS64 Release 2
+ISA processors, respectively.
+.Pp
+.It  -march= Va CPU
+Generate code for a particular mips cpu.
+.Pp
+.It  -mtune= Va cpu
+Schedule and tune for a particular mips cpu.
+.Pp
+.It  -mfix7000
+.It  -mno-fix7000
+Cause nops to be inserted if the read of the destination register of an mfhi
+or mflo instruction occurs in the following two instructions.
+.Pp
+.It  -mdebug
+.It  -no-mdebug
+Cause stabs-style debugging output to go into an ECOFF-style .mdebug section
+instead of the standard ELF .stabs sections.
+.Pp
+.It  -mpdr
+.It  -mno-pdr
+Control generation of
+.Li .pdr
+sections.
+.Pp
+.It  -mgp32
+.It  -mfp32
+The register sizes are normally inferred from the ISA and ABI, but these flags
+force a certain group of registers to be treated as 32 bits wide at all times.
+.Li -mgp32
+controls the size of general-purpose registers and
+.Li -mfp32
+controls the size of floating-point registers.
+.Pp
+.It  -mips16
+.It  -no-mips16
+Generate code for the MIPS 16 processor. This is equivalent to putting
+.Li .set mips16
+at the start of the assembly file.
+.Li -no-mips16
+turns off this option.
+.Pp
+.It  -msmartmips
+.It  -mno-smartmips
+Enables the SmartMIPS extension to the MIPS32 instruction set. This is equivalent
+to putting
+.Li .set smartmips
+at the start of the assembly file.
+.Li -mno-smartmips
+turns off this option.
+.Pp
+.It  -mips3d
+.It  -no-mips3d
+Generate code for the MIPS-3D Application Specific Extension. This tells the
+assembler to accept MIPS-3D instructions.
+.Li -no-mips3d
+turns off this option.
+.Pp
+.It  -mdmx
+.It  -no-mdmx
+Generate code for the MDMX Application Specific Extension. This tells the
+assembler to accept MDMX instructions.
+.Li -no-mdmx
+turns off this option.
+.Pp
+.It  -mdsp
+.It  -mno-dsp
+Generate code for the DSP Release 1 Application Specific Extension. This tells
+the assembler to accept DSP Release 1 instructions.
+.Li -mno-dsp
+turns off this option.
+.Pp
+.It  -mdspr2
+.It  -mno-dspr2
+Generate code for the DSP Release 2 Application Specific Extension. This option
+implies -mdsp. This tells the assembler to accept DSP Release 2 instructions.
+.Li -mno-dspr2
+turns off this option.
+.Pp
+.It  -mmt
+.It  -mno-mt
+Generate code for the MT Application Specific Extension. This tells the assembler
+to accept MT instructions.
+.Li -mno-mt
+turns off this option.
+.Pp
+.It  --construct-floats
+.It  --no-construct-floats
+The
+.Li --no-construct-floats
+option disables the construction of double width floating point constants
+by loading the two halves of the value into the two single width floating
+point registers that make up the double width register. By default
+.Li --construct-floats
+is selected, allowing construction of these floating point constants.
+.Pp
+.It  --emulation= Va name
+This option causes
+.Xr as
+to emulate
+.Xr as
+configured for some other target, in all respects, including output format
+(choosing between ELF and ECOFF only), handling of pseudo-opcodes which may
+generate debugging information or store symbol table information, and default
+endianness. The available configuration names are:
+.Li mipsecoff ,
+.Li mipself ,
+.Li mipslecoff ,
+.Li mipsbecoff ,
+.Li mipslelf ,
+.Li mipsbelf .
+The first two do not alter the default endianness from that of the primary
+target for which the assembler was configured; the others change the default
+to little- or big-endian as indicated by the
+.Li b
+or
+.Li l
+in the name. Using
+.Li -EB
+or
+.Li -EL
+will override the endianness selection in any case.
+.Pp
+This option is currently supported only when the primary target
+.Xr as
+is configured for is a mips ELF or ECOFF target. Furthermore, the primary
+target or others specified with
+.Li --enable-targets=...
+at configuration time must include support for the other format, if both are
+to be available. For example, the Irix 5 configuration includes support for
+both.
+.Pp
+Eventually, this option will support more configurations, with more fine-grained
+control over the assembler's behavior, and will be supported for more processors.
+.Pp
+.It  -nocpp
+.Xr as
+ignores this option. It is accepted for compatibility with the native tools.
+.Pp
+.It  --trap
+.It  --no-trap
+.It  --break
+.It  --no-break
+Control how to deal with multiplication overflow and division by zero.
+.Li --trap
+or
+.Li --no-break
+(which are synonyms) take a trap exception (and only work for Instruction
+Set Architecture level 2 and higher);
+.Li --break
+or
+.Li --no-trap
+(also synonyms, and the default) take a break exception.
+.Pp
+.It  -n
+When this option is used,
+.Xr as
+will issue a warning every time it generates a nop instruction from a macro.
+.El
+.Pp
+.Ss  Structure of this Manual
+This manual is intended to describe what you need to know to use GNU
+.Xr as .
+We cover the syntax expected in source files, including notation for symbols,
+constants, and expressions; the directives that
+.Xr as
+understands; and of course how to invoke
+.Xr as .
+.Pp
+We also cover special features in the machine specific configuration of
+.Xr as ,
+including assembler directives.
+.Pp
+On the other hand, this manual is
+.Em not
+intended as an introduction to programming in assembly language---let alone
+programming in general! In a similar vein, we make no attempt to introduce
+the machine architecture; we do
+.Em not
+describe the instruction set, standard mnemonics, registers or addressing
+modes that are standard to a particular architecture.
+.Pp
+.Ss  The GNU Assembler
+GNU
+.Xr as
+is really a family of assemblers. This manual describes
+.Xr as ,
+a member of that family which is configured for the machine specific architectures.
+If you use (or have used) the GNU assembler on one architecture, you should
+find a fairly similar environment when you use it on another architecture.
+Each version has much in common with the others, including object file formats,
+most assembler directives (often called
+.Em pseudo-ops )
+and assembler syntax.
+.Pp
+.Xr as
+is primarily intended to assemble the output of the GNU C compiler
+.Li gcc
+for use by the linker
+.Li ld .
+Nevertheless, we've tried to make
+.Xr as
+assemble correctly everything that other assemblers for the same machine would
+assemble.
+.Pp
+Unlike older assemblers,
+.Xr as
+is designed to assemble a source program in one pass of the source file. This
+has a subtle impact on the
+.Li .org
+directive (see Section
+.Dq Org ) .
+.Pp
+.Ss  Object File Formats
+The GNU assembler can be configured to produce several alternative object
+file formats. For the most part, this does not affect how you write assembly
+language programs; but directives for debugging symbols are typically different
+in different file formats.See Section
+.Dq Symbol Attributes .
+For the machine specific target,
+.Xr as
+is configured to produce ELF format object files.
+.Pp
+.Ss  Command Line
+After the program name
+.Xr as ,
+the command line may contain options and file names. Options may appear in
+any order, and may be before, after, or between file names. The order of file
+names is significant.
+.Pp
+.Pa --
+(two hyphens) by itself names the standard input file explicitly, as one of
+the files for
+.Xr as
+to assemble.
+.Pp
+Except for
+.Li --
+any command line argument that begins with a hyphen (
+.Li - )
+is an option. Each option changes the behavior of
+.Xr as .
+No option changes the way another option works. An option is a
+.Li -
+followed by one or more letters; the case of the letter is important. All
+options are optional.
+.Pp
+Some options expect exactly one file name to follow them. The file name may
+either immediately follow the option's letter (compatible with older assemblers)
+or it may be the next command argument (GNU standard). These two command lines
+are equivalent:
+.Pp
+.Bd -literal -offset indent
+as -o my-object-file.o mumble.s
+as -omy-object-file.o mumble.s
+.Ed
+.Pp
+.Ss  Input Files
+We use the phrase
+.Em source program ,
+abbreviated
+.Em source ,
+to describe the program input to one run of
+.Xr as .
+The program may be in one or more files; how the source is partitioned into
+files doesn't change the meaning of the source.
+.Pp
+The source program is a concatenation of the text in all the files, in the
+order specified.
+.Pp
+Each time you run
+.Xr as
+it assembles exactly one source program. The source program is made up of
+one or more files. (The standard input is also a file.)
+.Pp
+You give
+.Xr as
+a command line that has zero or more input file names. The input files are
+read (from left file name to right). A command line argument (in any position)
+that has no special meaning is taken to be an input file name.
+.Pp
+If you give
+.Xr as
+no file names it attempts to read one input file from the
+.Xr as
+standard input, which is normally your terminal. You may have to type ctl-D
+to tell
+.Xr as
+there is no more program to assemble.
+.Pp
+Use
+.Li --
+if you need to explicitly name the standard input file in your command line.
+.Pp
+If the source is empty,
+.Xr as
+produces a small, empty object file.
+.Pp
+.Em  Filenames and Line-numbers
+.Pp
+There are two ways of locating a line in the input file (or files) and either
+may be used in reporting error messages. One way refers to a line number in
+a physical file; the other refers to a line number in a \(lqlogical\(rq file.See Section
+.Dq Errors .
+.Pp
+.Em Physical files
+are those files named in the command line given to
+.Xr as .
+.Pp
+.Em Logical files
+are simply names declared explicitly by assembler directives; they bear no
+relation to physical files. Logical file names help error messages reflect
+the original source file, when
+.Xr as
+source is itself synthesized from other files.
+.Xr as
+understands the
+.Li #
+directives emitted by the
+.Li gcc
+preprocessor. See also File,,
+.Li .file
+\&.
+.Pp
+.Ss  Output (Object) File
+Every time you run
+.Xr as
+it produces an output file, which is your assembly language program translated
+into numbers. This file is the object file. Its default name is
+.Li a.out .
+You can give it another name by using the
+.Op -o
+option. Conventionally, object file names end with
+.Pa .o .
+The default name is used for historical reasons: older assemblers were capable
+of assembling self-contained programs directly into a runnable program. (For
+some formats, this isn't currently possible, but it can be done for the
+.Li a.out
+format.)
+.Pp
+The object file is meant for input to the linker
+.Li ld .
+It contains assembled program code, information to help
+.Li ld
+integrate the assembled program into a runnable file, and (optionally) symbolic
+information for the debugger.
+.Pp
+.Ss  Error and Warning Messages
+.Xr as
+may write warnings and error messages to the standard error file (usually
+your terminal). This should not happen when a compiler runs
+.Xr as
+automatically. Warnings report an assumption made so that
+.Xr as
+could keep assembling a flawed program; errors report a grave problem that
+stops the assembly.
+.Pp
+Warning messages have the format
+.Pp
+.Bd -literal -offset indent
+file_name:NNN:Warning Message Text
+.Ed
+.Pp
+(where
+.Sy NNN
+is a line number). If a logical file name has been given (see Section
+.Dq File )
+it is used for the filename, otherwise the name of the current input file
+is used. If a logical line number was given then it is used to calculate the
+number printed, otherwise the actual line in the current source file is printed.
+The message text is intended to be self explanatory (in the grand Unix tradition).
+.Pp
+Error messages have the format
+.Bd -literal -offset indent
+file_name:NNN:FATAL:Error Message Text
+.Ed
+The file name and line number are derived as for warning messages. The actual
+message text may be rather less explanatory because many of them aren't supposed
+to happen.
+.Pp
+.Sh  Command-Line Options
+This chapter describes command-line options available in
+.Em all
+versions of the GNU assembler; see Machine Dependencies, for options specific
+to the machine specific target.
+.Pp
+If you are invoking
+.Xr as
+via the GNU C compiler, you can use the
+.Li -Wa
+option to pass arguments through to the assembler. The assembler arguments
+must be separated from each other (and the
+.Li -Wa )
+by commas. For example:
+.Pp
+.Bd -literal -offset indent
+gcc -c -g -O -Wa,-alh,-L file.c
+.Ed
+.Pp
+This passes two options to the assembler:
+.Li -alh
+(emit a listing to standard output with high-level and assembly source) and
+.Li -L
+(retain local symbols in the symbol table).
+.Pp
+Usually you do not need to use this
+.Li -Wa
+mechanism, since many compiler command-line options are automatically passed
+to the assembler by the compiler. (You can call the GNU compiler driver with
+the
+.Li -v
+option to see precisely what options it passes to each compilation pass, including
+the assembler.)
+.Pp
+.Ss  Enable Listings: Op -a[cdhlns]
+These options enable listing output from the assembler. By itself,
+.Li -a
+requests high-level, assembly, and symbols listing. You can use other letters
+to select specific options for the list:
+.Li -ah
+requests a high-level language listing,
+.Li -al
+requests an output-program assembly listing, and
+.Li -as
+requests a symbol table listing. High-level listings require that a compiler
+debugging option like
+.Li -g
+be used, and that assembly listings (
+.Li -al )
+be requested also.
+.Pp
+Use the
+.Li -ac
+option to omit false conditionals from a listing. Any lines which are not
+assembled because of a false
+.Li .if
+(or
+.Li .ifdef ,
+or any other conditional), or a true
+.Li .if
+followed by an
+.Li .else ,
+will be omitted from the listing.
+.Pp
+Use the
+.Li -ad
+option to omit debugging directives from the listing.
+.Pp
+Once you have specified one of these options, you can further control listing
+output and its appearance using the directives
+.Li .list ,
+.Li .nolist ,
+.Li .psize ,
+.Li .eject ,
+.Li .title ,
+and
+.Li .sbttl .
+The
+.Li -an
+option turns off all forms processing. If you do not request listing output
+with one of the
+.Li -a
+options, the listing-control directives have no effect.
+.Pp
+The letters after
+.Li -a
+may be combined into one option,
+.Em e.g. ,
+.Li -aln .
+.Pp
+Note if the assembler source is coming from the standard input (e.g., because
+it is being created by
+.Li gcc
+and the
+.Li -pipe
+command line switch is being used) then the listing will not contain any comments
+or preprocessor directives. This is because the listing code buffers input
+source lines from stdin only after they have been preprocessed by the assembler.
+This reduces memory usage and makes the code more efficient.
+.Pp
+.Ss  Op --alternate
+Begin in alternate macro mode, see Altmacro,,
+.Li .altmacro
+\&.
+.Pp
+.Ss  Op -D
+This option has no effect whatsoever, but it is accepted to make it more likely
+that scripts written for other assemblers also work with
+.Xr as .
+.Pp
+.Ss  Work Faster: Op -f
+.Li -f
+should only be used when assembling programs written by a (trusted) compiler.
+.Li -f
+stops the assembler from doing whitespace and comment preprocessing on the
+input file(s) before assembling them.See Section
+.Dq Preprocessing .
+.Pp
+.Qo
+.Em Warning:
+if you use
+.Li -f
+when the files actually need to be preprocessed (if they contain comments,
+for example),
+.Xr as
+does not work correctly.
+.Qc
+.Pp
+.Ss  Li .include Search Path: Op -I Va path
+Use this option to add a
+.Va path
+to the list of directories
+.Xr as
+searches for files specified in
+.Li .include
+directives (see Section
+.Dq Include ) .
+You may use
+.Op -I
+as many times as necessary to include a variety of paths. The current working
+directory is always searched first; after that,
+.Xr as
+searches any
+.Li -I
+directories in the same order as they were specified (left to right) on the
+command line.
+.Pp
+.Ss  Difference Tables: Op -K
+On the machine specific family, this option is allowed, but has no effect.
+It is permitted for compatibility with the GNU assembler on other platforms,
+where it can be used to warn when the assembler alters the machine code generated
+for
+.Li .word
+directives in difference tables. The machine specific family does not have
+the addressing limitations that sometimes lead to this alteration on other
+platforms.
+.Pp
+.Ss  Include Local Symbols: Op -L
+Symbols beginning with system-specific local label prefixes, typically
+.Li .L
+for ELF systems or
+.Li L
+for traditional a.out systems, are called
+.Em local symbols .
+See Section.Dq Symbol Names .
+Normally you do not see such symbols when debugging, because they are intended
+for the use of programs (like compilers) that compose assembler programs,
+not for your notice. Normally both
+.Xr as
+and
+.Li ld
+discard such symbols, so you do not normally debug with them.
+.Pp
+This option tells
+.Xr as
+to retain those local symbols in the object file. Usually if you do this you
+also tell the linker
+.Li ld
+to preserve those symbols.
+.Pp
+.Ss  Configuring listing output: Op --listing
+The listing feature of the assembler can be enabled via the command line switch
+.Li -a
+(see Section
+.Dq a ) .
+This feature combines the input source file(s) with a hex dump of the corresponding
+locations in the output object file, and displays them as a listing file.
+The format of this listing can be controlled by directives inside the assembler
+source (i.e.,
+.Li .list
+(see Section
+.Dq List ) ,
+.Li .title
+(see Section
+.Dq Title ) ,
+.Li .sbttl
+(see Section
+.Dq Sbttl ) ,
+.Li .psize
+(see Section
+.Dq Psize ) ,
+and
+.Li .eject
+(see Section
+.Dq Eject )
+and also by the following switches:
+.Pp
+.Bl -tag -width Ds
+.It  --listing-lhs-width= Li number
+Sets the maximum width, in words, of the first line of the hex byte dump.
+This dump appears on the left hand side of the listing output.
+.Pp
+.It  --listing-lhs-width2= Li number
+Sets the maximum width, in words, of any further lines of the hex byte dump
+for a given input source line. If this value is not specified, it defaults
+to being the same as the value specified for
+.Li --listing-lhs-width .
+If neither switch is used the default is to one.
+.Pp
+.It  --listing-rhs-width= Li number
+Sets the maximum width, in characters, of the source line that is displayed
+alongside the hex dump. The default value for this parameter is 100. The source
+line is displayed on the right hand side of the listing output.
+.Pp
+.It  --listing-cont-lines= Li number
+Sets the maximum number of continuation lines of hex dump that will be displayed
+for a given single line of source input. The default value is 4.
+.El
+.Pp
+.Ss  Assemble in MRI Compatibility Mode: Op -M
+The
+.Op -M
+or
+.Op --mri
+option selects MRI compatibility mode. This changes the syntax and pseudo-op
+handling of
+.Xr as
+to make it compatible with the
+.Li ASM68K
+or the
+.Li ASM960
+(depending upon the configured target) assembler from Microtec Research. The
+exact nature of the MRI syntax will not be documented here; see the MRI manuals
+for more information. Note in particular that the handling of macros and macro
+arguments is somewhat different. The purpose of this option is to permit assembling
+existing MRI assembler code using
+.Xr as .
+.Pp
+The MRI compatibility is not complete. Certain operations of the MRI assembler
+depend upon its object file format, and can not be supported using other object
+file formats. Supporting these would require enhancing each object file format
+individually. These are:
+.Pp
+.Bl -bullet
+.It
+global symbols in common section
+.Pp
+The m68k MRI assembler supports common sections which are merged by the linker.
+Other object file formats do not support this.
+.Xr as
+handles common sections by treating them as a single common symbol. It permits
+local symbols to be defined within a common section, but it can not support
+global symbols, since it has no way to describe them.
+.Pp
+.It
+complex relocations
+.Pp
+The MRI assemblers support relocations against a negated section address,
+and relocations which combine the start addresses of two or more sections.
+These are not support by other object file formats.
+.Pp
+.It
+.Li END
+pseudo-op specifying start address
+.Pp
+The MRI
+.Li END
+pseudo-op permits the specification of a start address. This is not supported
+by other object file formats. The start address may instead be specified using
+the
+.Op -e
+option to the linker, or in a linker script.
+.Pp
+.It
+.Li IDNT ,
+.Li .ident
+and
+.Li NAME
+pseudo-ops
+.Pp
+The MRI
+.Li IDNT ,
+.Li .ident
+and
+.Li NAME
+pseudo-ops assign a module name to the output file. This is not supported
+by other object file formats.
+.Pp
+.It
+.Li ORG
+pseudo-op
+.Pp
+The m68k MRI
+.Li ORG
+pseudo-op begins an absolute section at a given address. This differs from
+the usual
+.Xr as
+.Li .org
+pseudo-op, which changes the location within the current section. Absolute
+sections are not supported by other object file formats. The address of a
+section may be assigned within a linker script.
+.El
+.Pp
+There are some other features of the MRI assembler which are not supported
+by
+.Xr as ,
+typically either because they are difficult or because they seem of little
+consequence. Some of these may be supported in future releases.
+.Pp
+.Bl -bullet
+.It
+EBCDIC strings
+.Pp
+EBCDIC strings are not supported.
+.Pp
+.It
+packed binary coded decimal
+.Pp
+Packed binary coded decimal is not supported. This means that the
+.Li DC.P
+and
+.Li DCB.P
+pseudo-ops are not supported.
+.Pp
+.It
+.Li FEQU
+pseudo-op
+.Pp
+The m68k
+.Li FEQU
+pseudo-op is not supported.
+.Pp
+.It
+.Li NOOBJ
+pseudo-op
+.Pp
+The m68k
+.Li NOOBJ
+pseudo-op is not supported.
+.Pp
+.It
+.Li OPT
+branch control options
+.Pp
+The m68k
+.Li OPT
+branch control options---
+.Li B ,
+.Li BRS ,
+.Li BRB ,
+.Li BRL ,
+and
+.Li BRW
+---are ignored.
+.Xr as
+automatically relaxes all branches, whether forward or backward, to an appropriate
+size, so these options serve no purpose.
+.Pp
+.It
+.Li OPT
+list control options
+.Pp
+The following m68k
+.Li OPT
+list control options are ignored:
+.Li C ,
+.Li CEX ,
+.Li CL ,
+.Li CRE ,
+.Li E ,
+.Li G ,
+.Li I ,
+.Li M ,
+.Li MEX ,
+.Li MC ,
+.Li MD ,
+.Li X .
+.Pp
+.It
+other
+.Li OPT
+options
+.Pp
+The following m68k
+.Li OPT
+options are ignored:
+.Li NEST ,
+.Li O ,
+.Li OLD ,
+.Li OP ,
+.Li P ,
+.Li PCO ,
+.Li PCR ,
+.Li PCS ,
+.Li R .
+.Pp
+.It
+.Li OPT
+.Li D
+option is default
+.Pp
+The m68k
+.Li OPT
+.Li D
+option is the default, unlike the MRI assembler.
+.Li OPT NOD
+may be used to turn it off.
+.Pp
+.It
+.Li XREF
+pseudo-op.
+.Pp
+The m68k
+.Li XREF
+pseudo-op is ignored.
+.Pp
+.It
+.Li .debug
+pseudo-op
+.Pp
+The i960
+.Li .debug
+pseudo-op is not supported.
+.Pp
+.It
+.Li .extended
+pseudo-op
+.Pp
+The i960
+.Li .extended
+pseudo-op is not supported.
+.Pp
+.It
+.Li .list
+pseudo-op.
+.Pp
+The various options of the i960
+.Li .list
+pseudo-op are not supported.
+.Pp
+.It
+.Li .optimize
+pseudo-op
+.Pp
+The i960
+.Li .optimize
+pseudo-op is not supported.
+.Pp
+.It
+.Li .output
+pseudo-op
+.Pp
+The i960
+.Li .output
+pseudo-op is not supported.
+.Pp
+.It
+.Li .setreal
+pseudo-op
+.Pp
+The i960
+.Li .setreal
+pseudo-op is not supported.
+.Pp
+.El
+.Ss  Dependency Tracking: Op --MD
+.Xr as
+can generate a dependency file for the file it creates. This file consists
+of a single rule suitable for
+.Li make
+describing the dependencies of the main source file.
+.Pp
+The rule is written to the file named in its argument.
+.Pp
+This feature is used in the automatic updating of makefiles.
+.Pp
+.Ss  Name the Object File: Op -o
+There is always one object file output when you run
+.Xr as .
+By default it has the name
+.Pa a.out .
+You use this option (which takes exactly one filename) to give the object
+file a different name.
+.Pp
+Whatever the object file is called,
+.Xr as
+overwrites any existing file of the same name.
+.Pp
+.Ss  Join Data and Text Sections: Op -R
+.Op -R
+tells
+.Xr as
+to write the object file as if all data-section data lives in the text section.
+This is only done at the very last moment: your binary data are the same,
+but data section parts are relocated differently. The data section part of
+your object file is zero bytes long because all its bytes are appended to
+the text section. (See Section
+.Dq Sections . )
+.Pp
+When you specify
+.Op -R
+it would be possible to generate shorter address displacements (because we
+do not have to cross between text and data section). We refrain from doing
+this simply for compatibility with older versions of
+.Xr as .
+In future,
+.Op -R
+may work this way.
+.Pp
+When
+.Xr as
+is configured for COFF or ELF output, this option is only useful if you use
+sections named
+.Li .text
+and
+.Li .data .
+.Pp
+.Ss  Display Assembly Statistics: Op --statistics
+Use
+.Li --statistics
+to display two statistics about the resources used by
+.Xr as :
+the maximum amount of space allocated during the assembly (in bytes), and
+the total execution time taken for the assembly (in cpu seconds).
+.Pp
+.Ss  Compatible Output: Op --traditional-format
+For some targets, the output of
+.Xr as
+is different in some ways from the output of some existing assembler. This
+switch requests
+.Xr as
+to use the traditional format instead.
+.Pp
+For example, it disables the exception frame optimizations which
+.Xr as
+normally does by default on
+.Li gcc
+output.
+.Pp
+.Ss  Announce Version: Op -v
+You can find out what version of as is running by including the option
+.Li -v
+(which you can also spell as
+.Li -version )
+on the command line.
+.Pp
+.Ss  Control Warnings: Op -W, Op --warn, Op --no-warn, Op --fatal-warnings
+.Xr as
+should never give a warning or error message when assembling compiler output.
+But programs written by people often cause
+.Xr as
+to give a warning that a particular assumption was made. All such warnings
+are directed to the standard error file.
+.Pp
+If you use the
+.Op -W
+and
+.Op --no-warn
+options, no warnings are issued. This only affects the warning messages: it
+does not change any particular of how
+.Xr as
+assembles your file. Errors, which stop the assembly, are still reported.
+.Pp
+If you use the
+.Op --fatal-warnings
+option,
+.Xr as
+considers files that generate warnings to be in error.
+.Pp
+You can switch these options off again by specifying
+.Op --warn ,
+which causes warnings to be output as usual.
+.Pp
+.Ss  Generate Object File in Spite of Errors: Op -Z
+After an error message,
+.Xr as
+normally produces no output. If for some reason you are interested in object
+file output even after
+.Xr as
+gives an error message on your program, use the
+.Li -Z
+option. If there are any errors,
+.Xr as
+continues anyways, and writes an object file after a final warning message
+of the form
+.Li  Va n errors, Va m warnings, generating bad object file.
+.Pp
+.Sh  Syntax
+This chapter describes the machine-independent syntax allowed in a source
+file.
+.Xr as
+syntax is similar to what many other assemblers use; it is inspired by the
+BSD 4.2 assembler.
+.Pp
+.Ss  Preprocessing
+The
+.Xr as
+internal preprocessor:
+.Bl -bullet
+.It
+adjusts and removes extra whitespace. It leaves one space or tab before the
+keywords on a line, and turns any other whitespace on the line into a single
+space.
+.Pp
+.It
+removes all comments, replacing them with a single space, or an appropriate
+number of newlines.
+.Pp
+.It
+converts character constants into the appropriate numeric values.
+.El
+.Pp
+It does not do macro processing, include file handling, or anything else you
+may get from your C compiler's preprocessor. You can do include file processing
+with the
+.Li .include
+directive (see Section
+.Dq Include ) .
+You can use the GNU C compiler driver to get other \(lqCPP\(rq style preprocessing
+by giving the input file a
+.Li .S
+suffix.See Section
+.Dq Overall Options .
+.Pp
+Excess whitespace, comments, and character constants cannot be used in the
+portions of the input text that are not preprocessed.
+.Pp
+If the first line of an input file is
+.Li #NO_APP
+or if you use the
+.Li -f
+option, whitespace and comments are not removed from the input file. Within
+an input file, you can ask for whitespace and comment removal in specific
+portions of the by putting a line that says
+.Li #APP
+before the text that may contain whitespace or comments, and putting a line
+that says
+.Li #NO_APP
+after this text. This feature is mainly intend to support
+.Li asm
+statements in compilers whose output is otherwise free of comments and whitespace.
+.Pp
+.Ss  Whitespace
+.Em Whitespace
+is one or more blanks or tabs, in any order. Whitespace is used to separate
+symbols, and to make programs neater for people to read. Unless within character
+constants (see Section
+.Dq Characters ) ,
+any whitespace means the same as exactly one space.
+.Pp
+.Ss  Comments
+There are two ways of rendering comments to
+.Xr as .
+In both cases the comment is equivalent to one space.
+.Pp
+Anything from
+.Li /*
+through the next
+.Li */
+is a comment. This means you may not nest these comments.
+.Pp
+.Bd -literal -offset indent
+/*
+  The only way to include a newline ('\en') in a comment
+  is to use this sort of comment.
+*/
+
+/* This sort of comment does not nest. */
+.Ed
+.Pp
+Anything from the
+.Em line comment
+character to the next newline is considered a comment and is ignored. The
+line comment character is
+.Li @
+on the ARM;
+.Li #
+on the i386 and x86-64;
+.Li #
+for Motorola PowerPC;
+.Li !
+on the SPARC; see Machine Dependencies.
+.Pp
+To be compatible with past assemblers, lines that begin with
+.Li #
+have a special interpretation. Following the
+.Li #
+should be an absolute expression (see Section
+.Dq Expressions ) :
+the logical line number of the
+.Em next
+line. Then a string (see Section
+.Dq Strings )
+is allowed: if present it is a new logical file name. The rest of the line,
+if any, should be whitespace.
+.Pp
+If the first non-whitespace characters on the line are not numeric, the line
+is ignored. (Just like a comment.)
+.Pp
+.Bd -literal -offset indent
+                          # This is an ordinary comment.
+# 42-6 "new_file_name"    # New logical file name
+                          # This is logical line # 36.
+.Ed
+This feature is deprecated, and may disappear from future versions of
+.Xr as .
+.Pp
+.Ss  Symbols
+A
+.Em symbol
+is one or more characters chosen from the set of all letters (both upper and
+lower case), digits and the three characters
+.Li _.$ .
+No symbol may begin with a digit. Case is significant. There is no length
+limit: all characters are significant. Symbols are delimited by characters
+not in that set, or by the beginning of a file (since the source program must
+end with a newline, the end of a file is not a possible symbol delimiter).See Section
+.Dq Symbols .
+.Pp
+.Ss  Statements
+A
+.Em statement
+ends at a newline character (
+.Li \en )
+or at a semicolon (
+.Li ; ) .
+The newline or semicolon is considered part of the preceding statement. Newlines
+and semicolons within character constants are an exception: they do not end
+statements.
+.Pp
+It is an error to end any statement with end-of-file: the last character of
+any input file should be a newline.
+.Pp
+An empty statement is allowed, and may include whitespace. It is ignored.
+.Pp
+A statement begins with zero or more labels, optionally followed by a key
+symbol which determines what kind of statement it is. The key symbol determines
+the syntax of the rest of the statement. If the symbol begins with a dot
+.Li .
+then the statement is an assembler directive: typically valid for any computer.
+If the symbol begins with a letter the statement is an assembly language
+.Em instruction :
+it assembles into a machine language instruction.
+.Pp
+A label is a symbol immediately followed by a colon (
+.Li : ) .
+Whitespace before a label or after a colon is permitted, but you may not have
+whitespace between a label's symbol and its colon.See Section
+.Dq Labels .
+.Pp
+.Bd -literal -offset indent
+label:     .directive    followed by something
+another_label:           # This is an empty statement.
+           instruction   operand_1, operand_2, ...
+.Ed
+.Pp
+.Ss  Constants
+A constant is a number, written so that its value is known by inspection,
+without knowing any context. Like this:
+.Bd -literal -offset indent
+
+\&.byte  74, 0112, 092, 0x4A, 0X4a, 'J, '\eJ # All the same value.
+\&.ascii "Ring the bell\e7"                  # A string constant.
+\&.octa  0x123456789abcdef0123456789ABCDEF0 # A biGNUm.
+\&.float 0f-314159265358979323846264338327\e
+95028841971.693993751E-40                 # - pi, a flonum.
+
+.Ed
+.Pp
+.Em  Character Constants
+.Pp
+There are two kinds of character constants. A
+.Em character
+stands for one character in one byte and its value may be used in numeric
+expressions. String constants (properly called string
+.Em literals )
+are potentially many bytes and their values may not be used in arithmetic
+expressions.
+.Pp
+.No  Strings
+.Pp
+A
+.Em string
+is written between double-quotes. It may contain double-quotes or null characters.
+The way to get special characters into a string is to
+.Em escape
+these characters: precede them with a backslash
+.Li \e
+character. For example
+.Li \e\e
+represents one backslash: the first
+.Li \e
+is an escape which tells
+.Xr as
+to interpret the second character literally as a backslash (which prevents
+.Xr as
+from recognizing the second
+.Li \e
+as an escape character). The complete list of escapes follows.
+.Pp
+.Bl -tag -width Ds
+.It  \eb
+Mnemonic for backspace; for ASCII this is octal code 010.
+.Pp
+.It  \ef
+Mnemonic for FormFeed; for ASCII this is octal code 014.
+.Pp
+.It  \en
+Mnemonic for newline; for ASCII this is octal code 012.
+.Pp
+.It  \er
+Mnemonic for carriage-Return; for ASCII this is octal code 015.
+.Pp
+.It  \et
+Mnemonic for horizontal Tab; for ASCII this is octal code 011.
+.Pp
+.It  \e Va digit Va digit Va digit
+An octal character code. The numeric code is 3 octal digits. For compatibility
+with other Unix systems, 8 and 9 are accepted as digits: for example,
+.Li \e008
+has the value 010, and
+.Li \e009
+the value 011.
+.Pp
+.It  \e Li x Va hex-digits...
+A hex character code. All trailing hex digits are combined. Either upper or
+lower case
+.Li x
+works.
+.Pp
+.It  \e\e
+Represents one
+.Li \e
+character.
+.Pp
+.It  \e"
+Represents one
+.Li "
+character. Needed in strings to represent this character, because an unescaped
+.Li "
+would end the string.
+.Pp
+.It  \e Va anything-else
+Any other character when escaped by
+.Li \e
+gives a warning, but assembles as if the
+.Li \e
+was not present. The idea is that if you used an escape sequence you clearly
+didn't want the literal interpretation of the following character. However
+.Xr as
+has no other interpretation, so
+.Xr as
+knows it is giving you the wrong code and warns you of the fact.
+.El
+.Pp
+Which characters are escapable, and what those escapes represent, varies widely
+among assemblers. The current set is what we think the BSD 4.2 assembler recognizes,
+and is a subset of what most C compilers recognize. If you are in doubt, do
+not use an escape sequence.
+.Pp
+.No  Characters
+.Pp
+A single character may be written as a single quote immediately followed by
+that character. The same escapes apply to characters as to strings. So if
+you want to write the character backslash, you must write
+.Li '\e\e
+where the first
+.Li \e
+escapes the second
+.Li \e .
+As you can see, the quote is an acute accent, not a grave accent. A newline
+(or semicolon
+.Li ; )
+immediately following an acute accent is taken as a literal character and
+does not count as the end of a statement. The value of a character constant
+in a numeric expression is the machine's byte-wide code for that character.
+.Xr as
+assumes your character code is ASCII:
+.Li 'A
+means 65,
+.Li 'B
+means 66, and so on.
+.Pp
+.Em  Number Constants
+.Pp
+.Xr as
+distinguishes three kinds of numbers according to how they are stored in the
+target machine.
+.Em Integers
+are numbers that would fit into an
+.Li int
+in the C language.
+.Em BiGNUms
+are integers, but they are stored in more than 32 bits.
+.Em Flonums
+are floating point numbers, described below.
+.Pp
+.No  Integers
+.Pp
+A binary integer is
+.Li 0b
+or
+.Li 0B
+followed by zero or more of the binary digits
+.Li 01 .
+.Pp
+An octal integer is
+.Li 0
+followed by zero or more of the octal digits (
+.Li 01234567 ) .
+.Pp
+A decimal integer starts with a non-zero digit followed by zero or more digits
+(
+.Li 0123456789 ) .
+.Pp
+A hexadecimal integer is
+.Li 0x
+or
+.Li 0X
+followed by one or more hexadecimal digits chosen from
+.Li 0123456789abcdefABCDEF .
+.Pp
+Integers have the usual values. To denote a negative integer, use the prefix
+operator
+.Li -
+discussed under expressions (see Section
+.Dq Prefix Ops ) .
+.Pp
+.No  BiGNUms
+.Pp
+A
+.Em biGNUm
+has the same syntax and semantics as an integer except that the number (or
+its negative) takes more than 32 bits to represent in binary. The distinction
+is made because in some places integers are permitted while biGNUms are not.
+.Pp
+.No  Flonums
+.Pp
+A
+.Em flonum
+represents a floating point number. The translation is indirect: a decimal
+floating point number from the text is converted by
+.Xr as
+to a generic binary floating point number of more than sufficient precision.
+This generic floating point number is converted to a particular computer's
+floating point format (or formats) by a portion of
+.Xr as
+specialized to that computer.
+.Pp
+A flonum is written by writing (in order)
+.Bl -bullet
+.It
+The digit
+.Li 0 .
+.Pp
+.It
+A letter, to tell
+.Xr as
+the rest of the number is a flonum.
+.Pp
+.It
+An optional sign: either
+.Li +
+or
+.Li - .
+.Pp
+.It
+An optional
+.Em integer part :
+zero or more decimal digits.
+.Pp
+.It
+An optional
+.Em fractional part :
+.Li .
+followed by zero or more decimal digits.
+.Pp
+.It
+An optional exponent, consisting of:
+.Pp
+.Bl -bullet
+.It
+An
+.Li E
+or
+.Li e .
+.It
+Optional sign: either
+.Li +
+or
+.Li - .
+.It
+One or more decimal digits.
+.El
+.Pp
+.El
+At least one of the integer part or the fractional part must be present. The
+floating point number has the usual base-10 value.
+.Pp
+.Xr as
+does all processing using integers. Flonums are computed independently of
+any floating point hardware in the computer running
+.Xr as .
+.Pp
+.Sh  Sections and Relocation
+.Ss  Background
+Roughly, a section is a range of addresses, with no gaps; all data \(lqin\(rq those
+addresses is treated the same for some particular purpose. For example there
+may be a \(lqread only\(rq section.
+.Pp
+The linker
+.Li ld
+reads many object files (partial programs) and combines their contents to
+form a runnable program. When
+.Xr as
+emits an object file, the partial program is assumed to start at address 0.
+.Li ld
+assigns the final addresses for the partial program, so that different partial
+programs do not overlap. This is actually an oversimplification, but it suffices
+to explain how
+.Xr as
+uses sections.
+.Pp
+.Li ld
+moves blocks of bytes of your program to their run-time addresses. These blocks
+slide to their run-time addresses as rigid units; their length does not change
+and neither does the order of bytes within them. Such a rigid unit is called
+a
+.Em section .
+Assigning run-time addresses to sections is called
+.Em relocation .
+It includes the task of adjusting mentions of object-file addresses so they
+refer to the proper run-time addresses.
+.Pp
+An object file written by
+.Xr as
+has at least three sections, any of which may be empty. These are named
+.Em text ,
+.Em data
+and
+.Em bss
+sections.
+.Pp
+.Xr as
+can also generate whatever other named sections you specify using the
+.Li .section
+directive (see Section
+.Dq Section ) .
+If you do not use any directives that place output in the
+.Li .text
+or
+.Li .data
+sections, these sections still exist, but are empty.
+.Pp
+Within the object file, the text section starts at address
+.Li 0 ,
+the data section follows, and the bss section follows the data section.
+.Pp
+To let
+.Li ld
+know which data changes when the sections are relocated, and how to change
+that data,
+.Xr as
+also writes to the object file details of the relocation needed. To perform
+relocation
+.Li ld
+must know, each time an address in the object file is mentioned:
+.Bl -bullet
+.It
+Where in the object file is the beginning of this reference to an address?
+.It
+How long (in bytes) is this reference?
+.It
+Which section does the address refer to? What is the numeric value of
+.Bd -filled -offset indent
+(
+.Va address )
+\-(
+.Va start-address of section ) ?
+.Ed
+.It
+Is the reference to an address \(lqProgram-Counter relative\(rq?
+.El
+.Pp
+In fact, every address
+.Xr as
+ever uses is expressed as
+.Bd -filled -offset indent
+(
+.Va section )
++ (
+.Va offset into section )
+.Ed
+Further, most expressions
+.Xr as
+computes have this section-relative nature.
+.Pp
+In this manual we use the notation {
+.Va secname
+.Va N
+}to mean \(lqoffset
+.Va N
+into section
+.Va secname
+\&.\(rq
+.Pp
+Apart from text, data and bss sections you need to know about the
+.Em absolute
+section. When
+.Li ld
+mixes partial programs, addresses in the absolute section remain unchanged.
+For example, address
+.Li {absolute 0}
+is \(lqrelocated\(rq to run-time address 0 by
+.Li ld .
+Although the linker never arranges two partial programs' data sections with
+overlapping addresses after linking,
+.Em by definition
+their absolute sections must overlap. Address
+.Li {absolute 239}
+in one part of a program is always the same address when the program is running
+as address
+.Li {absolute 239}
+in any other part of the program.
+.Pp
+The idea of sections is extended to the
+.Em undefined
+section. Any address whose section is unknown at assembly time is by definition
+rendered {undefined
+.Va U
+}---where
+.Va U
+is filled in later. Since numbers are always defined, the only way to generate
+an undefined address is to mention an undefined symbol. A reference to a named
+common block would be such a symbol: its value is unknown at assembly time
+so it has section
+.Em undefined .
+.Pp
+By analogy the word
+.Em section
+is used to describe groups of sections in the linked program.
+.Li ld
+puts all partial programs' text sections in contiguous addresses in the linked
+program. It is customary to refer to the
+.Em text section
+of a program, meaning all the addresses of all partial programs' text sections.
+Likewise for data and bss sections.
+.Pp
+Some sections are manipulated by
+.Li ld ;
+others are invented for use of
+.Xr as
+and have no meaning except during assembly.
+.Pp
+.Ss  Linker Sections
+.Li ld
+deals with just four kinds of sections, summarized below.
+.Pp
+.Bl -tag -width Ds
+.It  named sections
+These sections hold your program.
+.Xr as
+and
+.Li ld
+treat them as separate but equal sections. Anything you can say of one section
+is true of another. When the program is running, however, it is customary
+for the text section to be unalterable. The text section is often shared among
+processes: it contains instructions, constants and the like. The data section
+of a running program is usually alterable: for example, C variables would
+be stored in the data section.
+.Pp
+.It  bss section
+This section contains zeroed bytes when your program begins running. It is
+used to hold uninitialized variables or common storage. The length of each
+partial program's bss section is important, but because it starts out containing
+zeroed bytes there is no need to store explicit zero bytes in the object file.
+The bss section was invented to eliminate those explicit zeros from object
+files.
+.Pp
+.It  absolute section
+Address 0 of this section is always \(lqrelocated\(rq to runtime address 0. This is
+useful if you want to refer to an address that
+.Li ld
+must not change when relocating. In this sense we speak of absolute addresses
+being \(lqunrelocatable\(rq: they do not change during relocation.
+.Pp
+.It  undefined section
+This \(lqsection\(rq is a catch-all for address references to objects not in the preceding
+sections.
+.El
+.Pp
+An idealized example of three relocatable sections follows. The example uses
+the traditional section names
+.Li .text
+and
+.Li .data .
+Memory addresses are on the horizontal axis.
+.Pp
+.Bd -literal -offset indent
+                      +-----+----+--+
+partial program # 1:  |ttttt|dddd|00|
+                      +-----+----+--+
+
+                      text   data bss
+                      seg.   seg. seg.
+
+                      +---+---+---+
+partial program # 2:  |TTT|DDD|000|
+                      +---+---+---+
+
+                      +--+---+-----+--+----+---+-----+~~
+linked program:       |  |TTT|ttttt|  |dddd|DDD|00000|
+                      +--+---+-----+--+----+---+-----+~~
+
+    addresses:        0 ...
+.Ed
+.Pp
+.Ss  Assembler Internal Sections
+These sections are meant only for the internal use of
+.Xr as .
+They have no meaning at run-time. You do not really need to know about these
+sections for most purposes; but they can be mentioned in
+.Xr as
+warning messages, so it might be helpful to have an idea of their meanings
+to
+.Xr as .
+These sections are used to permit the value of every expression in your assembly
+language program to be a section-relative address.
+.Pp
+.Bl -tag -width Ds
+.It  ASSEMBLER-INTERNAL-LOGIC-ERROR!
+An internal assembler logic error has been found. This means there is a bug
+in the assembler.
+.Pp
+.It  expr section
+The assembler stores complex expression internally as combinations of symbols.
+When it needs to represent an expression as a symbol, it puts it in the expr
+section.
+.El
+.Pp
+.Ss  Sub-Sections
+You may have separate groups of data in named sections that you want to end
+up near to each other in the object file, even though they are not contiguous
+in the assembler source.
+.Xr as
+allows you to use
+.Em subsections
+for this purpose. Within each section, there can be numbered subsections with
+values from 0 to 8192. Objects assembled into the same subsection go into
+the object file together with other objects in the same subsection. For example,
+a compiler might want to store constants in the text section, but might not
+want to have them interspersed with the program being assembled. In this case,
+the compiler could issue a
+.Li .text 0
+before each section of code being output, and a
+.Li .text 1
+before each group of constants being output.
+.Pp
+Subsections are optional. If you do not use subsections, everything goes in
+subsection number zero.
+.Pp
+Subsections appear in your object file in numeric order, lowest numbered to
+highest. (All this to be compatible with other people's assemblers.) The object
+file contains no representation of subsections;
+.Li ld
+and other programs that manipulate object files see no trace of them. They
+just see all your text subsections as a text section, and all your data subsections
+as a data section.
+.Pp
+To specify which subsection you want subsequent statements assembled into,
+use a numeric argument to specify it, in a
+.Li .text Va expression
+or a
+.Li .data Va expression
+statement. You can also use the
+.Li .subsection
+directive (see Section
+.Dq SubSection )
+to specify a subsection:
+.Li .subsection Va expression .
+.Va Expression
+should be an absolute expression (see Section
+.Dq Expressions ) .
+If you just say
+.Li .text
+then
+.Li .text 0
+is assumed. Likewise
+.Li .data
+means
+.Li .data 0 .
+Assembly begins in
+.Li text 0 .
+For instance:
+.Bd -literal -offset indent
+\&.text 0     # The default subsection is text 0 anyway.
+\&.ascii "This lives in the first text subsection. *"
+\&.text 1
+\&.ascii "But this lives in the second text subsection."
+\&.data 0
+\&.ascii "This lives in the data section,"
+\&.ascii "in the first data subsection."
+\&.text 0
+\&.ascii "This lives in the first text section,"
+\&.ascii "immediately following the asterisk (*)."
+.Ed
+.Pp
+Each section has a
+.Em location counter
+incremented by one for every byte assembled into that section. Because subsections
+are merely a convenience restricted to
+.Xr as
+there is no concept of a subsection location counter. There is no way to directly
+manipulate a location counter---but the
+.Li .align
+directive changes it, and any label definition captures its current value.
+The location counter of the section where statements are being assembled is
+said to be the
+.Em active
+location counter.
+.Pp
+.Ss  bss Section
+The bss section is used for local common variable storage. You may allocate
+address space in the bss section, but you may not dictate data to load into
+it before your program executes. When your program starts running, all the
+contents of the bss section are zeroed bytes.
+.Pp
+The
+.Li .lcomm
+pseudo-op defines a symbol in the bss section; see Lcomm,,
+.Li .lcomm
+\&.
+.Pp
+The
+.Li .comm
+pseudo-op may be used to declare a common symbol, which is another form of
+uninitialized symbol; see Comm,,
+.Li .comm
+\&.
+.Pp
+.Sh  Symbols
+Symbols are a central concept: the programmer uses symbols to name things,
+the linker uses symbols to link, and the debugger uses symbols to debug.
+.Pp
+.Qo
+.Em Warning:
+.Xr as
+does not place symbols in the object file in the same order they were declared.
+This may break some debuggers.
+.Qc
+.Pp
+.Ss  Labels
+A
+.Em label
+is written as a symbol immediately followed by a colon
+.Li : .
+The symbol then represents the current value of the active location counter,
+and is, for example, a suitable instruction operand. You are warned if you
+use the same symbol to represent two different locations: the first definition
+overrides any other definitions.
+.Pp
+.Ss  Giving Symbols Other Values
+A symbol can be given an arbitrary value by writing a symbol, followed by
+an equals sign
+.Li = ,
+followed by an expression (see Section
+.Dq Expressions ) .
+This is equivalent to using the
+.Li .set
+directive.See Section
+.Dq Set .
+In the same way, using a double equals sign
+.Li =
+.Li =
+here represents an equivalent of the
+.Li .eqv
+directive.See Section
+.Dq Eqv .
+.Pp
+.Ss  Symbol Names
+Symbol names begin with a letter or with one of
+.Li ._ .
+On most machines, you can also use
+.Li $
+in symbol names; exceptions are noted in Machine Dependencies. That character
+may be followed by any string of digits, letters, dollar signs (unless otherwise
+noted for a particular target machine), and underscores.
+.Pp
+Case of letters is significant:
+.Li foo
+is a different symbol name than
+.Li Foo .
+.Pp
+Each symbol has exactly one name. Each name in an assembly language program
+refers to exactly one symbol. You may use that symbol name any number of times
+in a program.
+.Pp
+.Em  Local Symbol Names
+.Pp
+A local symbol is any symbol beginning with certain local label prefixes.
+By default, the local label prefix is
+.Li .L
+for ELF systems or
+.Li L
+for traditional a.out systems, but each target may have its own set of local
+label prefixes.
+.Pp
+Local symbols are defined and used within the assembler, but they are normally
+not saved in object files. Thus, they are not visible when debugging. You
+may use the
+.Li -L
+option (see Section
+.Dq L )
+to retain the local symbols in the object files.
+.Pp
+.Em  Local Labels
+.Pp
+Local labels help compilers and programmers use names temporarily. They create
+symbols which are guaranteed to be unique over the entire scope of the input
+source code and which can be referred to by a simple notation. To define a
+local label, write a label of the form
+.Li  Sy N:
+(where
+.Sy N
+represents any positive integer). To refer to the most recent previous definition
+of that label write
+.Li  Sy Nb ,
+using the same number as when you defined the label. To refer to the next
+definition of a local label, write
+.Li  Sy Nf
+---the
+.Li b
+stands for \(lqbackwards\(rq and the
+.Li f
+stands for \(lqforwards\(rq.
+.Pp
+There is no restriction on how you can use these labels, and you can reuse
+them too. So that it is possible to repeatedly define the same local label
+(using the same number
+.Li  Sy N ) ,
+although you can only refer to the most recently defined local label of that
+number (for a backwards reference) or the next definition of a specific local
+label for a forward reference. It is also worth noting that the first 10 local
+labels (
+.Li  Sy 0:
+\&....Li  Sy 9: )
+are implemented in a slightly more efficient manner than the others.
+.Pp
+Here is an example:
+.Pp
+.Bd -literal -offset indent
+1:        branch 1f
+2:        branch 1b
+1:        branch 2f
+2:        branch 1b
+.Ed
+.Pp
+Which is the equivalent of:
+.Pp
+.Bd -literal -offset indent
+label_1:  branch label_3
+label_2:  branch label_1
+label_3:  branch label_4
+label_4:  branch label_3
+.Ed
+.Pp
+Local label names are only a notational device. They are immediately transformed
+into more conventional symbol names before the assembler uses them. The symbol
+names are stored in the symbol table, appear in error messages, and are optionally
+emitted to the object file. The names are constructed using these parts:
+.Pp
+.Bl -tag -width Ds
+.It  Em local label prefix
+All local symbols begin with the system-specific local label prefix. Normally
+both
+.Xr as
+and
+.Li ld
+forget symbols that start with the local label prefix. These labels are used
+for symbols you are never intended to see. If you use the
+.Li -L
+option then
+.Xr as
+retains these symbols in the object file. If you also instruct
+.Li ld
+to retain these symbols, you may use them in debugging.
+.Pp
+.It  Va number
+This is the number that was used in the local label definition. So if the
+label is written
+.Li 55:
+then the number is
+.Li 55 .
+.Pp
+.It  Li C-B
+This unusual character is included so you do not accidentally invent a symbol
+of the same name. The character has ASCII value of
+.Li \e002
+(control-B).
+.Pp
+.It  Em ordinal number
+This is a serial number to keep the labels distinct. The first definition
+of
+.Li 0:
+gets the number
+.Li 1 .
+The 15th definition of
+.Li 0:
+gets the number
+.Li 15 ,
+and so on. Likewise the first definition of
+.Li 1:
+gets the number
+.Li 1
+and its 15th definition gets
+.Li 15
+as well.
+.El
+.Pp
+So for example, the first
+.Li 1:
+may be named
+.Li .L1 Li C-B1 ,
+and the 44th
+.Li 3:
+may be named
+.Li .L3 Li C-B44 .
+.Pp
+.Em  Dollar Local Labels
+.Pp
+.Li as
+also supports an even more local form of local labels called dollar labels.
+These labels go out of scope (i.e., they become undefined) as soon as a non-local
+label is defined. Thus they remain valid for only a small region of the input
+source code. Normal local labels, by contrast, remain in scope for the entire
+file, or until they are redefined by another occurrence of the same local
+label.
+.Pp
+Dollar labels are defined in exactly the same way as ordinary local labels,
+except that instead of being terminated by a colon, they are terminated by
+a dollar sign, e.g.,
+.Li  Sy 55$ .
+.Pp
+They can also be distinguished from ordinary local labels by their transformed
+names which use ASCII character
+.Li \e001
+(control-A) as the magic character to distinguish them from ordinary labels.
+For example, the fifth definition of
+.Li 6$
+may be named
+.Li .L6 Li C-A5 .
+.Pp
+.Ss  The Special Dot Symbol
+The special symbol
+.Li .
+refers to the current address that
+.Xr as
+is assembling into. Thus, the expression
+.Li melvin: .long .
+defines
+.Li melvin
+to contain its own address. Assigning a value to
+.Li .
+is treated the same as a
+.Li .org
+directive. Thus, the expression
+.Li .=.+4
+is the same as saying
+.Li .space 4 .
+.Pp
+.Ss  Symbol Attributes
+Every symbol has, as well as its name, the attributes \(lqValue\(rq and \(lqType\(rq. Depending
+on output format, symbols can also have auxiliary attributes. The detailed
+definitions are in
+.Pa a.out.h .
+.Pp
+If you use a symbol without defining it,
+.Xr as
+assumes zero for all these attributes, and probably won't warn you. This makes
+the symbol an externally defined symbol, which is generally what you would
+want.
+.Pp
+.Em  Value
+.Pp
+The value of a symbol is (usually) 32 bits. For a symbol which labels a location
+in the text, data, bss or absolute sections the value is the number of addresses
+from the start of that section to the label. Naturally for text, data and
+bss sections the value of a symbol changes as
+.Li ld
+changes section base addresses during linking. Absolute symbols' values do
+not change during linking: that is why they are called absolute.
+.Pp
+The value of an undefined symbol is treated in a special way. If it is 0 then
+the symbol is not defined in this assembler source file, and
+.Li ld
+tries to determine its value from other files linked into the same program.
+You make this kind of symbol simply by mentioning a symbol name without defining
+it. A non-zero value represents a
+.Li .comm
+common declaration. The value is how much common storage to reserve, in bytes
+(addresses). The symbol refers to the first address of the allocated storage.
+.Pp
+.Em  Type
+.Pp
+The type attribute of a symbol contains relocation (section) information,
+any flag settings indicating that a symbol is external, and (optionally),
+other information for linkers and debuggers. The exact format depends on the
+object-code output format in use.
+.Pp
+.Sh  Expressions
+An
+.Em expression
+specifies an address or numeric value. Whitespace may precede and/or follow
+an expression.
+.Pp
+The result of an expression must be an absolute number, or else an offset
+into a particular section. If an expression is not absolute, and there is
+not enough information when
+.Xr as
+sees the expression to know its section, a second pass over the source program
+might be necessary to interpret the expression---but the second pass is currently
+not implemented.
+.Xr as
+aborts with an error message in this situation.
+.Pp
+.Ss  Empty Expressions
+An empty expression has no value: it is just whitespace or null. Wherever
+an absolute expression is required, you may omit the expression, and
+.Xr as
+assumes a value of (absolute) 0. This is compatible with other assemblers.
+.Pp
+.Ss  Integer Expressions
+An
+.Em integer expression
+is one or more
+.Em arguments
+delimited by
+.Em operators .
+.Pp
+.Em  Arguments
+.Pp
+.Em Arguments
+are symbols, numbers or subexpressions. In other contexts arguments are sometimes
+called \(lqarithmetic operands\(rq. In this manual, to avoid confusing them with the
+\(lqinstruction operands\(rq of the machine language, we use the term \(lqargument\(rq to
+refer to parts of expressions only, reserving the word \(lqoperand\(rq to refer only
+to machine instruction operands.
+.Pp
+Symbols are evaluated to yield {
+.Va section
+.Va NNN
+}where
+.Va section
+is one of text, data, bss, absolute, or undefined.
+.Va NNN
+is a signed, 2's complement 32 bit integer.
+.Pp
+Numbers are usually integers.
+.Pp
+A number can be a flonum or biGNUm. In this case, you are warned that only
+the low order 32 bits are used, and
+.Xr as
+pretends these 32 bits are an integer. You may write integer-manipulating
+instructions that act on exotic constants, compatible with other assemblers.
+.Pp
+Subexpressions are a left parenthesis
+.Li (
+followed by an integer expression, followed by a right parenthesis
+.Li ) ;
+or a prefix operator followed by an argument.
+.Pp
+.Em  Operators
+.Pp
+.Em Operators
+are arithmetic functions, like
+.Li +
+or
+.Li % .
+Prefix operators are followed by an argument. Infix operators appear between
+their arguments. Operators may be preceded and/or followed by whitespace.
+.Pp
+.Em  Prefix Operator
+.Pp
+.Xr as
+has the following
+.Em prefix operators .
+They each take one argument, which must be absolute.
+.Pp
+.Bl -tag -width Ds
+.It  -
+.Em Negation .
+Two's complement negation.
+.It  ~
+.Em Complementation .
+Bitwise not.
+.El
+.Pp
+.Em  Infix Operators
+.Pp
+.Em Infix operators
+take two arguments, one on either side. Operators have precedence, but operations
+with equal precedence are performed left to right. Apart from
+.Li +
+or
+.Op - ,
+both arguments must be absolute, and the result is absolute.
+.Pp
+.Bl -enum
+.It
+Highest Precedence
+.Pp
+.Bl -tag -width Ds
+.It  *
+.Em Multiplication .
+.Pp
+.It  /
+.Em Division .
+Truncation is the same as the C operator
+.Li /
+.Pp
+.It  %
+.Em Remainder .
+.Pp
+.It  <<
+.Em Shift Left .
+Same as the C operator
+.Li << .
+.Pp
+.It  >>
+.Em Shift Right .
+Same as the C operator
+.Li >> .
+.El
+.Pp
+.It
+Intermediate precedence
+.Pp
+.Bl -tag -width Ds
+.It  |
+.Pp
+.Em Bitwise Inclusive Or .
+.Pp
+.It  &
+.Em Bitwise And .
+.Pp
+.It  ^
+.Em Bitwise Exclusive Or .
+.Pp
+.It  !
+.Em Bitwise Or Not .
+.El
+.Pp
+.It
+Low Precedence
+.Pp
+.Bl -tag -width Ds
+.It  +
+.Em Addition .
+If either argument is absolute, the result has the section of the other argument.
+You may not add together arguments from different sections.
+.Pp
+.It  -
+.Em Subtraction .
+If the right argument is absolute, the result has the section of the left
+argument. If both arguments are in the same section, the result is absolute.
+You may not subtract arguments from different sections.
+.Pp
+.It  ==
+.Em Is Equal To
+.It  <>
+.It  !=
+.Em Is Not Equal To
+.It  <
+.Em Is Less Than
+.It  >
+.Em Is Greater Than
+.It  >=
+.Em Is Greater Than Or Equal To
+.It  <=
+.Em Is Less Than Or Equal To
+.Pp
+The comparison operators can be used as infix operators. A true results has
+a value of -1 whereas a false result has a value of 0. Note, these operators
+perform signed comparisons.
+.El
+.Pp
+.It
+Lowest Precedence
+.Pp
+.Bl -tag -width Ds
+.It  &&
+.Em Logical And .
+.Pp
+.It  ||
+.Em Logical Or .
+.Pp
+These two logical operations can be used to combine the results of sub expressions.
+Note, unlike the comparison operators a true result returns a value of 1 but
+a false results does still return 0. Also note that the logical or operator
+has a slightly lower precedence than logical and.
+.Pp
+.El
+.El
+In short, it's only meaningful to add or subtract the
+.Em offsets
+in an address; you can only have a defined section in one of the two arguments.
+.Pp
+.Sh  Assembler Directives
+All assembler directives have names that begin with a period (
+.Li . ) .
+The rest of the name is letters, usually in lower case.
+.Pp
+This chapter discusses directives that are available regardless of the target
+machine configuration for the GNU assembler.
+.Pp
+.Ss  Li .abort
+This directive stops the assembly immediately. It is for compatibility with
+other assemblers. The original idea was that the assembly language source
+would be piped into the assembler. If the sender of the source quit, it could
+use this directive tells
+.Xr as
+to quit also. One day
+.Li .abort
+will not be supported.
+.Pp
+.Ss  Li .align Va abs-expr, Va abs-expr, Va abs-expr
+Pad the location counter (in the current subsection) to a particular storage
+boundary. The first expression (which must be absolute) is the alignment required,
+as described below.
+.Pp
+The second expression (also absolute) gives the fill value to be stored in
+the padding bytes. It (and the comma) may be omitted. If it is omitted, the
+padding bytes are normally zero. However, on some systems, if the section
+is marked as containing code and the fill value is omitted, the space is filled
+with no-op instructions.
+.Pp
+The third expression is also absolute, and is also optional. If it is present,
+it is the maximum number of bytes that should be skipped by this alignment
+directive. If doing the alignment would require skipping more bytes than the
+specified maximum, then the alignment is not done at all. You can omit the
+fill value (the second argument) entirely by simply using two commas after
+the required alignment; this can be useful if you want the alignment to be
+filled with no-op instructions when appropriate.
+.Pp
+The way the required alignment is specified varies from system to system.
+For the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, s390, sparc,
+tic4x, tic80 and xtensa, the first expression is the alignment request in
+bytes. For example
+.Li .align 8
+advances the location counter until it is a multiple of 8. If the location
+counter is already a multiple of 8, no change is needed. For the tic54x, the
+first expression is the alignment request in words.
+.Pp
+For other systems, including the i386 using a.out format, and the arm and
+strongarm, it is the number of low-order zero bits the location counter must
+have after advancement. For example
+.Li .align 3
+advances the location counter until it a multiple of 8. If the location counter
+is already a multiple of 8, no change is needed.
+.Pp
+This inconsistency is due to the different behaviors of the various native
+assemblers for these systems which GAS must emulate. GAS also provides
+.Li .balign
+and
+.Li .p2align
+directives, described later, which have a consistent behavior across all architectures
+(but are specific to GAS).
+.Pp
+.Ss  Li .ascii " Va string"...
+.Li .ascii
+expects zero or more string literals (see Section
+.Dq Strings )
+separated by commas. It assembles each string (with no automatic trailing
+zero byte) into consecutive addresses.
+.Pp
+.Ss  Li .asciz " Va string"...
+.Li .asciz
+is just like
+.Li .ascii ,
+but each string is followed by a zero byte. The \(lqz\(rq in
+.Li .asciz
+stands for \(lqzero\(rq.
+.Pp
+.Ss  Li .balign[wl] Va abs-expr, Va abs-expr, Va abs-expr
+Pad the location counter (in the current subsection) to a particular storage
+boundary. The first expression (which must be absolute) is the alignment request
+in bytes. For example
+.Li .balign 8
+advances the location counter until it is a multiple of 8. If the location
+counter is already a multiple of 8, no change is needed.
+.Pp
+The second expression (also absolute) gives the fill value to be stored in
+the padding bytes. It (and the comma) may be omitted. If it is omitted, the
+padding bytes are normally zero. However, on some systems, if the section
+is marked as containing code and the fill value is omitted, the space is filled
+with no-op instructions.
+.Pp
+The third expression is also absolute, and is also optional. If it is present,
+it is the maximum number of bytes that should be skipped by this alignment
+directive. If doing the alignment would require skipping more bytes than the
+specified maximum, then the alignment is not done at all. You can omit the
+fill value (the second argument) entirely by simply using two commas after
+the required alignment; this can be useful if you want the alignment to be
+filled with no-op instructions when appropriate.
+.Pp
+The
+.Li .balignw
+and
+.Li .balignl
+directives are variants of the
+.Li .balign
+directive. The
+.Li .balignw
+directive treats the fill pattern as a two byte word value. The
+.Li .balignl
+directives treats the fill pattern as a four byte longword value. For example,
+.Li .balignw 4,0x368d
+will align to a multiple of 4. If it skips two bytes, they will be filled
+in with the value 0x368d (the exact placement of the bytes depends upon the
+endianness of the processor). If it skips 1 or 3 bytes, the fill value is
+undefined.
+.Pp
+.Ss  Li .byte Va expressions
+.Li .byte
+expects zero or more expressions, separated by commas. Each expression is
+assembled into the next byte.
+.Pp
+.Ss  Li .comm Va symbol , Va length
+.Li .comm
+declares a common symbol named
+.Va symbol .
+When linking, a common symbol in one object file may be merged with a defined
+or common symbol of the same name in another object file. If
+.Li ld
+does not see a definition for the symbol--just one or more common symbols--then
+it will allocate
+.Va length
+bytes of uninitialized memory.
+.Va length
+must be an absolute expression. If
+.Li ld
+sees multiple common symbols with the same name, and they do not all have
+the same size, it will allocate space using the largest size.
+.Pp
+When using ELF, the
+.Li .comm
+directive takes an optional third argument. This is the desired alignment
+of the symbol, specified as a byte boundary (for example, an alignment of
+16 means that the least significant 4 bits of the address should be zero).
+The alignment must be an absolute expression, and it must be a power of two.
+If
+.Li ld
+allocates uninitialized memory for the common symbol, it will use the alignment
+when placing the symbol. If no alignment is specified,
+.Xr as
+will set the alignment to the largest power of two less than or equal to the
+size of the symbol, up to a maximum of 16.
+.Pp
+.Ss  Li .cfi_startproc [simple]
+.Li .cfi_startproc
+is used at the beginning of each function that should have an entry in
+.Li .eh_frame .
+It initializes some internal data structures. Don't forget to close the function
+by
+.Li .cfi_endproc .
+.Pp
+Unless
+.Li .cfi_startproc
+is used along with parameter
+.Li simple
+it also emits some architecture dependent initial CFI instructions.
+.Ss  Li .cfi_endproc
+.Li .cfi_endproc
+is used at the end of a function where it closes its unwind entry previously
+opened by
+.Li .cfi_startproc ,
+and emits it to
+.Li .eh_frame .
+.Pp
+.Ss  Li .cfi_personality Va encoding [, Va exp]
+.Li .cfi_personality
+defines personality routine and its encoding.
+.Va encoding
+must be a constant determining how the personality should be encoded. If it
+is 255 (
+.Li DW_EH_PE_omit ) ,
+second argument is not present, otherwise second argument should be a constant
+or a symbol name. When using indirect encodings, the symbol provided should
+be the location where personality can be loaded from, not the personality
+routine itself. The default after
+.Li .cfi_startproc
+is
+.Li .cfi_personality 0xff ,
+no personality routine.
+.Pp
+.Ss  Li .cfi_lsda Va encoding [, Va exp]
+.Li .cfi_lsda
+defines LSDA and its encoding.
+.Va encoding
+must be a constant determining how the LSDA should be encoded. If it is 255
+(
+.Li DW_EH_PE_omit ) ,
+second argument is not present, otherwise second argument should be a constant
+or a symbol name. The default after
+.Li .cfi_startproc
+is
+.Li .cfi_lsda 0xff ,
+no LSDA.
+.Pp
+.Ss  Li .cfi_def_cfa Va register, Va offset
+.Li .cfi_def_cfa
+defines a rule for computing CFA as:
+.Em take address from Va register and add Va offset to it .
+.Pp
+.Ss  Li .cfi_def_cfa_register Va register
+.Li .cfi_def_cfa_register
+modifies a rule for computing CFA. From now on
+.Va register
+will be used instead of the old one. Offset remains the same.
+.Pp
+.Ss  Li .cfi_def_cfa_offset Va offset
+.Li .cfi_def_cfa_offset
+modifies a rule for computing CFA. Register remains the same, but
+.Va offset
+is new. Note that it is the absolute offset that will be added to a defined
+register to compute CFA address.
+.Pp
+.Ss  Li .cfi_adjust_cfa_offset Va offset
+Same as
+.Li .cfi_def_cfa_offset
+but
+.Va offset
+is a relative value that is added/substracted from the previous offset.
+.Pp
+.Ss  Li .cfi_offset Va register, Va offset
+Previous value of
+.Va register
+is saved at offset
+.Va offset
+from CFA.
+.Pp
+.Ss  Li .cfi_rel_offset Va register, Va offset
+Previous value of
+.Va register
+is saved at offset
+.Va offset
+from the current CFA register. This is transformed to
+.Li .cfi_offset
+using the known displacement of the CFA register from the CFA. This is often
+easier to use, because the number will match the code it's annotating.
+.Pp
+.Ss  Li .cfi_register Va register1, Va register2
+Previous value of
+.Va register1
+is saved in register
+.Va register2 .
+.Pp
+.Ss  Li .cfi_restore Va register
+.Li .cfi_restore
+says that the rule for
+.Va register
+is now the same as it was at the beginning of the function, after all initial
+instruction added by
+.Li .cfi_startproc
+were executed.
+.Pp
+.Ss  Li .cfi_undefined Va register
+From now on the previous value of
+.Va register
+can't be restored anymore.
+.Pp
+.Ss  Li .cfi_same_value Va register
+Current value of
+.Va register
+is the same like in the previous frame, i.e. no restoration needed.
+.Pp
+.Ss  Li .cfi_remember_state, 
+First save all current rules for all registers by
+.Li .cfi_remember_state ,
+then totally screw them up by subsequent
+.Li .cfi_*
+directives and when everything is hopelessly bad, use
+.Li .cfi_restore_state
+to restore the previous saved state.
+.Pp
+.Ss  Li .cfi_return_column Va register
+Change return column
+.Va register ,
+i.e. the return address is either directly in
+.Va register
+or can be accessed by rules for
+.Va register .
+.Pp
+.Ss  Li .cfi_signal_frame
+Mark current function as signal trampoline.
+.Pp
+.Ss  Li .cfi_window_save
+SPARC register window has been saved.
+.Pp
+.Ss  Li .cfi_escape Va expression[, ...]
+Allows the user to add arbitrary bytes to the unwind info. One might use this
+to add OS-specific CFI opcodes, or generic CFI opcodes that GAS does not yet
+support.
+.Pp
+.Ss  Li .file Va fileno Va filename
+When emitting dwarf2 line number information
+.Li .file
+assigns filenames to the
+.Li .debug_line
+file name table. The
+.Va fileno
+operand should be a unique positive integer to use as the index of the entry
+in the table. The
+.Va filename
+operand is a C string literal.
+.Pp
+The detail of filename indices is exposed to the user because the filename
+table is shared with the
+.Li .debug_info
+section of the dwarf2 debugging information, and thus the user must know the
+exact indices that table entries will have.
+.Pp
+.Ss  Li .loc Va fileno Va lineno [ Va column] [ Va options]
+The
+.Li .loc
+directive will add row to the
+.Li .debug_line
+line number matrix corresponding to the immediately following assembly instruction.
+The
+.Va fileno ,
+.Va lineno ,
+and optional
+.Va column
+arguments will be applied to the
+.Li .debug_line
+state machine before the row is added.
+.Pp
+The
+.Va options
+are a sequence of the following tokens in any order:
+.Pp
+.Bl -tag -width Ds
+.It  basic_block
+This option will set the
+.Li basic_block
+register in the
+.Li .debug_line
+state machine to
+.Li true .
+.Pp
+.It  prologue_end
+This option will set the
+.Li prologue_end
+register in the
+.Li .debug_line
+state machine to
+.Li true .
+.Pp
+.It  epilogue_begin
+This option will set the
+.Li epilogue_begin
+register in the
+.Li .debug_line
+state machine to
+.Li true .
+.Pp
+.It  is_stmt Va value
+This option will set the
+.Li is_stmt
+register in the
+.Li .debug_line
+state machine to
+.Li value ,
+which must be either 0 or 1.
+.Pp
+.It  isa Va value
+This directive will set the
+.Li isa
+register in the
+.Li .debug_line
+state machine to
+.Va value ,
+which must be an unsigned integer.
+.Pp
+.El
+.Ss  Li .loc_mark_blocks Va enable
+The
+.Li .loc_mark_blocks
+directive makes the assembler emit an entry to the
+.Li .debug_line
+line number matrix with the
+.Li basic_block
+register in the state machine set whenever a code label is seen. The
+.Va enable
+argument should be either 1 or 0, to enable or disable this function respectively.
+.Pp
+.Ss  Li .data Va subsection
+.Li .data
+tells
+.Xr as
+to assemble the following statements onto the end of the data subsection numbered
+.Va subsection
+(which is an absolute expression). If
+.Va subsection
+is omitted, it defaults to zero.
+.Pp
+.Ss  Li .double Va flonums
+.Li .double
+expects zero or more flonums, separated by commas. It assembles floating point
+numbers.
+.Pp
+.Ss  Li .eject
+Force a page break at this point, when generating assembly listings.
+.Pp
+.Ss  Li .else
+.Li .else
+is part of the
+.Xr as
+support for conditional assembly; see If,,
+.Li .if
+\&. It marks the beginning of a section of code to be assembled if the condition
+for the preceding
+.Li .if
+was false.
+.Pp
+.Ss  Li .elseif
+.Li .elseif
+is part of the
+.Xr as
+support for conditional assembly; see If,,
+.Li .if
+\&. It is shorthand for beginning a new
+.Li .if
+block that would otherwise fill the entire
+.Li .else
+section.
+.Pp
+.Ss  Li .end
+.Li .end
+marks the end of the assembly file.
+.Xr as
+does not process anything in the file past the
+.Li .end
+directive.
+.Pp
+.Ss  Li .endfunc
+.Li .endfunc
+marks the end of a function specified with
+.Li .func .
+.Pp
+.Ss  Li .endif
+.Li .endif
+is part of the
+.Xr as
+support for conditional assembly; it marks the end of a block of code that
+is only assembled conditionally.See Section
+.Dq If .
+.Pp
+.Ss  Li .equ Va symbol, Va expression
+This directive sets the value of
+.Va symbol
+to
+.Va expression .
+It is synonymous with
+.Li .set ;
+see Set,,
+.Li .set
+\&.
+.Pp
+.Ss  Li .equiv Va symbol, Va expression
+The
+.Li .equiv
+directive is like
+.Li .equ
+and
+.Li .set ,
+except that the assembler will signal an error if
+.Va symbol
+is already defined. Note a symbol which has been referenced but not actually
+defined is considered to be undefined.
+.Pp
+Except for the contents of the error message, this is roughly equivalent to
+.Bd -literal -offset indent
+\&.ifdef SYM
+\&.err
+\&.endif
+\&.equ SYM,VAL
+.Ed
+plus it protects the symbol from later redefinition.
+.Pp
+.Ss  Li .eqv Va symbol, Va expression
+The
+.Li .eqv
+directive is like
+.Li .equiv ,
+but no attempt is made to evaluate the expression or any part of it immediately.
+Instead each time the resulting symbol is used in an expression, a snapshot
+of its current value is taken.
+.Pp
+.Ss  Li .err
+If
+.Xr as
+assembles a
+.Li .err
+directive, it will print an error message and, unless the
+.Op -Z
+option was used, it will not generate an object file. This can be used to
+signal an error in conditionally compiled code.
+.Pp
+.Ss  Li .error " Va string"
+Similarly to
+.Li .err ,
+this directive emits an error, but you can specify a string that will be emitted
+as the error message. If you don't specify the message, it defaults to
+.Li ".error directive invoked in source file" .
+See Section.Dq Errors .
+.Pp
+.Bd -literal -offset indent
+ .error "This code has not been assembled and tested."
+.Ed
+.Pp
+.Ss  Li .exitm
+Exit early from the current macro definition.See Section
+.Dq Macro .
+.Pp
+.Ss  Li .extern
+.Li .extern
+is accepted in the source program---for compatibility with other assemblers---but
+it is ignored.
+.Xr as
+treats all undefined symbols as external.
+.Pp
+.Ss  Li .fail Va expression
+Generates an error or a warning. If the value of the
+.Va expression
+is 500 or more,
+.Xr as
+will print a warning message. If the value is less than 500,
+.Xr as
+will print an error message. The message will include the value of
+.Va expression .
+This can occasionally be useful inside complex nested macros or conditional
+assembly.
+.Pp
+.Ss  Li .file Va string
+.Li .file
+tells
+.Xr as
+that we are about to start a new logical file.
+.Va string
+is the new file name. In general, the filename is recognized whether or not
+it is surrounded by quotes
+.Li " ;
+but if you wish to specify an empty file name, you must give the quotes--
+.Li "" .
+This statement may go away in future: it is only recognized to be compatible
+with old
+.Xr as
+programs.
+.Pp
+.Ss  Li .fill Va repeat , Va size , Va value
+.Va repeat ,
+.Va size
+and
+.Va value
+are absolute expressions. This emits
+.Va repeat
+copies of
+.Va size
+bytes.
+.Va Repeat
+may be zero or more.
+.Va Size
+may be zero or more, but if it is more than 8, then it is deemed to have the
+value 8, compatible with other people's assemblers. The contents of each
+.Va repeat
+bytes is taken from an 8-byte number. The highest order 4 bytes are zero.
+The lowest order 4 bytes are
+.Va value
+rendered in the byte-order of an integer on the computer
+.Xr as
+is assembling for. Each
+.Va size
+bytes in a repetition is taken from the lowest order
+.Va size
+bytes of this number. Again, this bizarre behavior is compatible with other
+people's assemblers.
+.Pp
+.Va size
+and
+.Va value
+are optional. If the second comma and
+.Va value
+are absent,
+.Va value
+is assumed zero. If the first comma and following tokens are absent,
+.Va size
+is assumed to be 1.
+.Pp
+.Ss  Li .float Va flonums
+This directive assembles zero or more flonums, separated by commas. It has
+the same effect as
+.Li .single .
+.Pp
+.Ss  Li .func Va name[, Va label]
+.Li .func
+emits debugging information to denote function
+.Va name ,
+and is ignored unless the file is assembled with debugging enabled. Only
+.Li --gstabs[+]
+is currently supported.
+.Va label
+is the entry point of the function and if omitted
+.Va name
+prepended with the
+.Li leading char
+is used.
+.Li leading char
+is usually
+.Li _
+or nothing, depending on the target. All functions are currently defined to
+have
+.Li void
+return type. The function must be terminated with
+.Li .endfunc .
+.Pp
+.Ss  Li .global Va symbol, Li .globl Va symbol
+.Li .global
+makes the symbol visible to
+.Li ld .
+If you define
+.Va symbol
+in your partial program, its value is made available to other partial programs
+that are linked with it. Otherwise,
+.Va symbol
+takes its attributes from a symbol of the same name from another file linked
+into the same program.
+.Pp
+Both spellings (
+.Li .globl
+and
+.Li .global )
+are accepted, for compatibility with other assemblers.
+.Pp
+.Ss  Li .hidden Va names
+This is one of the ELF visibility directives. The other two are
+.Li .internal
+(see Section
+.Dq Internal )
+and
+.Li .protected
+(see Section
+.Dq Protected ) .
+.Pp
+This directive overrides the named symbols default visibility (which is set
+by their binding: local, global or weak). The directive sets the visibility
+to
+.Li hidden
+which means that the symbols are not visible to other components. Such symbols
+are always considered to be
+.Li protected
+as well.
+.Pp
+.Ss  Li .hword Va expressions
+This expects zero or more
+.Va expressions ,
+and emits a 16 bit number for each.
+.Pp
+This directive is a synonym for
+.Li .short .
+.Pp
+.Ss  Li .ident
+This directive is used by some assemblers to place tags in object files. The
+behavior of this directive varies depending on the target. When using the
+a.out object file format,
+.Xr as
+simply accepts the directive for source-file compatibility with existing assemblers,
+but does not emit anything for it. When using COFF, comments are emitted to
+the
+.Li .comment
+or
+.Li .rdata
+section, depending on the target. When using ELF, comments are emitted to
+the
+.Li .comment
+section.
+.Pp
+.Ss  Li .if Va absolute expression
+.Li .if
+marks the beginning of a section of code which is only considered part of
+the source program being assembled if the argument (which must be an
+.Va absolute expression )
+is non-zero. The end of the conditional section of code must be marked by
+.Li .endif
+(see Section
+.Dq Endif ) ;
+optionally, you may include code for the alternative condition, flagged by
+.Li .else
+(see Section
+.Dq Else ) .
+If you have several conditions to check,
+.Li .elseif
+may be used to avoid nesting blocks if/else within each subsequent
+.Li .else
+block.
+.Pp
+The following variants of
+.Li .if
+are also supported:
+.Bl -tag -width Ds
+.It  .ifdef Va symbol
+Assembles the following section of code if the specified
+.Va symbol
+has been defined. Note a symbol which has been referenced but not yet defined
+is considered to be undefined.
+.Pp
+.It  .ifb Va text
+Assembles the following section of code if the operand is blank (empty).
+.Pp
+.It  .ifc Va string1, Va string2
+Assembles the following section of code if the two strings are the same. The
+strings may be optionally quoted with single quotes. If they are not quoted,
+the first string stops at the first comma, and the second string stops at
+the end of the line. Strings which contain whitespace should be quoted. The
+string comparison is case sensitive.
+.Pp
+.It  .ifeq Va absolute expression
+Assembles the following section of code if the argument is zero.
+.Pp
+.It  .ifeqs Va string1, Va string2
+Another form of
+.Li .ifc .
+The strings must be quoted using double quotes.
+.Pp
+.It  .ifge Va absolute expression
+Assembles the following section of code if the argument is greater than or
+equal to zero.
+.Pp
+.It  .ifgt Va absolute expression
+Assembles the following section of code if the argument is greater than zero.
+.Pp
+.It  .ifle Va absolute expression
+Assembles the following section of code if the argument is less than or equal
+to zero.
+.Pp
+.It  .iflt Va absolute expression
+Assembles the following section of code if the argument is less than zero.
+.Pp
+.It  .ifnb Va text
+Like
+.Li .ifb ,
+but the sense of the test is reversed: this assembles the following section
+of code if the operand is non-blank (non-empty).
+.Pp
+.It  .ifnc Va string1, Va string2.
+Like
+.Li .ifc ,
+but the sense of the test is reversed: this assembles the following section
+of code if the two strings are not the same.
+.Pp
+.It  .ifndef Va symbol
+.It  .ifnotdef Va symbol
+Assembles the following section of code if the specified
+.Va symbol
+has not been defined. Both spelling variants are equivalent. Note a symbol
+which has been referenced but not yet defined is considered to be undefined.
+.Pp
+.It  .ifne Va absolute expression
+Assembles the following section of code if the argument is not equal to zero
+(in other words, this is equivalent to
+.Li .if ) .
+.Pp
+.It  .ifnes Va string1, Va string2
+Like
+.Li .ifeqs ,
+but the sense of the test is reversed: this assembles the following section
+of code if the two strings are not the same.
+.El
+.Pp
+.Ss  Li .incbin " Va file"[, Va skip[, Va count]]
+The
+.Li incbin
+directive includes
+.Va file
+verbatim at the current location. You can control the search paths used with
+the
+.Li -I
+command-line option (see Section
+.Dq Invoking ) .
+Quotation marks are required around
+.Va file .
+.Pp
+The
+.Va skip
+argument skips a number of bytes from the start of the
+.Va file .
+The
+.Va count
+argument indicates the maximum number of bytes to read. Note that the data
+is not aligned in any way, so it is the user's responsibility to make sure
+that proper alignment is provided both before and after the
+.Li incbin
+directive.
+.Pp
+.Ss  Li .include " Va file"
+This directive provides a way to include supporting files at specified points
+in your source program. The code from
+.Va file
+is assembled as if it followed the point of the
+.Li .include ;
+when the end of the included file is reached, assembly of the original file
+continues. You can control the search paths used with the
+.Li -I
+command-line option (see Section
+.Dq Invoking ) .
+Quotation marks are required around
+.Va file .
+.Pp
+.Ss  Li .int Va expressions
+Expect zero or more
+.Va expressions ,
+of any section, separated by commas. For each expression, emit a number that,
+at run time, is the value of that expression. The byte order and bit size
+of the number depends on what kind of target the assembly is for.
+.Pp
+.Ss  Li .internal Va names
+This is one of the ELF visibility directives. The other two are
+.Li .hidden
+(see Section
+.Dq Hidden )
+and
+.Li .protected
+(see Section
+.Dq Protected ) .
+.Pp
+This directive overrides the named symbols default visibility (which is set
+by their binding: local, global or weak). The directive sets the visibility
+to
+.Li internal
+which means that the symbols are considered to be
+.Li hidden
+(i.e., not visible to other components), and that some extra, processor specific
+processing must also be performed upon the symbols as well.
+.Pp
+.Ss  Li .irp Va symbol, Va values...
+Evaluate a sequence of statements assigning different values to
+.Va symbol .
+The sequence of statements starts at the
+.Li .irp
+directive, and is terminated by an
+.Li .endr
+directive. For each
+.Va value ,
+.Va symbol
+is set to
+.Va value ,
+and the sequence of statements is assembled. If no
+.Va value
+is listed, the sequence of statements is assembled once, with
+.Va symbol
+set to the null string. To refer to
+.Va symbol
+within the sequence of statements, use
+.Va \esymbol .
+.Pp
+For example, assembling
+.Pp
+.Bd -literal -offset indent
+        .irp    param,1,2,3
+        move    d\eparam,sp@-
+        .endr
+.Ed
+.Pp
+is equivalent to assembling
+.Pp
+.Bd -literal -offset indent
+        move    d1,sp@-
+        move    d2,sp@-
+        move    d3,sp@-
+.Ed
+.Pp
+For some caveats with the spelling of
+.Va symbol ,
+see also Macro.
+.Pp
+.Ss  Li .irpc Va symbol, Va values...
+Evaluate a sequence of statements assigning different values to
+.Va symbol .
+The sequence of statements starts at the
+.Li .irpc
+directive, and is terminated by an
+.Li .endr
+directive. For each character in
+.Va value ,
+.Va symbol
+is set to the character, and the sequence of statements is assembled. If no
+.Va value
+is listed, the sequence of statements is assembled once, with
+.Va symbol
+set to the null string. To refer to
+.Va symbol
+within the sequence of statements, use
+.Va \esymbol .
+.Pp
+For example, assembling
+.Pp
+.Bd -literal -offset indent
+        .irpc    param,123
+        move    d\eparam,sp@-
+        .endr
+.Ed
+.Pp
+is equivalent to assembling
+.Pp
+.Bd -literal -offset indent
+        move    d1,sp@-
+        move    d2,sp@-
+        move    d3,sp@-
+.Ed
+.Pp
+For some caveats with the spelling of
+.Va symbol ,
+see also the discussion atSee Section
+.Dq Macro .
+.Pp
+.Ss  Li .lcomm Va symbol , Va length
+Reserve
+.Va length
+(an absolute expression) bytes for a local common denoted by
+.Va symbol .
+The section and value of
+.Va symbol
+are those of the new local common. The addresses are allocated in the bss
+section, so that at run-time the bytes start off zeroed.
+.Va Symbol
+is not declared global (see Section
+.Dq Global ) ,
+so is normally not visible to
+.Li ld .
+.Pp
+.Ss  Li .lflags
+.Xr as
+accepts this directive, for compatibility with other assemblers, but ignores
+it.
+.Pp
+.Ss  Li .line Va line-number
+Even though this is a directive associated with the
+.Li a.out
+or
+.Li b.out
+object-code formats,
+.Xr as
+still recognizes it when producing COFF output, and treats
+.Li .line
+as though it were the COFF
+.Li .ln
+.Em if
+it is found outside a
+.Li .def
+/
+.Li .endef
+pair.
+.Pp
+Inside a
+.Li .def ,
+.Li .line
+is, instead, one of the directives used by compilers to generate auxiliary
+symbol information for debugging.
+.Pp
+.Ss  Li .linkonce [ Va type]
+Mark the current section so that the linker only includes a single copy of
+it. This may be used to include the same section in several different object
+files, but ensure that the linker will only include it once in the final output
+file. The
+.Li .linkonce
+pseudo-op must be used for each instance of the section. Duplicate sections
+are detected based on the section name, so it should be unique.
+.Pp
+This directive is only supported by a few object file formats; as of this
+writing, the only object file format which supports it is the Portable Executable
+format used on Windows NT.
+.Pp
+The
+.Va type
+argument is optional. If specified, it must be one of the following strings.
+For example:
+.Bd -literal -offset indent
+\&.linkonce same_size
+.Ed
+Not all types may be supported on all object file formats.
+.Pp
+.Bl -tag -width Ds
+.It  discard
+Silently discard duplicate sections. This is the default.
+.Pp
+.It  one_only
+Warn if there are duplicate sections, but still keep only one copy.
+.Pp
+.It  same_size
+Warn if any of the duplicates have different sizes.
+.Pp
+.It  same_contents
+Warn if any of the duplicates do not have exactly the same contents.
+.El
+.Pp
+.Ss  Li .ln Va line-number
+.Li .ln
+is a synonym for
+.Li .line .
+.Pp
+.Ss  Li .mri Va val
+If
+.Va val
+is non-zero, this tells
+.Xr as
+to enter MRI mode. If
+.Va val
+is zero, this tells
+.Xr as
+to exit MRI mode. This change affects code assembled until the next
+.Li .mri
+directive, or until the end of the file.See Section
+.Dq M .
+.Pp
+.Ss  Li .list
+Control (in conjunction with the
+.Li .nolist
+directive) whether or not assembly listings are generated. These two directives
+maintain an internal counter (which is zero initially).
+.Li .list
+increments the counter, and
+.Li .nolist
+decrements it. Assembly listings are generated whenever the counter is greater
+than zero.
+.Pp
+By default, listings are disabled. When you enable them (with the
+.Li -a
+command line option;see Section
+.Dq Invoking ) ,
+the initial value of the listing counter is one.
+.Pp
+.Ss  Li .long Va expressions
+.Li .long
+is the same as
+.Li .int .
+See Section.Dq Int .
+.Pp
+.Ss  Li .macro
+The commands
+.Li .macro
+and
+.Li .endm
+allow you to define macros that generate assembly output. For example, this
+definition specifies a macro
+.Li sum
+that puts a sequence of numbers into memory:
+.Pp
+.Bd -literal -offset indent
+        .macro  sum from=0, to=5
+        .long   \efrom
+        .if     \eto-\efrom
+        sum     "(\efrom+1)",\eto
+        .endif
+        .endm
+.Ed
+.Pp
+With that definition,
+.Li SUM 0,5
+is equivalent to this assembly input:
+.Pp
+.Bd -literal -offset indent
+        .long   0
+        .long   1
+        .long   2
+        .long   3
+        .long   4
+        .long   5
+.Ed
+.Pp
+.Bl -tag -width Ds
+.It  .macro Va macname
+.It  .macro Va macname Va macargs ...
+Begin the definition of a macro called
+.Va macname .
+If your macro definition requires arguments, specify their names after the
+macro name, separated by commas or spaces. You can qualify the macro argument
+to indicate whether all invocations must specify a non-blank value (through
+.Li : Li req ) ,
+or whether it takes all of the remaining arguments (through
+.Li : Li vararg ) .
+You can supply a default value for any macro argument by following the name
+with
+.Li = Va deflt .
+You cannot define two macros with the same
+.Va macname
+unless it has been subject to the
+.Li .purgem
+directive (see Section
+.Dq Purgem )
+between the two definitions. For example, these are all valid
+.Li .macro
+statements:
+.Pp
+.Bl -tag -width Ds
+.It  .macro comm
+Begin the definition of a macro called
+.Li comm ,
+which takes no arguments.
+.Pp
+.It  .macro plus1 p, p1
+.It  .macro plus1 p p1
+Either statement begins the definition of a macro called
+.Li plus1 ,
+which takes two arguments; within the macro definition, write
+.Li \ep
+or
+.Li \ep1
+to evaluate the arguments.
+.Pp
+.It  .macro reserve_str p1=0 p2
+Begin the definition of a macro called
+.Li reserve_str ,
+with two arguments. The first argument has a default value, but not the second.
+After the definition is complete, you can call the macro either as
+.Li reserve_str Va a, Va b
+(with
+.Li \ep1
+evaluating to
+.Va a
+and
+.Li \ep2
+evaluating to
+.Va b ) ,
+or as
+.Li reserve_str , Va b
+(with
+.Li \ep1
+evaluating as the default, in this case
+.Li 0 ,
+and
+.Li \ep2
+evaluating to
+.Va b ) .
+.Pp
+.It  .macro m p1:req, p2=0, p3:vararg
+Begin the definition of a macro called
+.Li m ,
+with at least three arguments. The first argument must always have a value
+specified, but not the second, which instead has a default value. The third
+formal will get assigned all remaining arguments specified at invocation time.
+.Pp
+When you call a macro, you can specify the argument values either by position,
+or by keyword. For example,
+.Li sum 9,17
+is equivalent to
+.Li sum to=17, from=9 .
+.Pp
+.El
+Note that since each of the
+.Va macargs
+can be an identifier exactly as any other one permitted by the target architecture,
+there may be occasional problems if the target hand-crafts special meanings
+to certain characters when they occur in a special position. For example,
+if the colon (
+.Li : )
+is generally permitted to be part of a symbol name, but the architecture specific
+code special-cases it when occurring as the final character of a symbol (to
+denote a label), then the macro parameter replacement code will have no way
+of knowing that and consider the whole construct (including the colon) an
+identifier, and check only this identifier for being the subject to parameter
+substitution. So for example this macro definition:
+.Pp
+.Bd -literal -offset indent
+	.macro label l
+\el:
+	.endm
+.Ed
+.Pp
+might not work as expected. Invoking
+.Li label foo
+might not create a label called
+.Li foo
+but instead just insert the text
+.Li \el:
+into the assembler source, probably generating an error about an unrecognised
+identifier.
+.Pp
+Similarly problems might occur with the period character (
+.Li . )
+which is often allowed inside opcode names (and hence identifier names). So
+for example constructing a macro to build an opcode from a base name and a
+length specifier like this:
+.Pp
+.Bd -literal -offset indent
+	.macro opcode base length
+        \ebase.\elength
+	.endm
+.Ed
+.Pp
+and invoking it as
+.Li opcode store l
+will not create a
+.Li store.l
+instruction but instead generate some kind of error as the assembler tries
+to interpret the text
+.Li \ebase.\elength .
+.Pp
+There are several possible ways around this problem:
+.Pp
+.Bl -tag -width Ds
+.It  Insert white space
+If it is possible to use white space characters then this is the simplest
+solution. eg:
+.Pp
+.Bd -literal -offset indent
+	.macro label l
+\el :
+	.endm
+.Ed
+.Pp
+.It  Use Li \e()
+The string
+.Li \e()
+can be used to separate the end of a macro argument from the following text.
+eg:
+.Pp
+.Bd -literal -offset indent
+	.macro opcode base length
+        \ebase\e().\elength
+	.endm
+.Ed
+.Pp
+.It  Use the alternate macro syntax mode
+In the alternative macro syntax mode the ampersand character (
+.Li & )
+can be used as a separator. eg:
+.Pp
+.Bd -literal -offset indent
+	.altmacro
+	.macro label l
+l&:
+	.endm
+.Ed
+.El
+.Pp
+Note: this problem of correctly identifying string parameters to pseudo ops
+also applies to the identifiers used in
+.Li .irp
+(see Section
+.Dq Irp )
+and
+.Li .irpc
+(see Section
+.Dq Irpc )
+as well.
+.Pp
+.It  .endm
+Mark the end of a macro definition.
+.Pp
+.It  .exitm
+Exit early from the current macro definition.
+.Pp
+.It  \e@
+.Xr as
+maintains a counter of how many macros it has executed in this pseudo-variable;
+you can copy that number to your output with
+.Li \e@ ,
+but
+.Em only within a macro definition .
+.Pp
+.It  LOCAL Va name [ , ... ]
+.Em Warning: Li LOCAL is only available if you select \(lqalternate macro syntax\(rq with Li --alternate or Li .altmacro.
+See Section.Dq Altmacro .
+.El
+.Pp
+.Ss  Li .altmacro
+Enable alternate macro mode, enabling:
+.Pp
+.Bl -tag -width Ds
+.It  LOCAL Va name [ , ... ]
+One additional directive,
+.Li LOCAL ,
+is available. It is used to generate a string replacement for each of the
+.Va name
+arguments, and replace any instances of
+.Va name
+in each macro expansion. The replacement string is unique in the assembly,
+and different for each separate macro expansion.
+.Li LOCAL
+allows you to write macros that define symbols, without fear of conflict between
+separate macro expansions.
+.Pp
+.It  String delimiters
+You can write strings delimited in these other ways besides
+.Li " Va string" :
+.Pp
+.Bl -tag -width Ds
+.It  ' Va string'
+You can delimit strings with single-quote characters.
+.Pp
+.It  < Va string>
+You can delimit strings with matching angle brackets.
+.El
+.Pp
+.It  single-character string escape
+To include any single character literally in a string (even if the character
+would otherwise have some special meaning), you can prefix the character with
+.Li !
+(an exclamation mark). For example, you can write
+.Li <4.3 !> 5.4!!>
+to get the literal text
+.Li 4.3 > 5.4! .
+.Pp
+.It  Expression results as strings
+You can write
+.Li % Va expr
+to evaluate the expression
+.Va expr
+and use the result as a string.
+.El
+.Pp
+.Ss  Li .noaltmacro
+Disable alternate macro mode.See Section
+.Dq Altmacro .
+.Pp
+.Ss  Li .nolist
+Control (in conjunction with the
+.Li .list
+directive) whether or not assembly listings are generated. These two directives
+maintain an internal counter (which is zero initially).
+.Li .list
+increments the counter, and
+.Li .nolist
+decrements it. Assembly listings are generated whenever the counter is greater
+than zero.
+.Pp
+.Ss  Li .octa Va biGNUms
+This directive expects zero or more biGNUms, separated by commas. For each
+biGNUm, it emits a 16-byte integer.
+.Pp
+The term \(lqocta\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence
+.Em octa
+-word for 16 bytes.
+.Pp
+.Ss  Li .org Va new-lc , Va fill
+Advance the location counter of the current section to
+.Va new-lc .
+.Va new-lc
+is either an absolute expression or an expression with the same section as
+the current subsection. That is, you can't use
+.Li .org
+to cross sections: if
+.Va new-lc
+has the wrong section, the
+.Li .org
+directive is ignored. To be compatible with former assemblers, if the section
+of
+.Va new-lc
+is absolute,
+.Xr as
+issues a warning, then pretends the section of
+.Va new-lc
+is the same as the current subsection.
+.Pp
+.Li .org
+may only increase the location counter, or leave it unchanged; you cannot
+use
+.Li .org
+to move the location counter backwards.
+.Pp
+Because
+.Xr as
+tries to assemble programs in one pass,
+.Va new-lc
+may not be undefined. If you really detest this restriction we eagerly await
+a chance to share your improved assembler.
+.Pp
+Beware that the origin is relative to the start of the section, not to the
+start of the subsection. This is compatible with other people's assemblers.
+.Pp
+When the location counter (of the current subsection) is advanced, the intervening
+bytes are filled with
+.Va fill
+which should be an absolute expression. If the comma and
+.Va fill
+are omitted,
+.Va fill
+defaults to zero.
+.Pp
+.Ss  Li .p2align[wl] Va abs-expr, Va abs-expr, Va abs-expr
+Pad the location counter (in the current subsection) to a particular storage
+boundary. The first expression (which must be absolute) is the number of low-order
+zero bits the location counter must have after advancement. For example
+.Li .p2align 3
+advances the location counter until it a multiple of 8. If the location counter
+is already a multiple of 8, no change is needed.
+.Pp
+The second expression (also absolute) gives the fill value to be stored in
+the padding bytes. It (and the comma) may be omitted. If it is omitted, the
+padding bytes are normally zero. However, on some systems, if the section
+is marked as containing code and the fill value is omitted, the space is filled
+with no-op instructions.
+.Pp
+The third expression is also absolute, and is also optional. If it is present,
+it is the maximum number of bytes that should be skipped by this alignment
+directive. If doing the alignment would require skipping more bytes than the
+specified maximum, then the alignment is not done at all. You can omit the
+fill value (the second argument) entirely by simply using two commas after
+the required alignment; this can be useful if you want the alignment to be
+filled with no-op instructions when appropriate.
+.Pp
+The
+.Li .p2alignw
+and
+.Li .p2alignl
+directives are variants of the
+.Li .p2align
+directive. The
+.Li .p2alignw
+directive treats the fill pattern as a two byte word value. The
+.Li .p2alignl
+directives treats the fill pattern as a four byte longword value. For example,
+.Li .p2alignw 2,0x368d
+will align to a multiple of 4. If it skips two bytes, they will be filled
+in with the value 0x368d (the exact placement of the bytes depends upon the
+endianness of the processor). If it skips 1 or 3 bytes, the fill value is
+undefined.
+.Pp
+.Ss  Li .previous
+This is one of the ELF section stack manipulation directives. The others are
+.Li .section
+(see Section
+.Dq Section ) ,
+.Li .subsection
+(see Section
+.Dq SubSection ) ,
+.Li .pushsection
+(see Section
+.Dq PushSection ) ,
+and
+.Li .popsection
+(see Section
+.Dq PopSection ) .
+.Pp
+This directive swaps the current section (and subsection) with most recently
+referenced section (and subsection) prior to this one. Multiple
+.Li .previous
+directives in a row will flip between two sections (and their subsections).
+.Pp
+In terms of the section stack, this directive swaps the current section with
+the top section on the section stack.
+.Pp
+.Ss  Li .popsection
+This is one of the ELF section stack manipulation directives. The others are
+.Li .section
+(see Section
+.Dq Section ) ,
+.Li .subsection
+(see Section
+.Dq SubSection ) ,
+.Li .pushsection
+(see Section
+.Dq PushSection ) ,
+and
+.Li .previous
+(see Section
+.Dq Previous ) .
+.Pp
+This directive replaces the current section (and subsection) with the top
+section (and subsection) on the section stack. This section is popped off
+the stack.
+.Pp
+.Ss  Li .print Va string
+.Xr as
+will print
+.Va string
+on the standard output during assembly. You must put
+.Va string
+in double quotes.
+.Pp
+.Ss  Li .protected Va names
+This is one of the ELF visibility directives. The other two are
+.Li .hidden
+(see Section
+.Dq Hidden )
+and
+.Li .internal
+(see Section
+.Dq Internal ) .
+.Pp
+This directive overrides the named symbols default visibility (which is set
+by their binding: local, global or weak). The directive sets the visibility
+to
+.Li protected
+which means that any references to the symbols from within the components
+that defines them must be resolved to the definition in that component, even
+if a definition in another component would normally preempt this.
+.Pp
+.Ss  Li .psize Va lines , Va columns
+Use this directive to declare the number of lines---and, optionally, the number
+of columns---to use for each page, when generating listings.
+.Pp
+If you do not use
+.Li .psize ,
+listings use a default line-count of 60. You may omit the comma and
+.Va columns
+specification; the default width is 200 columns.
+.Pp
+.Xr as
+generates formfeeds whenever the specified number of lines is exceeded (or
+whenever you explicitly request one, using
+.Li .eject ) .
+.Pp
+If you specify
+.Va lines
+as
+.Li 0 ,
+no formfeeds are generated save those explicitly specified with
+.Li .eject .
+.Pp
+.Ss  Li .purgem Va name
+Undefine the macro
+.Va name ,
+so that later uses of the string will not be expanded.See Section
+.Dq Macro .
+.Pp
+.Ss  Li .pushsection Va name , Va subsection
+This is one of the ELF section stack manipulation directives. The others are
+.Li .section
+(see Section
+.Dq Section ) ,
+.Li .subsection
+(see Section
+.Dq SubSection ) ,
+.Li .popsection
+(see Section
+.Dq PopSection ) ,
+and
+.Li .previous
+(see Section
+.Dq Previous ) .
+.Pp
+This directive pushes the current section (and subsection) onto the top of
+the section stack, and then replaces the current section and subsection with
+.Li name
+and
+.Li subsection .
+.Pp
+.Ss  Li .quad Va biGNUms
+.Li .quad
+expects zero or more biGNUms, separated by commas. For each bignum, it emits
+an 8-byte integer. If the biGNUm won't fit in 8 bytes, it prints a warning
+message; and just takes the lowest order 8 bytes of the biGNUm.
+.Pp
+The term \(lqquad\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence
+.Em quad
+-word for 8 bytes.
+.Pp
+.Ss  Li .reloc Va offset, Va reloc_name[, Va expression]
+Generate a relocation at
+.Va offset
+of type
+.Va reloc_name
+with value
+.Va expression .
+If
+.Va offset
+is a number, the relocation is generated in the current section. If
+.Va offset
+is an expression that resolves to a symbol plus offset, the relocation is
+generated in the given symbol's section.
+.Va expression ,
+if present, must resolve to a symbol plus addend or to an absolute value,
+but note that not all targets support an addend. e.g. ELF REL targets such
+as i386 store an addend in the section contents rather than in the relocation.
+This low level interface does not support addends stored in the section.
+.Pp
+.Ss  Li .rept Va count
+Repeat the sequence of lines between the
+.Li .rept
+directive and the next
+.Li .endr
+directive
+.Va count
+times.
+.Pp
+For example, assembling
+.Pp
+.Bd -literal -offset indent
+        .rept   3
+        .long   0
+        .endr
+.Ed
+.Pp
+is equivalent to assembling
+.Pp
+.Bd -literal -offset indent
+        .long   0
+        .long   0
+        .long   0
+.Ed
+.Pp
+.Ss  Li .sbttl " Va subheading"
+Use
+.Va subheading
+as the title (third line, immediately after the title line) when generating
+assembly listings.
+.Pp
+This directive affects subsequent pages, as well as the current page if it
+appears within ten lines of the top of a page.
+.Pp
+.Ss  Li .section Va name
+Use the
+.Li .section
+directive to assemble the following code into a section named
+.Va name .
+.Pp
+This directive is only supported for targets that actually support arbitrarily
+named sections; on
+.Li a.out
+targets, for example, it is not accepted, even with a standard
+.Li a.out
+section name.
+.Pp
+This is one of the ELF section stack manipulation directives. The others are
+.Li .subsection
+(see Section
+.Dq SubSection ) ,
+.Li .pushsection
+(see Section
+.Dq PushSection ) ,
+.Li .popsection
+(see Section
+.Dq PopSection ) ,
+and
+.Li .previous
+(see Section
+.Dq Previous ) .
+.Pp
+For ELF targets, the
+.Li .section
+directive is used like this:
+.Pp
+.Bd -literal -offset indent
+\&.section name [, "flags"[, @type[,flag_specific_arguments]]]
+.Ed
+.Pp
+The optional
+.Va flags
+argument is a quoted string which may contain any combination of the following
+characters:
+.Bl -tag -width Ds
+.It  a
+section is allocatable
+.It  w
+section is writable
+.It  x
+section is executable
+.It  M
+section is mergeable
+.It  S
+section contains zero terminated strings
+.It  G
+section is a member of a section group
+.It  T
+section is used for thread-local-storage
+.El
+.Pp
+The optional
+.Va type
+argument may contain one of the following constants:
+.Bl -tag -width Ds
+.It  @progbits
+section contains data
+.It  @nobits
+section does not contain data (i.e., section only occupies space)
+.It  @note
+section contains data which is used by things other than the program
+.It  @init_array
+section contains an array of pointers to init functions
+.It  @fini_array
+section contains an array of pointers to finish functions
+.It  @preinit_array
+section contains an array of pointers to pre-init functions
+.El
+.Pp
+Many targets only support the first three section types.
+.Pp
+Note on targets where the
+.Li @
+character is the start of a comment (eg ARM) then another character is used
+instead. For example the ARM port uses the
+.Li %
+character.
+.Pp
+If
+.Va flags
+contains the
+.Li M
+symbol then the
+.Va type
+argument must be specified as well as an extra argument---
+.Va entsize
+---like this:
+.Pp
+.Bd -literal -offset indent
+\&.section name , "flags"M, @type, entsize
+.Ed
+.Pp
+Sections with the
+.Li M
+flag but not
+.Li S
+flag must contain fixed size constants, each
+.Va entsize
+octets long. Sections with both
+.Li M
+and
+.Li S
+must contain zero terminated strings where each character is
+.Va entsize
+bytes long. The linker may remove duplicates within sections with the same
+name, same entity size and same flags.
+.Va entsize
+must be an absolute expression.
+.Pp
+If
+.Va flags
+contains the
+.Li G
+symbol then the
+.Va type
+argument must be present along with an additional field like this:
+.Pp
+.Bd -literal -offset indent
+\&.section name , "flags"G, @type, GroupName[, linkage]
+.Ed
+.Pp
+The
+.Va GroupName
+field specifies the name of the section group to which this particular section
+belongs. The optional linkage field can contain:
+.Bl -tag -width Ds
+.It  comdat
+indicates that only one copy of this section should be retained
+.It  .GNU.linkonce
+an alias for comdat
+.El
+.Pp
+Note: if both the
+.Va M
+and
+.Va G
+flags are present then the fields for the Merge flag should come first, like
+this:
+.Pp
+.Bd -literal -offset indent
+\&.section name , "flags"MG, @type, entsize, GroupName[, linkage]
+.Ed
+.Pp
+If no flags are specified, the default flags depend upon the section name.
+If the section name is not recognized, the default will be for the section
+to have none of the above flags: it will not be allocated in memory, nor writable,
+nor executable. The section will contain data.
+.Pp
+For ELF targets, the assembler supports another type of
+.Li .section
+directive for compatibility with the Solaris assembler:
+.Pp
+.Bd -literal -offset indent
+\&.section "name"[, flags...]
+.Ed
+.Pp
+Note that the section name is quoted. There may be a sequence of comma separated
+flags:
+.Bl -tag -width Ds
+.It  #alloc
+section is allocatable
+.It  #write
+section is writable
+.It  #execinstr
+section is executable
+.It  #tls
+section is used for thread local storage
+.El
+.Pp
+This directive replaces the current section and subsection. See the contents
+of the gas testsuite directory
+.Li gas/testsuite/gas/elf
+for some examples of how this directive and the other section stack directives
+work.
+.Pp
+.Ss  Li .set Va symbol, Va expression
+Set the value of
+.Va symbol
+to
+.Va expression .
+This changes
+.Va symbol
+\&'s value and type to conform to
+.Va expression .
+If
+.Va symbol
+was flagged as external, it remains flagged (see Section
+.Dq Symbol Attributes ) .
+.Pp
+You may
+.Li .set
+a symbol many times in the same assembly.
+.Pp
+If you
+.Li .set
+a global symbol, the value stored in the object file is the last value stored
+into it.
+.Pp
+.Ss  Li .short Va expressions
+This expects zero or more
+.Va expressions ,
+and emits a 16 bit number for each.
+.Pp
+.Ss  Li .single Va flonums
+This directive assembles zero or more flonums, separated by commas. It has
+the same effect as
+.Li .float .
+.Pp
+.Ss  Li .size
+This directive is used to set the size associated with a symbol.
+.Pp
+For ELF targets, the
+.Li .size
+directive is used like this:
+.Pp
+.Bd -literal -offset indent
+\&.size name , expression
+.Ed
+.Pp
+This directive sets the size associated with a symbol
+.Va name .
+The size in bytes is computed from
+.Va expression
+which can make use of label arithmetic. This directive is typically used to
+set the size of function symbols.
+.Pp
+.Ss  Li .sleb128 Va expressions
+.Va sleb128
+stands for \(lqsigned little endian base 128.\(rq This is a compact, variable length
+representation of numbers used by the DWARF symbolic debugging format.See Section
+.Dq Uleb128 .
+.Pp
+.Ss  Li .skip Va size , Va fill
+This directive emits
+.Va size
+bytes, each of value
+.Va fill .
+Both
+.Va size
+and
+.Va fill
+are absolute expressions. If the comma and
+.Va fill
+are omitted,
+.Va fill
+is assumed to be zero. This is the same as
+.Li .space .
+.Pp
+.Ss  Li .space Va size , Va fill
+This directive emits
+.Va size
+bytes, each of value
+.Va fill .
+Both
+.Va size
+and
+.Va fill
+are absolute expressions. If the comma and
+.Va fill
+are omitted,
+.Va fill
+is assumed to be zero. This is the same as
+.Li .skip .
+.Pp
+.Ss  Li .stabd, .stabn, .stabs
+There are three directives that begin
+.Li .stab .
+All emit symbols (see Section
+.Dq Symbols ) ,
+for use by symbolic debuggers. The symbols are not entered in the
+.Xr as
+hash table: they cannot be referenced elsewhere in the source file. Up to
+five fields are required:
+.Pp
+.Bl -tag -width Ds
+.It  string
+This is the symbol's name. It may contain any character except
+.Li \e000 ,
+so is more general than ordinary symbol names. Some debuggers used to code
+arbitrarily complex structures into symbol names using this field.
+.Pp
+.It  type
+An absolute expression. The symbol's type is set to the low 8 bits of this
+expression. Any bit pattern is permitted, but
+.Li ld
+and debuggers choke on silly bit patterns.
+.Pp
+.It  other
+An absolute expression. The symbol's \(lqother\(rq attribute is set to the low 8 bits
+of this expression.
+.Pp
+.It  desc
+An absolute expression. The symbol's descriptor is set to the low 16 bits
+of this expression.
+.Pp
+.It  value
+An absolute expression which becomes the symbol's value.
+.El
+.Pp
+If a warning is detected while reading a
+.Li .stabd ,
+.Li .stabn ,
+or
+.Li .stabs
+statement, the symbol has probably already been created; you get a half-formed
+symbol in your object file. This is compatible with earlier assemblers!
+.Pp
+.Bl -tag -width Ds
+.It  .stabd Va type , Va other , Va desc
+.Pp
+The \(lqname\(rq of the symbol generated is not even an empty string. It is a null
+pointer, for compatibility. Older assemblers used a null pointer so they didn't
+waste space in object files with empty strings.
+.Pp
+The symbol's value is set to the location counter, relocatably. When your
+program is linked, the value of this symbol is the address of the location
+counter when the
+.Li .stabd
+was assembled.
+.Pp
+.It  .stabn Va type , Va other , Va desc , Va value
+The name of the symbol is set to the empty string
+.Li "" .
+.Pp
+.It  .stabs Va string , Va type , Va other , Va desc , Va value
+All five fields are specified.
+.El
+.Pp
+.Ss  Li .string " Va str"
+Copy the characters in
+.Va str
+to the object file. You may specify more than one string to copy, separated
+by commas. Unless otherwise specified for a particular machine, the assembler
+marks the end of each string with a 0 byte. You can use any of the escape
+sequences described in Strings,,Strings.
+.Pp
+.Ss  Li .struct Va expression
+Switch to the absolute section, and set the section offset to
+.Va expression ,
+which must be an absolute expression. You might use this as follows:
+.Bd -literal -offset indent
+        .struct 0
+field1:
+        .struct field1 + 4
+field2:
+        .struct field2 + 4
+field3:
+.Ed
+This would define the symbol
+.Li field1
+to have the value 0, the symbol
+.Li field2
+to have the value 4, and the symbol
+.Li field3
+to have the value 8. Assembly would be left in the absolute section, and you
+would need to use a
+.Li .section
+directive of some sort to change to some other section before further assembly.
+.Pp
+.Ss  Li .subsection Va name
+This is one of the ELF section stack manipulation directives. The others are
+.Li .section
+(see Section
+.Dq Section ) ,
+.Li .pushsection
+(see Section
+.Dq PushSection ) ,
+.Li .popsection
+(see Section
+.Dq PopSection ) ,
+and
+.Li .previous
+(see Section
+.Dq Previous ) .
+.Pp
+This directive replaces the current subsection with
+.Li name .
+The current section is not changed. The replaced subsection is put onto the
+section stack in place of the then current top of stack subsection.
+.Pp
+.Ss  Li .symver
+Use the
+.Li .symver
+directive to bind symbols to specific version nodes within a source file.
+This is only supported on ELF platforms, and is typically used when assembling
+files to be linked into a shared library. There are cases where it may make
+sense to use this in objects to be bound into an application itself so as
+to override a versioned symbol from a shared library.
+.Pp
+For ELF targets, the
+.Li .symver
+directive can be used like this:
+.Bd -literal -offset indent
+\&.symver name, name2@nodename
+.Ed
+If the symbol
+.Va name
+is defined within the file being assembled, the
+.Li .symver
+directive effectively creates a symbol alias with the name
+.Va name2@nodename ,
+and in fact the main reason that we just don't try and create a regular alias
+is that the
+.Va @
+character isn't permitted in symbol names. The
+.Va name2
+part of the name is the actual name of the symbol by which it will be externally
+referenced. The name
+.Va name
+itself is merely a name of convenience that is used so that it is possible
+to have definitions for multiple versions of a function within a single source
+file, and so that the compiler can unambiguously know which version of a function
+is being mentioned. The
+.Va nodename
+portion of the alias should be the name of a node specified in the version
+script supplied to the linker when building a shared library. If you are attempting
+to override a versioned symbol from a shared library, then
+.Va nodename
+should correspond to the nodename of the symbol you are trying to override.
+.Pp
+If the symbol
+.Va name
+is not defined within the file being assembled, all references to
+.Va name
+will be changed to
+.Va name2@nodename .
+If no reference to
+.Va name
+is made,
+.Va name2@nodename
+will be removed from the symbol table.
+.Pp
+Another usage of the
+.Li .symver
+directive is:
+.Bd -literal -offset indent
+\&.symver name, name2@@nodename
+.Ed
+In this case, the symbol
+.Va name
+must exist and be defined within the file being assembled. It is similar to
+.Va name2@nodename .
+The difference is
+.Va name2@@nodename
+will also be used to resolve references to
+.Va name2
+by the linker.
+.Pp
+The third usage of the
+.Li .symver
+directive is:
+.Bd -literal -offset indent
+\&.symver name, name2@@@nodename
+.Ed
+When
+.Va name
+is not defined within the file being assembled, it is treated as
+.Va name2@nodename .
+When
+.Va name
+is defined within the file being assembled, the symbol name,
+.Va name ,
+will be changed to
+.Va name2@@nodename .
+.Pp
+.Ss  Li .text Va subsection
+Tells
+.Xr as
+to assemble the following statements onto the end of the text subsection numbered
+.Va subsection ,
+which is an absolute expression. If
+.Va subsection
+is omitted, subsection number zero is used.
+.Pp
+.Ss  Li .title " Va heading"
+Use
+.Va heading
+as the title (second line, immediately after the source file name and pagenumber)
+when generating assembly listings.
+.Pp
+This directive affects subsequent pages, as well as the current page if it
+appears within ten lines of the top of a page.
+.Pp
+.Ss  Li .type
+This directive is used to set the type of a symbol.
+.Pp
+For ELF targets, the
+.Li .type
+directive is used like this:
+.Pp
+.Bd -literal -offset indent
+\&.type name , type description
+.Ed
+.Pp
+This sets the type of symbol
+.Va name
+to be either a function symbol or an object symbol. There are five different
+syntaxes supported for the
+.Va type description
+field, in order to provide compatibility with various other assemblers.
+.Pp
+Because some of the characters used in these syntaxes (such as
+.Li @
+and
+.Li # )
+are comment characters for some architectures, some of the syntaxes below
+do not work on all architectures. The first variant will be accepted by the
+GNU assembler on all architectures so that variant should be used for maximum
+portability, if you do not need to assemble your code with other assemblers.
+.Pp
+The syntaxes supported are:
+.Pp
+.Bd -literal -offset indent
+  .type <name> STT_FUNCTION
+  .type <name> STT_OBJECT
+
+  .type <name>,#function
+  .type <name>,#object
+
+  .type <name>,@function
+  .type <name>,@object
+
+  .type <name>,%function
+  .type <name>,%object
+  
+  .type <name>,"function"
+  .type <name>,"object"
+.Ed
+.Pp
+.Ss  Li .uleb128 Va expressions
+.Va uleb128
+stands for \(lqunsigned little endian base 128.\(rq This is a compact, variable length
+representation of numbers used by the DWARF symbolic debugging format.See Section
+.Dq Sleb128 .
+.Pp
+.Ss  Li .version " Va string"
+This directive creates a
+.Li .note
+section and places into it an ELF formatted note of type NT_VERSION. The note's
+name is set to
+.Li string .
+.Pp
+.Ss  Li .vtable_entry Va table, Va offset
+This directive finds or creates a symbol
+.Li table
+and creates a
+.Li VTABLE_ENTRY
+relocation for it with an addend of
+.Li offset .
+.Pp
+.Ss  Li .vtable_inherit Va child, Va parent
+This directive finds the symbol
+.Li child
+and finds or creates the symbol
+.Li parent
+and then creates a
+.Li VTABLE_INHERIT
+relocation for the parent whose addend is the value of the child symbol. As
+a special case the parent name of
+.Li 0
+is treated as referring to the
+.Li *ABS*
+section.
+.Pp
+.Ss  Li .warning " Va string"
+Similar to the directive
+.Li .error
+(see Section
+.Dq Error ) ,
+but just emits a warning.
+.Pp
+.Ss  Li .weak Va names
+This directive sets the weak attribute on the comma separated list of symbol
+.Li names .
+If the symbols do not already exist, they will be created.
+.Pp
+On COFF targets other than PE, weak symbols are a GNU extension. This directive
+sets the weak attribute on the comma separated list of symbol
+.Li names .
+If the symbols do not already exist, they will be created.
+.Pp
+On the PE target, weak symbols are supported natively as weak aliases. When
+a weak symbol is created that is not an alias, GAS creates an alternate symbol
+to hold the default value.
+.Pp
+.Ss  Li .weakref Va alias, Va target
+This directive creates an alias to the target symbol that enables the symbol
+to be referenced with weak-symbol semantics, but without actually making it
+weak. If direct references or definitions of the symbol are present, then
+the symbol will not be weak, but if all references to it are through weak
+references, the symbol will be marked as weak in the symbol table.
+.Pp
+The effect is equivalent to moving all references to the alias to a separate
+assembly source file, renaming the alias to the symbol in it, declaring the
+symbol as weak there, and running a reloadable link to merge the object files
+resulting from the assembly of the new source file and the old source file
+that had the references to the alias removed.
+.Pp
+The alias itself never makes to the symbol table, and is entirely handled
+within the assembler.
+.Pp
+.Ss  Li .word Va expressions
+This directive expects zero or more
+.Va expressions ,
+of any section, separated by commas. For each expression,
+.Xr as
+emits a 32-bit number.
+.Pp
+.Ss  Deprecated Directives
+One day these directives won't work. They are included for compatibility with
+older assemblers.
+.Bl -tag -width Ds
+.It  .abort
+.It  .line
+.El
+.Pp
+.Sh  ARM Dependent Features
+.Ss  Options
+.Bl -tag -width Ds
+.It  -mcpu= Va processor[+ Va extension...]
+This option specifies the target processor. The assembler will issue an error
+message if an attempt is made to assemble an instruction which will not execute
+on the target processor. The following processor names are recognized:
+.Li arm1 ,
+.Li arm2 ,
+.Li arm250 ,
+.Li arm3 ,
+.Li arm6 ,
+.Li arm60 ,
+.Li arm600 ,
+.Li arm610 ,
+.Li arm620 ,
+.Li arm7 ,
+.Li arm7m ,
+.Li arm7d ,
+.Li arm7dm ,
+.Li arm7di ,
+.Li arm7dmi ,
+.Li arm70 ,
+.Li arm700 ,
+.Li arm700i ,
+.Li arm710 ,
+.Li arm710t ,
+.Li arm720 ,
+.Li arm720t ,
+.Li arm740t ,
+.Li arm710c ,
+.Li arm7100 ,
+.Li arm7500 ,
+.Li arm7500fe ,
+.Li arm7t ,
+.Li arm7tdmi ,
+.Li arm7tdmi-s ,
+.Li arm8 ,
+.Li arm810 ,
+.Li strongarm ,
+.Li strongarm1 ,
+.Li strongarm110 ,
+.Li strongarm1100 ,
+.Li strongarm1110 ,
+.Li arm9 ,
+.Li arm920 ,
+.Li arm920t ,
+.Li arm922t ,
+.Li arm940t ,
+.Li arm9tdmi ,
+.Li arm9e ,
+.Li arm926e ,
+.Li arm926ej-s ,
+.Li arm946e-r0 ,
+.Li arm946e ,
+.Li arm946e-s ,
+.Li arm966e-r0 ,
+.Li arm966e ,
+.Li arm966e-s ,
+.Li arm968e-s ,
+.Li arm10t ,
+.Li arm10tdmi ,
+.Li arm10e ,
+.Li arm1020 ,
+.Li arm1020t ,
+.Li arm1020e ,
+.Li arm1022e ,
+.Li arm1026ej-s ,
+.Li arm1136j-s ,
+.Li arm1136jf-s ,
+.Li arm1156t2-s ,
+.Li arm1156t2f-s ,
+.Li arm1176jz-s ,
+.Li arm1176jzf-s ,
+.Li mpcore ,
+.Li mpcorenovfp ,
+.Li cortex-a8 ,
+.Li cortex-r4 ,
+.Li cortex-m3 ,
+.Li ep9312
+(ARM920 with Cirrus Maverick coprocessor),
+.Li i80200
+(Intel XScale processor)
+.Li iwmmxt
+(Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) and
+.Li xscale .
+The special name
+.Li all
+may be used to allow the assembler to accept instructions valid for any ARM
+processor.
+.Pp
+In addition to the basic instruction set, the assembler can be told to accept
+various extension mnemonics that extend the processor using the co-processor
+instruction space. For example,
+.Li -mcpu=arm920+maverick
+is equivalent to specifying
+.Li -mcpu=ep9312 .
+The following extensions are currently supported:
+.Li +maverick
+.Li +iwmmxt
+and
+.Li +xscale .
+.Pp
+.It  -march= Va architecture[+ Va extension...]
+This option specifies the target architecture. The assembler will issue an
+error message if an attempt is made to assemble an instruction which will
+not execute on the target architecture. The following architecture names are
+recognized:
+.Li armv1 ,
+.Li armv2 ,
+.Li armv2a ,
+.Li armv2s ,
+.Li armv3 ,
+.Li armv3m ,
+.Li armv4 ,
+.Li armv4xm ,
+.Li armv4t ,
+.Li armv4txm ,
+.Li armv5 ,
+.Li armv5t ,
+.Li armv5txm ,
+.Li armv5te ,
+.Li armv5texp ,
+.Li armv6 ,
+.Li armv6j ,
+.Li armv6k ,
+.Li armv6z ,
+.Li armv6zk ,
+.Li armv7 ,
+.Li armv7-a ,
+.Li armv7-r ,
+.Li armv7-m ,
+.Li iwmmxt
+and
+.Li xscale .
+If both
+.Li -mcpu
+and
+.Li -march
+are specified, the assembler will use the setting for
+.Li -mcpu .
+.Pp
+The architecture option can be extended with the same instruction set extension
+options as the
+.Li -mcpu
+option.
+.Pp
+.It  -mfpu= Va floating-point-format
+.Pp
+This option specifies the floating point format to assemble for. The assembler
+will issue an error message if an attempt is made to assemble an instruction
+which will not execute on the target floating point unit. The following format
+options are recognized:
+.Li softfpa ,
+.Li fpe ,
+.Li fpe2 ,
+.Li fpe3 ,
+.Li fpa ,
+.Li fpa10 ,
+.Li fpa11 ,
+.Li arm7500fe ,
+.Li softvfp ,
+.Li softvfp+vfp ,
+.Li vfp ,
+.Li vfp10 ,
+.Li vfp10-r0 ,
+.Li vfp9 ,
+.Li vfpxd ,
+.Li arm1020t ,
+.Li arm1020e ,
+.Li arm1136jf-s
+and
+.Li maverick .
+.Pp
+In addition to determining which instructions are assembled, this option also
+affects the way in which the
+.Li .double
+assembler directive behaves when assembling little-endian code.
+.Pp
+The default is dependent on the processor selected. For Architecture 5 or
+later, the default is to assembler for VFP instructions; for earlier architectures
+the default is to assemble for FPA instructions.
+.Pp
+.It  -mthumb
+This option specifies that the assembler should start assembling Thumb instructions;
+that is, it should behave as though the file starts with a
+.Li .code 16
+directive.
+.Pp
+.It  -mthumb-interwork
+This option specifies that the output generated by the assembler should be
+marked as supporting interworking.
+.Pp
+.It  -mapcs Li [26|32]
+This option specifies that the output generated by the assembler should be
+marked as supporting the indicated version of the Arm Procedure. Calling Standard.
+.Pp
+.It  -matpcs
+This option specifies that the output generated by the assembler should be
+marked as supporting the Arm/Thumb Procedure Calling Standard. If enabled
+this option will cause the assembler to create an empty debugging section
+in the object file called .arm.atpcs. Debuggers can use this to determine
+the ABI being used by.
+.Pp
+.It  -mapcs-float
+This indicates the floating point variant of the APCS should be used. In this
+variant floating point arguments are passed in FP registers rather than integer
+registers.
+.Pp
+.It  -mapcs-reentrant
+This indicates that the reentrant variant of the APCS should be used. This
+variant supports position independent code.
+.Pp
+.It  -mfloat-abi= Va abi
+This option specifies that the output generated by the assembler should be
+marked as using specified floating point ABI. The following values are recognized:
+.Li soft ,
+.Li softfp
+and
+.Li hard .
+.Pp
+.It  -meabi= Va ver
+This option specifies which EABI version the produced object files should
+conform to. The following values are recognized:
+.Li GNU ,
+.Li 4
+and
+.Li 5 .
+.Pp
+.It  -EB
+This option specifies that the output generated by the assembler should be
+marked as being encoded for a big-endian processor.
+.Pp
+.It  -EL
+This option specifies that the output generated by the assembler should be
+marked as being encoded for a little-endian processor.
+.Pp
+.It  -k
+This option specifies that the output of the assembler should be marked as
+position-independent code (PIC).
+.Pp
+.El
+.Ss  Syntax
+.Em  Special Characters
+.Pp
+The presence of a
+.Li @
+on a line indicates the start of a comment that extends to the end of the
+current line. If a
+.Li #
+appears as the first character of a line, the whole line is treated as a comment.
+.Pp
+The
+.Li ;
+character can be used instead of a newline to separate statements.
+.Pp
+Either
+.Li #
+or
+.Li $
+can be used to indicate immediate operands.
+.Pp
+*TODO* Explain about /data modifier on symbols.
+.Pp
+.Em  Register Names
+.Pp
+*TODO* Explain about ARM register naming, and the predefined names.
+.Pp
+.Em  ARM relocation generation
+.Pp
+Specific data relocations can be generated by putting the relocation name
+in parentheses after the symbol name. For example:
+.Pp
+.Bd -literal -offset indent
+        .word foo(TARGET1)
+.Ed
+.Pp
+This will generate an
+.Li R_ARM_TARGET1
+relocation against the symbol
+.Va foo .
+The following relocations are supported:
+.Li GOT ,
+.Li GOTOFF ,
+.Li TARGET1 ,
+.Li TARGET2 ,
+.Li SBREL ,
+.Li TLSGD ,
+.Li TLSLDM ,
+.Li TLSLDO ,
+.Li GOTTPOFF
+and
+.Li TPOFF .
+.Pp
+For compatibility with older toolchains the assembler also accepts
+.Li (PLT)
+after branch targets. This will generate the deprecated
+.Li R_ARM_PLT32
+relocation.
+.Pp
+Relocations for
+.Li MOVW
+and
+.Li MOVT
+instructions can be generated by prefixing the value with
+.Li #:lower16:
+and
+.Li #:upper16
+respectively. For example to load the 32-bit address of foo into r0:
+.Pp
+.Bd -literal -offset indent
+        MOVW r0, #:lower16:foo
+        MOVT r0, #:upper16:foo
+.Ed
+.Pp
+.Ss  Floating Point
+The ARM family uses ieee floating-point numbers.
+.Pp
+.Ss  ARM Machine Directives
+.Bl -tag -width Ds
+.It  .align Va expression [, Va expression]
+This is the generic
+.Va .align
+directive. For the ARM however if the first argument is zero (ie no alignment
+is needed) the assembler will behave as if the argument had been 2 (ie pad
+to the next four byte boundary). This is for compatibility with ARM's own
+assembler.
+.Pp
+.It  Va name .req Va register name
+This creates an alias for
+.Va register name
+called
+.Va name .
+For example:
+.Pp
+.Bd -literal -offset indent
+        foo .req r0
+.Ed
+.Pp
+.It  .unreq Va alias-name
+This undefines a register alias which was previously defined using the
+.Li req ,
+.Li dn
+or
+.Li qn
+directives. For example:
+.Pp
+.Bd -literal -offset indent
+        foo .req r0
+        .unreq foo
+.Ed
+.Pp
+An error occurs if the name is undefined. Note - this pseudo op can be used
+to delete builtin in register name aliases (eg 'r0'). This should only be
+done if it is really necessary.
+.Pp
+.It  Va name .dn Va register name [ Va .type] [ Va [index]]
+.It  Va name .qn Va register name [ Va .type] [ Va [index]]
+.Pp
+The
+.Li dn
+and
+.Li qn
+directives are used to create typed and/or indexed register aliases for use
+in Advanced SIMD Extension (Neon) instructions. The former should be used
+to create aliases of double-precision registers, and the latter to create
+aliases of quad-precision registers.
+.Pp
+If these directives are used to create typed aliases, those aliases can be
+used in Neon instructions instead of writing types after the mnemonic or after
+each operand. For example:
+.Pp
+.Bd -literal -offset indent
+        x .dn d2.f32
+        y .dn d3.f32
+        z .dn d4.f32[1]
+        vmul x,y,z
+.Ed
+.Pp
+This is equivalent to writing the following:
+.Pp
+.Bd -literal -offset indent
+        vmul.f32 d2,d3,d4[1]
+.Ed
+.Pp
+Aliases created using
+.Li dn
+or
+.Li qn
+can be destroyed using
+.Li unreq .
+.Pp
+.It  .code Li [16|32]
+This directive selects the instruction set being generated. The value 16 selects
+Thumb, with the value 32 selecting ARM.
+.Pp
+.It  .thumb
+This performs the same action as
+.Va .code 16 .
+.Pp
+.It  .arm
+This performs the same action as
+.Va .code 32 .
+.Pp
+.It  .force_thumb
+This directive forces the selection of Thumb instructions, even if the target
+processor does not support those instructions
+.Pp
+.It  .thumb_func
+This directive specifies that the following symbol is the name of a Thumb
+encoded function. This information is necessary in order to allow the assembler
+and linker to generate correct code for interworking between Arm and Thumb
+instructions and should be used even if interworking is not going to be performed.
+The presence of this directive also implies
+.Li .thumb
+.Pp
+This directive is not neccessary when generating EABI objects. On these targets
+the encoding is implicit when generating Thumb code.
+.Pp
+.It  .thumb_set
+This performs the equivalent of a
+.Li .set
+directive in that it creates a symbol which is an alias for another symbol
+(possibly not yet defined). This directive also has the added property in
+that it marks the aliased symbol as being a thumb function entry point, in
+the same way that the
+.Li .thumb_func
+directive does.
+.Pp
+.It  .ltorg
+This directive causes the current contents of the literal pool to be dumped
+into the current section (which is assumed to be the .text section) at the
+current location (aligned to a word boundary).
+.Li GAS
+maintains a separate literal pool for each section and each sub-section. The
+.Li .ltorg
+directive will only affect the literal pool of the current section and sub-section.
+At the end of assembly all remaining, un-empty literal pools will automatically
+be dumped.
+.Pp
+Note - older versions of
+.Li GAS
+would dump the current literal pool any time a section change occurred. This
+is no longer done, since it prevents accurate control of the placement of
+literal pools.
+.Pp
+.It  .pool
+This is a synonym for .ltorg.
+.Pp
+.It  .unwind_fnstart
+Marks the start of a function with an unwind table entry.
+.Pp
+.It  .unwind_fnend
+Marks the end of a function with an unwind table entry. The unwind index table
+entry is created when this directive is processed.
+.Pp
+If no personality routine has been specified then standard personality routine
+0 or 1 will be used, depending on the number of unwind opcodes required.
+.Pp
+.It  .cantunwind
+Prevents unwinding through the current function. No personality routine or
+exception table data is required or permitted.
+.Pp
+.It  .personality Va name
+Sets the personality routine for the current function to
+.Va name .
+.Pp
+.It  .personalityindex Va index
+Sets the personality routine for the current function to the EABI standard
+routine number
+.Va index
+.Pp
+.It  .handlerdata
+Marks the end of the current function, and the start of the exception table
+entry for that function. Anything between this directive and the
+.Li .fnend
+directive will be added to the exception table entry.
+.Pp
+Must be preceded by a
+.Li .personality
+or
+.Li .personalityindex
+directive.
+.Pp
+.It  .save Va reglist
+Generate unwinder annotations to restore the registers in
+.Va reglist .
+The format of
+.Va reglist
+is the same as the corresponding store-multiple instruction.
+.Pp
+.Bd -literal -offset indent
+  .save {r4, r5, r6, lr}
+  stmfd sp!, {r4, r5, r6, lr}
+  .save f4, 2
+  sfmfd f4, 2, [sp]!
+  .save {d8, d9, d10}
+  fstmdx sp!, {d8, d9, d10}
+  .save {wr10, wr11}
+  wstrd wr11, [sp, #-8]!
+  wstrd wr10, [sp, #-8]!
+or
+  .save wr11
+  wstrd wr11, [sp, #-8]!
+  .save wr10
+  wstrd wr10, [sp, #-8]!
+.Ed
+.Pp
+.It  .vsave Va vfp-reglist
+Generate unwinder annotations to restore the VFP registers in
+.Va vfp-reglist
+using FLDMD. Also works for VFPv3 registers that are to be restored using
+VLDM. The format of
+.Va vfp-reglist
+is the same as the corresponding store-multiple instruction.
+.Pp
+.Bd -literal -offset indent
+  .vsave {d8, d9, d10}
+  fstmdd sp!, {d8, d9, d10}
+  .vsave {d15, d16, d17}
+  vstm sp!, {d15, d16, d17}
+.Ed
+.Pp
+Since FLDMX and FSTMX are now deprecated, this directive should be used in
+favour of
+.Li .save
+for saving VFP registers for ARMv6 and above.
+.Pp
+.It  .pad # Va count
+Generate unwinder annotations for a stack adjustment of
+.Va count
+bytes. A positive value indicates the function prologue allocated stack space
+by decrementing the stack pointer.
+.Pp
+.It  .movsp Va reg [, # Va offset]
+Tell the unwinder that
+.Va reg
+contains an offset from the current stack pointer. If
+.Va offset
+is not specified then it is assumed to be zero.
+.Pp
+.It  .setfp Va fpreg, Va spreg [, # Va offset]
+Make all unwinder annotations relaive to a frame pointer. Without this the
+unwinder will use offsets from the stack pointer.
+.Pp
+The syntax of this directive is the same as the
+.Li sub
+or
+.Li mov
+instruction used to set the frame pointer.
+.Va spreg
+must be either
+.Li sp
+or mentioned in a previous
+.Li .movsp
+directive.
+.Pp
+.Bd -literal -offset indent
+\&.movsp ip
+mov ip, sp
+\&...
+\&.setfp fp, ip, #4
+sub fp, ip, #4
+.Ed
+.Pp
+.It  .raw Va offset, Va byte1, ...
+Insert one of more arbitary unwind opcode bytes, which are known to adjust
+the stack pointer by
+.Va offset
+bytes.
+.Pp
+For example
+.Li .unwind_raw 4, 0xb1, 0x01
+is equivalent to
+.Li .save {r0}
+.Pp
+.It  .cpu Va name
+Select the target processor. Valid values for
+.Va name
+are the same as for the
+.Op -mcpu
+commandline option.
+.Pp
+.It  .arch Va name
+Select the target architecture. Valid values for
+.Va name
+are the same as for the
+.Op -march
+commandline option.
+.Pp
+.It  .object_arch Va name
+Override the architecture recorded in the EABI object attribute section. Valid
+values for
+.Va name
+are the same as for the
+.Li .arch
+directive. Typically this is useful when code uses runtime detection of CPU
+features.
+.Pp
+.It  .fpu Va name
+Select the floating point unit to assemble for. Valid values for
+.Va name
+are the same as for the
+.Op -mfpu
+commandline option.
+.Pp
+.It  .eabi_attribute Va tag, Va value
+Set the EABI object attribute number
+.Va tag
+to
+.Va value .
+The value is either a
+.Li number ,
+.Li "string" ,
+or
+.Li number, "string"
+depending on the tag.
+.Pp
+.El
+.Ss  Opcodes
+.Li as
+implements all the standard ARM opcodes. It also implements several pseudo
+opcodes, including several synthetic load instructions.
+.Pp
+.Bl -tag -width Ds
+.It  NOP
+.Bd -literal -offset indent
+  nop
+.Ed
+.Pp
+This pseudo op will always evaluate to a legal ARM instruction that does nothing.
+Currently it will evaluate to MOV r0, r0.
+.Pp
+.It  LDR 
+.Bd -literal -offset indent
+  ldr <register> , = <expression>
+.Ed
+.Pp
+If expression evaluates to a numeric constant then a MOV or MVN instruction
+will be used in place of the LDR instruction, if the constant can be generated
+by either of these instructions. Otherwise the constant will be placed into
+the nearest literal pool (if it not already there) and a PC relative LDR instruction
+will be generated.
+.Pp
+.It  ADR
+.Bd -literal -offset indent
+  adr <register> <label>
+.Ed
+.Pp
+This instruction will load the address of
+.Va label
+into the indicated register. The instruction will evaluate to a PC relative
+ADD or SUB instruction depending upon where the label is located. If the label
+is out of range, or if it is not defined in the same file (and section) as
+the ADR instruction, then an error will be generated. This instruction will
+not make use of the literal pool.
+.Pp
+.It  ADRL 
+.Bd -literal -offset indent
+  adrl <register> <label>
+.Ed
+.Pp
+This instruction will load the address of
+.Va label
+into the indicated register. The instruction will evaluate to one or two PC
+relative ADD or SUB instructions depending upon where the label is located.
+If a second instruction is not needed a NOP instruction will be generated
+in its place, so that this instruction is always 8 bytes long.
+.Pp
+If the label is out of range, or if it is not defined in the same file (and
+section) as the ADRL instruction, then an error will be generated. This instruction
+will not make use of the literal pool.
+.Pp
+.El
+For information on the ARM or Thumb instruction sets, see
+.Em ARM Software Development Toolkit Reference Manual ,
+Advanced RISC Machines Ltd.
+.Pp
+.Ss  Mapping Symbols
+The ARM ELF specification requires that special symbols be inserted into object
+files to mark certain features:
+.Pp
+.Bl -tag -width Ds
+.It  $a
+At the start of a region of code containing ARM instructions.
+.Pp
+.It  $t
+At the start of a region of code containing THUMB instructions.
+.Pp
+.It  $d
+At the start of a region of data.
+.Pp
+.El
+The assembler will automatically insert these symbols for you - there is no
+need to code them yourself. Support for tagging symbols ($b, $f, $p and $m)
+which is also mentioned in the current ARM ELF specification is not implemented.
+This is because they have been dropped from the new EABI and so tools cannot
+rely upon their presence.
+.Pp
+.Sh  80386 Dependent Features
+The i386 version
+.Li as
+supports both the original Intel 386 architecture in both 16 and 32-bit mode
+as well as AMD x86-64 architecture extending the Intel architecture to 64-bits.
+.Pp
+.Ss  Options
+The i386 version of
+.Li as
+has a few machine dependent options:
+.Pp
+.Bl -tag -width Ds
+.It  --32 | --64
+Select the word size, either 32 bits or 64 bits. Selecting 32-bit implies
+Intel i386 architecture, while 64-bit implies AMD x86-64 architecture.
+.Pp
+These options are only available with the ELF object file format, and require
+that the necessary BFD support has been included (on a 32-bit platform you
+have to add --enable-64-bit-bfd to configure enable 64-bit usage and use x86-64
+as target platform).
+.Pp
+.It  -n
+By default, x86 GAS replaces multiple nop instructions used for alignment
+within code sections with multi-byte nop instructions such as leal 0(%esi,1),%esi.
+This switch disables the optimization.
+.Pp
+.It  --divide
+On SVR4-derived platforms, the character
+.Li /
+is treated as a comment character, which means that it cannot be used in expressions.
+The
+.Li --divide
+option turns
+.Li /
+into a normal character. This does not disable
+.Li /
+at the beginning of a line starting a comment, or affect using
+.Li #
+for starting a comment.
+.Pp
+.It  -march= Va CPU
+This option specifies an instruction set architecture for generating instructions.
+The following architectures are recognized:
+.Li i8086 ,
+.Li i186 ,
+.Li i286 ,
+.Li i386 ,
+.Li i486 ,
+.Li i586 ,
+.Li i686 ,
+.Li pentium ,
+.Li pentiumpro ,
+.Li pentiumii ,
+.Li pentiumiii ,
+.Li pentium4 ,
+.Li prescott ,
+.Li nocona ,
+.Li core ,
+.Li core2 ,
+.Li k6 ,
+.Li k6_2 ,
+.Li athlon ,
+.Li sledgehammer ,
+.Li opteron ,
+.Li k8 ,
+.Li generic32
+and
+.Li generic64 .
+.Pp
+This option only affects instructions generated by the assembler. The
+.Li .arch
+directive will take precedent.
+.Pp
+.It  -mtune= Va CPU
+This option specifies a processor to optimize for. When used in conjunction
+with the
+.Op -march
+option, only instructions of the processor specified by the
+.Op -march
+option will be generated.
+.Pp
+Valid
+.Va CPU
+values are identical to
+.Op -march= Va CPU .
+.Pp
+.El
+.Ss  AT&T Syntax versus Intel Syntax
+.Li as
+now supports assembly using Intel assembler syntax.
+.Li .intel_syntax
+selects Intel mode, and
+.Li .att_syntax
+switches back to the usual AT&T mode for compatibility with the output of
+.Li gcc .
+Either of these directives may have an optional argument,
+.Li prefix ,
+or
+.Li noprefix
+specifying whether registers require a
+.Li %
+prefix. AT&T System V/386 assembler syntax is quite different from Intel syntax.
+We mention these differences because almost all 80386 documents use Intel
+syntax. Notable differences between the two syntaxes are:
+.Pp
+.Bl -bullet
+.It
+AT&T immediate operands are preceded by
+.Li $ ;
+Intel immediate operands are undelimited (Intel
+.Li push 4
+is AT&T
+.Li pushl $4 ) .
+AT&T register operands are preceded by
+.Li % ;
+Intel register operands are undelimited. AT&T absolute (as opposed to PC relative)
+jump/call operands are prefixed by
+.Li * ;
+they are undelimited in Intel syntax.
+.Pp
+.It
+AT&T and Intel syntax use the opposite order for source and destination operands.
+Intel
+.Li add eax, 4
+is
+.Li addl $4, %eax .
+The
+.Li source, dest
+convention is maintained for compatibility with previous Unix assemblers.
+Note that instructions with more than one source operand, such as the
+.Li enter
+instruction, do
+.Em not
+have reversed order. i386-Bugs.
+.Pp
+.It
+In AT&T syntax the size of memory operands is determined from the last character
+of the instruction mnemonic. Mnemonic suffixes of
+.Li b ,
+.Li w ,
+.Li l
+and
+.Li q
+specify byte (8-bit), word (16-bit), long (32-bit) and quadruple word (64-bit)
+memory references. Intel syntax accomplishes this by prefixing memory operands
+(
+.Em not
+the instruction mnemonics) with
+.Li byte ptr ,
+.Li word ptr ,
+.Li dword ptr
+and
+.Li qword ptr .
+Thus, Intel
+.Li mov al, byte ptr Va foo
+is
+.Li movb Va foo, %al
+in AT&T syntax.
+.Pp
+.It
+Immediate form long jumps and calls are
+.Li lcall/ljmp $ Va section, $ Va offset
+in AT&T syntax; the Intel syntax is
+.Li call/jmp far Va section: Va offset .
+Also, the far return instruction is
+.Li lret $ Va stack-adjust
+in AT&T syntax; Intel syntax is
+.Li ret far Va stack-adjust .
+.Pp
+.It
+The AT&T assembler does not provide support for multiple section programs.
+Unix style systems expect all programs to be single sections.
+.El
+.Pp
+.Ss  Instruction Naming
+Instruction mnemonics are suffixed with one character modifiers which specify
+the size of operands. The letters
+.Li b ,
+.Li w ,
+.Li l
+and
+.Li q
+specify byte, word, long and quadruple word operands. If no suffix is specified
+by an instruction then
+.Li as
+tries to fill in the missing suffix based on the destination register operand
+(the last one by convention). Thus,
+.Li mov %ax, %bx
+is equivalent to
+.Li movw %ax, %bx ;
+also,
+.Li mov $1, %bx
+is equivalent to
+.Li movw $1, bx .
+Note that this is incompatible with the AT&T Unix assembler which assumes
+that a missing mnemonic suffix implies long operand size. (This incompatibility
+does not affect compiler output since compilers always explicitly specify
+the mnemonic suffix.)
+.Pp
+Almost all instructions have the same names in AT&T and Intel format. There
+are a few exceptions. The sign extend and zero extend instructions need two
+sizes to specify them. They need a size to sign/zero extend
+.Em from
+and a size to zero extend
+.Em to .
+This is accomplished by using two instruction mnemonic suffixes in AT&T syntax.
+Base names for sign extend and zero extend are
+.Li movs...
+and
+.Li movz...
+in AT&T syntax (
+.Li movsx
+and
+.Li movzx
+in Intel syntax). The instruction mnemonic suffixes are tacked on to this
+base name, the
+.Em from
+suffix before the
+.Em to
+suffix. Thus,
+.Li movsbl %al, %edx
+is AT&T syntax for \(lqmove sign extend
+.Em from
+%al
+.Em to
+%edx.\(rq Possible suffixes, thus, are
+.Li bl
+(from byte to long),
+.Li bw
+(from byte to word),
+.Li wl
+(from word to long),
+.Li bq
+(from byte to quadruple word),
+.Li wq
+(from word to quadruple word), and
+.Li lq
+(from long to quadruple word).
+.Pp
+The Intel-syntax conversion instructions
+.Pp
+.Bl -bullet
+.It
+.Li cbw
+--- sign-extend byte in
+.Li %al
+to word in
+.Li %ax ,
+.Pp
+.It
+.Li cwde
+--- sign-extend word in
+.Li %ax
+to long in
+.Li %eax ,
+.Pp
+.It
+.Li cwd
+--- sign-extend word in
+.Li %ax
+to long in
+.Li %dx:%ax ,
+.Pp
+.It
+.Li cdq
+--- sign-extend dword in
+.Li %eax
+to quad in
+.Li %edx:%eax ,
+.Pp
+.It
+.Li cdqe
+--- sign-extend dword in
+.Li %eax
+to quad in
+.Li %rax
+(x86-64 only),
+.Pp
+.It
+.Li cqo
+--- sign-extend quad in
+.Li %rax
+to octuple in
+.Li %rdx:%rax
+(x86-64 only),
+.El
+.Pp
+are called
+.Li cbtw ,
+.Li cwtl ,
+.Li cwtd ,
+.Li cltd ,
+.Li cltq ,
+and
+.Li cqto
+in AT&T naming.
+.Li as
+accepts either naming for these instructions.
+.Pp
+Far call/jump instructions are
+.Li lcall
+and
+.Li ljmp
+in AT&T syntax, but are
+.Li call far
+and
+.Li jump far
+in Intel convention.
+.Pp
+.Ss  Register Naming
+Register operands are always prefixed with
+.Li % .
+The 80386 registers consist of
+.Pp
+.Bl -bullet
+.It
+the 8 32-bit registers
+.Li %eax
+(the accumulator),
+.Li %ebx ,
+.Li %ecx ,
+.Li %edx ,
+.Li %edi ,
+.Li %esi ,
+.Li %ebp
+(the frame pointer), and
+.Li %esp
+(the stack pointer).
+.Pp
+.It
+the 8 16-bit low-ends of these:
+.Li %ax ,
+.Li %bx ,
+.Li %cx ,
+.Li %dx ,
+.Li %di ,
+.Li %si ,
+.Li %bp ,
+and
+.Li %sp .
+.Pp
+.It
+the 8 8-bit registers:
+.Li %ah ,
+.Li %al ,
+.Li %bh ,
+.Li %bl ,
+.Li %ch ,
+.Li %cl ,
+.Li %dh ,
+and
+.Li %dl
+(These are the high-bytes and low-bytes of
+.Li %ax ,
+.Li %bx ,
+.Li %cx ,
+and
+.Li %dx )
+.Pp
+.It
+the 6 section registers
+.Li %cs
+(code section),
+.Li %ds
+(data section),
+.Li %ss
+(stack section),
+.Li %es ,
+.Li %fs ,
+and
+.Li %gs .
+.Pp
+.It
+the 3 processor control registers
+.Li %cr0 ,
+.Li %cr2 ,
+and
+.Li %cr3 .
+.Pp
+.It
+the 6 debug registers
+.Li %db0 ,
+.Li %db1 ,
+.Li %db2 ,
+.Li %db3 ,
+.Li %db6 ,
+and
+.Li %db7 .
+.Pp
+.It
+the 2 test registers
+.Li %tr6
+and
+.Li %tr7 .
+.Pp
+.It
+the 8 floating point register stack
+.Li %st
+or equivalently
+.Li %st(0) ,
+.Li %st(1) ,
+.Li %st(2) ,
+.Li %st(3) ,
+.Li %st(4) ,
+.Li %st(5) ,
+.Li %st(6) ,
+and
+.Li %st(7) .
+These registers are overloaded by 8 MMX registers
+.Li %mm0 ,
+.Li %mm1 ,
+.Li %mm2 ,
+.Li %mm3 ,
+.Li %mm4 ,
+.Li %mm5 ,
+.Li %mm6
+and
+.Li %mm7 .
+.Pp
+.It
+the 8 SSE registers registers
+.Li %xmm0 ,
+.Li %xmm1 ,
+.Li %xmm2 ,
+.Li %xmm3 ,
+.Li %xmm4 ,
+.Li %xmm5 ,
+.Li %xmm6
+and
+.Li %xmm7 .
+.El
+.Pp
+The AMD x86-64 architecture extends the register set by:
+.Pp
+.Bl -bullet
+.It
+enhancing the 8 32-bit registers to 64-bit:
+.Li %rax
+(the accumulator),
+.Li %rbx ,
+.Li %rcx ,
+.Li %rdx ,
+.Li %rdi ,
+.Li %rsi ,
+.Li %rbp
+(the frame pointer),
+.Li %rsp
+(the stack pointer)
+.Pp
+.It
+the 8 extended registers
+.Li %r8
+--
+.Li %r15 .
+.Pp
+.It
+the 8 32-bit low ends of the extended registers:
+.Li %r8d
+--
+.Li %r15d
+.Pp
+.It
+the 8 16-bit low ends of the extended registers:
+.Li %r8w
+--
+.Li %r15w
+.Pp
+.It
+the 8 8-bit low ends of the extended registers:
+.Li %r8b
+--
+.Li %r15b
+.Pp
+.It
+the 4 8-bit registers:
+.Li %sil ,
+.Li %dil ,
+.Li %bpl ,
+.Li %spl .
+.Pp
+.It
+the 8 debug registers:
+.Li %db8
+--
+.Li %db15 .
+.Pp
+.It
+the 8 SSE registers:
+.Li %xmm8
+--
+.Li %xmm15 .
+.El
+.Pp
+.Ss  Instruction Prefixes
+Instruction prefixes are used to modify the following instruction. They are
+used to repeat string instructions, to provide section overrides, to perform
+bus lock operations, and to change operand and address sizes. (Most instructions
+that normally operate on 32-bit operands will use 16-bit operands if the instruction
+has an \(lqoperand size\(rq prefix.) Instruction prefixes are best written on the
+same line as the instruction they act upon. For example, the
+.Li scas
+(scan string) instruction is repeated with:
+.Pp
+.Bd -literal -offset indent
+        repne scas %es:(%edi),%al
+.Ed
+.Pp
+You may also place prefixes on the lines immediately preceding the instruction,
+but this circumvents checks that
+.Li as
+does with prefixes, and will not work with all prefixes.
+.Pp
+Here is a list of instruction prefixes:
+.Pp
+.Bl -bullet
+.It
+Section override prefixes
+.Li cs ,
+.Li ds ,
+.Li ss ,
+.Li es ,
+.Li fs ,
+.Li gs .
+These are automatically added by specifying using the
+.Va section
+:
+.Va memory-operand
+form for memory references.
+.Pp
+.It
+Operand/Address size prefixes
+.Li data16
+and
+.Li addr16
+change 32-bit operands/addresses into 16-bit operands/addresses, while
+.Li data32
+and
+.Li addr32
+change 16-bit ones (in a
+.Li .code16
+section) into 32-bit operands/addresses. These prefixes
+.Em must
+appear on the same line of code as the instruction they modify. For example,
+in a 16-bit
+.Li .code16
+section, you might write:
+.Pp
+.Bd -literal -offset indent
+        addr32 jmpl *(%ebx)
+.Ed
+.Pp
+.It
+The bus lock prefix
+.Li lock
+inhibits interrupts during execution of the instruction it precedes. (This
+is only valid with certain instructions; see a 80386 manual for details).
+.Pp
+.It
+The wait for coprocessor prefix
+.Li wait
+waits for the coprocessor to complete the current instruction. This should
+never be needed for the 80386/80387 combination.
+.Pp
+.It
+The
+.Li rep ,
+.Li repe ,
+and
+.Li repne
+prefixes are added to string instructions to make them repeat
+.Li %ecx
+times (
+.Li %cx
+times if the current address size is 16-bits).
+.It
+The
+.Li rex
+family of prefixes is used by x86-64 to encode extensions to i386 instruction
+set. The
+.Li rex
+prefix has four bits --- an operand size overwrite (
+.Li 64 )
+used to change operand size from 32-bit to 64-bit and X, Y and Z extensions
+bits used to extend the register set.
+.Pp
+You may write the
+.Li rex
+prefixes directly. The
+.Li rex64xyz
+instruction emits
+.Li rex
+prefix with all the bits set. By omitting the
+.Li 64 ,
+.Li x ,
+.Li y
+or
+.Li z
+you may write other prefixes as well. Normally, there is no need to write
+the prefixes explicitly, since gas will automatically generate them based
+on the instruction operands.
+.El
+.Pp
+.Ss  Memory References
+An Intel syntax indirect memory reference of the form
+.Pp
+.Bd -literal -offset indent
+section:[base + index*scale + disp]
+.Ed
+.Pp
+is translated into the AT&T syntax
+.Pp
+.Bd -literal -offset indent
+section:disp(base, index, scale)
+.Ed
+.Pp
+where
+.Va base
+and
+.Va index
+are the optional 32-bit base and index registers,
+.Va disp
+is the optional displacement, and
+.Va scale ,
+taking the values 1, 2, 4, and 8, multiplies
+.Va index
+to calculate the address of the operand. If no
+.Va scale
+is specified,
+.Va scale
+is taken to be 1.
+.Va section
+specifies the optional section register for the memory operand, and may override
+the default section register (see a 80386 manual for section register defaults).
+Note that section overrides in AT&T syntax
+.Em must
+be preceded by a
+.Li % .
+If you specify a section override which coincides with the default section
+register,
+.Li as
+does
+.Em not
+output any section register override prefixes to assemble the given instruction.
+Thus, section overrides can be specified to emphasize which section register
+is used for a given memory operand.
+.Pp
+Here are some examples of Intel and AT&T style memory references:
+.Pp
+.Bl -tag -width Ds
+.It  AT&T: Li -4(%ebp), Intel: Li [ebp - 4]
+.Va base
+is
+.Li %ebp ;
+.Va disp
+is
+.Li -4 .
+.Va section
+is missing, and the default section is used (
+.Li %ss
+for addressing with
+.Li %ebp
+as the base register).
+.Va index ,
+.Va scale
+are both missing.
+.Pp
+.It  AT&T: Li foo(,%eax,4), Intel: Li [foo + eax*4]
+.Va index
+is
+.Li %eax
+(scaled by a
+.Va scale
+4);
+.Va disp
+is
+.Li foo .
+All other fields are missing. The section register here defaults to
+.Li %ds .
+.Pp
+.It  AT&T: Li foo(,1); Intel Li [foo]
+This uses the value pointed to by
+.Li foo
+as a memory operand. Note that
+.Va base
+and
+.Va index
+are both missing, but there is only
+.Em one
+.Li , .
+This is a syntactic exception.
+.Pp
+.It  AT&T: Li %gs:foo; Intel Li gs:foo
+This selects the contents of the variable
+.Li foo
+with section register
+.Va section
+being
+.Li %gs .
+.El
+.Pp
+Absolute (as opposed to PC relative) call and jump operands must be prefixed
+with
+.Li * .
+If no
+.Li *
+is specified,
+.Li as
+always chooses PC relative addressing for jump/call labels.
+.Pp
+Any instruction that has a memory operand, but no register operand,
+.Em must
+specify its size (byte, word, long, or quadruple) with an instruction mnemonic
+suffix (
+.Li b ,
+.Li w ,
+.Li l
+or
+.Li q ,
+respectively).
+.Pp
+The x86-64 architecture adds an RIP (instruction pointer relative) addressing.
+This addressing mode is specified by using
+.Li rip
+as a base register. Only constant offsets are valid. For example:
+.Pp
+.Bl -tag -width Ds
+.It  AT&T: Li 1234(%rip), Intel: Li [rip + 1234]
+Points to the address 1234 bytes past the end of the current instruction.
+.Pp
+.It  AT&T: Li symbol(%rip), Intel: Li [rip + symbol]
+Points to the
+.Li symbol
+in RIP relative way, this is shorter than the default absolute addressing.
+.El
+.Pp
+Other addressing modes remain unchanged in x86-64 architecture, except registers
+used are 64-bit instead of 32-bit.
+.Pp
+.Ss  Handling of Jump Instructions
+Jump instructions are always optimized to use the smallest possible displacements.
+This is accomplished by using byte (8-bit) displacement jumps whenever the
+target is sufficiently close. If a byte displacement is insufficient a long
+displacement is used. We do not support word (16-bit) displacement jumps in
+32-bit mode (i.e. prefixing the jump instruction with the
+.Li data16
+instruction prefix), since the 80386 insists upon masking
+.Li %eip
+to 16 bits after the word displacement is added. (See alsosee Section
+.Dq i386-Arch )
+.Pp
+Note that the
+.Li jcxz ,
+.Li jecxz ,
+.Li loop ,
+.Li loopz ,
+.Li loope ,
+.Li loopnz
+and
+.Li loopne
+instructions only come in byte displacements, so that if you use these instructions
+(
+.Li gcc
+does not use them) you may get an error message (and incorrect code). The
+AT&T 80386 assembler tries to get around this problem by expanding
+.Li jcxz foo
+to
+.Pp
+.Bd -literal -offset indent
+         jcxz cx_zero
+         jmp cx_nonzero
+cx_zero: jmp foo
+cx_nonzero:
+.Ed
+.Pp
+.Ss  Floating Point
+All 80387 floating point types except packed BCD are supported. (BCD support
+may be added without much difficulty). These data types are 16-, 32-, and
+64- bit integers, and single (32-bit), double (64-bit), and extended (80-bit)
+precision floating point. Each supported type has an instruction mnemonic
+suffix and a constructor associated with it. Instruction mnemonic suffixes
+specify the operand's data type. Constructors build these data types into
+memory.
+.Pp
+.Bl -bullet
+.It
+Floating point constructors are
+.Li .float
+or
+.Li .single ,
+.Li .double ,
+and
+.Li .tfloat
+for 32-, 64-, and 80-bit formats. These correspond to instruction mnemonic
+suffixes
+.Li s ,
+.Li l ,
+and
+.Li t .
+.Li t
+stands for 80-bit (ten byte) real. The 80387 only supports this format via
+the
+.Li fldt
+(load 80-bit real to stack top) and
+.Li fstpt
+(store 80-bit real and pop stack) instructions.
+.Pp
+.It
+Integer constructors are
+.Li .word ,
+.Li .long
+or
+.Li .int ,
+and
+.Li .quad
+for the 16-, 32-, and 64-bit integer formats. The corresponding instruction
+mnemonic suffixes are
+.Li s
+(single),
+.Li l
+(long), and
+.Li q
+(quad). As with the 80-bit real format, the 64-bit
+.Li q
+format is only present in the
+.Li fildq
+(load quad integer to stack top) and
+.Li fistpq
+(store quad integer and pop stack) instructions.
+.El
+.Pp
+Register to register operations should not use instruction mnemonic suffixes.
+.Li fstl %st, %st(1)
+will give a warning, and be assembled as if you wrote
+.Li fst %st, %st(1) ,
+since all register to register operations use 80-bit floating point operands.
+(Contrast this with
+.Li fstl %st, mem ,
+which converts
+.Li %st
+from 80-bit to 64-bit floating point format, then stores the result in the
+4 byte location
+.Li mem )
+.Pp
+.Ss  Intel's MMX and AMD's 3DNow! SIMD Operations
+.Li as
+supports Intel's MMX instruction set (SIMD instructions for integer data),
+available on Intel's Pentium MMX processors and Pentium II processors, AMD's
+K6 and K6-2 processors, Cyrix' M2 processor, and probably others. It also
+supports AMD's 3DNow! instruction set (SIMD instructions for 32-bit floating
+point data) available on AMD's K6-2 processor and possibly others in the future.
+.Pp
+Currently,
+.Li as
+does not support Intel's floating point SIMD, Katmai (KNI).
+.Pp
+The eight 64-bit MMX operands, also used by 3DNow!, are called
+.Li %mm0 ,
+.Li %mm1 ,
+\&...
+.Li %mm7 .
+They contain eight 8-bit integers, four 16-bit integers, two 32-bit integers,
+one 64-bit integer, or two 32-bit floating point values. The MMX registers
+cannot be used at the same time as the floating point stack.
+.Pp
+See Intel and AMD documentation, keeping in mind that the operand order in
+instructions is reversed from the Intel syntax.
+.Pp
+.Ss  Writing 16-bit Code
+While
+.Li as
+normally writes only \(lqpure\(rq 32-bit i386 code or 64-bit x86-64 code depending
+on the default configuration, it also supports writing code to run in real
+mode or in 16-bit protected mode code segments. To do this, put a
+.Li .code16
+or
+.Li .code16gcc
+directive before the assembly language instructions to be run in 16-bit mode.
+You can switch
+.Li as
+back to writing normal 32-bit code with the
+.Li .code32
+directive.
+.Pp
+.Li .code16gcc
+provides experimental support for generating 16-bit code from gcc, and differs
+from
+.Li .code16
+in that
+.Li call ,
+.Li ret ,
+.Li enter ,
+.Li leave ,
+.Li push ,
+.Li pop ,
+.Li pusha ,
+.Li popa ,
+.Li pushf ,
+and
+.Li popf
+instructions default to 32-bit size. This is so that the stack pointer is
+manipulated in the same way over function calls, allowing access to function
+parameters at the same stack offsets as in 32-bit mode.
+.Li .code16gcc
+also automatically adds address size prefixes where necessary to use the 32-bit
+addressing modes that gcc generates.
+.Pp
+The code which
+.Li as
+generates in 16-bit mode will not necessarily run on a 16-bit pre-80386 processor.
+To write code that runs on such a processor, you must refrain from using
+.Em any
+32-bit constructs which require
+.Li as
+to output address or operand size prefixes.
+.Pp
+Note that writing 16-bit code instructions by explicitly specifying a prefix
+or an instruction mnemonic suffix within a 32-bit code section generates different
+machine instructions than those generated for a 16-bit code segment. In a
+32-bit code section, the following code generates the machine opcode bytes
+.Li 66 6a 04 ,
+which pushes the value
+.Li 4
+onto the stack, decrementing
+.Li %esp
+by 2.
+.Pp
+.Bd -literal -offset indent
+        pushw $4
+.Ed
+.Pp
+The same code in a 16-bit code section would generate the machine opcode bytes
+.Li 6a 04
+(i.e., without the operand size prefix), which is correct since the processor
+default operand size is assumed to be 16 bits in a 16-bit code section.
+.Pp
+.Ss  AT&T Syntax bugs
+The UnixWare assembler, and probably other AT&T derived ix86 Unix assemblers,
+generate floating point instructions with reversed source and destination
+registers in certain cases. Unfortunately, gcc and possibly many other programs
+use this reversed syntax, so we're stuck with it.
+.Pp
+For example
+.Pp
+.Bd -literal -offset indent
+        fsub %st,%st(3)
+.Ed
+results in
+.Li %st(3)
+being updated to
+.Li %st - %st(3)
+rather than the expected
+.Li %st(3) - %st .
+This happens with all the non-commutative arithmetic floating point operations
+with two register operands where the source register is
+.Li %st
+and the destination register is
+.Li %st(i) .
+.Pp
+.Ss  Specifying CPU Architecture
+.Li as
+may be told to assemble for a particular CPU (sub-)architecture with the
+.Li .arch Va cpu_type
+directive. This directive enables a warning when gas detects an instruction
+that is not supported on the CPU specified. The choices for
+.Va cpu_type
+are:
+.Pp
+.TS
+l l l l.
+
+i8086	 i186	 i286	 i386
+i486	 i586	 i686	 pentium
+pentiumpro	 pentiumii	 pentiumiii	 pentium4
+prescott	 nocona	 core	 core2
+amdfam10
+k6	 athlon	 sledgehammer	 k8
+\&.mmx	 .sse	 .sse2	 .sse3
+\&.ssse3	 .sse4.1	 .sse4.2	 .sse4
+\&.sse4a	 .3dnow	 .3dnowa	 .padlock
+\&.pacifica	 .svme	 .abm
+.TE
+.Pp
+Apart from the warning, there are only two other effects on
+.Li as
+operation; Firstly, if you specify a CPU other than
+.Li i486 ,
+then shift by one instructions such as
+.Li sarl $1, %eax
+will automatically use a two byte opcode sequence. The larger three byte opcode
+sequence is used on the 486 (and when no architecture is specified) because
+it executes faster on the 486. Note that you can explicitly request the two
+byte opcode by writing
+.Li sarl %eax .
+Secondly, if you specify
+.Li i8086 ,
+.Li i186 ,
+or
+.Li i286 ,
+.Em and
+.Li .code16
+or
+.Li .code16gcc
+then byte offset conditional jumps will be promoted when necessary to a two
+instruction sequence consisting of a conditional jump of the opposite sense
+around an unconditional jump to the target.
+.Pp
+Following the CPU architecture (but not a sub-architecture, which are those
+starting with a dot), you may specify
+.Li jumps
+or
+.Li nojumps
+to control automatic promotion of conditional jumps.
+.Li jumps
+is the default, and enables jump promotion; All external jumps will be of
+the long variety, and file-local jumps will be promoted as necessary. (see Section
+.Dq i386-Jumps )
+.Li nojumps
+leaves external conditional jumps as byte offset jumps, and warns about file-local
+conditional jumps that
+.Li as
+promotes. Unconditional jumps are treated as for
+.Li jumps .
+.Pp
+For example
+.Pp
+.Bd -literal -offset indent
+ .arch i8086,nojumps
+.Ed
+.Pp
+.Ss  Notes
+There is some trickery concerning the
+.Li mul
+and
+.Li imul
+instructions that deserves mention. The 16-, 32-, 64- and 128-bit expanding
+multiplies (base opcode
+.Li 0xf6 ;
+extension 4 for
+.Li mul
+and 5 for
+.Li imul )
+can be output only in the one operand form. Thus,
+.Li imul %ebx, %eax
+does
+.Em not
+select the expanding multiply; the expanding multiply would clobber the
+.Li %edx
+register, and this would confuse
+.Li gcc
+output. Use
+.Li imul %ebx
+to get the 64-bit product in
+.Li %edx:%eax .
+.Pp
+We have added a two operand form of
+.Li imul
+when the first operand is an immediate mode expression and the second operand
+is a register. This is just a shorthand, so that, multiplying
+.Li %eax
+by 69, for example, can be done with
+.Li imul $69, %eax
+rather than
+.Li imul $69, %eax, %eax .
+.Pp
+.Sh  IA-64 Dependent Features
+.Ss  Options
+.Bl -tag -width Ds
+.It  -mconstant-gp
+This option instructs the assembler to mark the resulting object file as using
+the \(lqconstant GP\(rq model. With this model, it is assumed that the entire program
+uses a single global pointer (GP) value. Note that this option does not in
+any fashion affect the machine code emitted by the assembler. All it does
+is turn on the EF_IA_64_CONS_GP flag in the ELF file header.
+.Pp
+.It  -mauto-pic
+This option instructs the assembler to mark the resulting object file as using
+the \(lqconstant GP without function descriptor\(rq data model. This model is like
+the \(lqconstant GP\(rq model, except that it additionally does away with function
+descriptors. What this means is that the address of a function refers directly
+to the function's code entry-point. Normally, such an address would refer
+to a function descriptor, which contains both the code entry-point and the
+GP-value needed by the function. Note that this option does not in any fashion
+affect the machine code emitted by the assembler. All it does is turn on the
+EF_IA_64_NOFUNCDESC_CONS_GP flag in the ELF file header.
+.Pp
+.It  -milp32
+.It  -milp64
+.It  -mlp64
+.It  -mp64
+These options select the data model. The assembler defaults to
+.Li -mlp64
+(LP64 data model).
+.Pp
+.It  -mle
+.It  -mbe
+These options select the byte order. The
+.Li -mle
+option selects little-endian byte order (default) and
+.Li -mbe
+selects big-endian byte order. Note that IA-64 machine code always uses little-endian
+byte order.
+.Pp
+.It  -mtune=itanium1
+.It  -mtune=itanium2
+Tune for a particular IA-64 CPU,
+.Va itanium1
+or
+.Va itanium2 .
+The default is
+.Va itanium2 .
+.Pp
+.It  -munwind-check=warning
+.It  -munwind-check=error
+These options control what the assembler will do when performing consistency
+checks on unwind directives.
+.Li -munwind-check=warning
+will make the assembler issue a warning when an unwind directive check fails.
+This is the default.
+.Li -munwind-check=error
+will make the assembler issue an error when an unwind directive check fails.
+.Pp
+.It  -mhint.b=ok
+.It  -mhint.b=warning
+.It  -mhint.b=error
+These options control what the assembler will do when the
+.Li hint.b
+instruction is used.
+.Li -mhint.b=ok
+will make the assembler accept
+.Li hint.b .
+.Li -mint.b=warning
+will make the assembler issue a warning when
+.Li hint.b
+is used.
+.Li -mhint.b=error
+will make the assembler treat
+.Li hint.b
+as an error, which is the default.
+.Pp
+.It  -x
+.It  -xexplicit
+These options turn on dependency violation checking.
+.Pp
+.It  -xauto
+This option instructs the assembler to automatically insert stop bits where
+necessary to remove dependency violations. This is the default mode.
+.Pp
+.It  -xnone
+This option turns off dependency violation checking.
+.Pp
+.It  -xdebug
+This turns on debug output intended to help tracking down bugs in the dependency
+violation checker.
+.Pp
+.It  -xdebugn
+This is a shortcut for -xnone -xdebug.
+.Pp
+.It  -xdebugx
+This is a shortcut for -xexplicit -xdebug.
+.Pp
+.El
+.Ss  Syntax
+The assembler syntax closely follows the IA-64 Assembly Language Reference
+Guide.
+.Pp
+.Em  Special Characters
+.Pp
+.Li //
+is the line comment token.
+.Pp
+.Li ;
+can be used instead of a newline to separate statements.
+.Pp
+.Em  Register Names
+.Pp
+The 128 integer registers are referred to as
+.Li r Va n .
+The 128 floating-point registers are referred to as
+.Li f Va n .
+The 128 application registers are referred to as
+.Li ar Va n .
+The 128 control registers are referred to as
+.Li cr Va n .
+The 64 one-bit predicate registers are referred to as
+.Li p Va n .
+The 8 branch registers are referred to as
+.Li b Va n .
+In addition, the assembler defines a number of aliases:
+.Li gp
+(
+.Li r1 ) ,
+.Li sp
+(
+.Li r12 ) ,
+.Li rp
+(
+.Li b0 ) ,
+.Li ret0
+(
+.Li r8 ) ,
+.Li ret1
+(
+.Li r9 ) ,
+.Li ret2
+(
+.Li r10 ) ,
+.Li ret3
+(
+.Li r9 ) ,
+.Li farg Va n
+(
+.Li f8+ Va n ) ,
+and
+.Li fret Va n
+(
+.Li f8+ Va n ) .
+.Pp
+For convenience, the assembler also defines aliases for all named application
+and control registers. For example,
+.Li ar.bsp
+refers to the register backing store pointer (
+.Li ar17 ) .
+Similarly,
+.Li cr.eoi
+refers to the end-of-interrupt register (
+.Li cr67 ) .
+.Pp
+.Em  IA-64 Processor-Status-Register (PSR) Bit Names
+.Pp
+The assembler defines bit masks for each of the bits in the IA-64 processor
+status register. For example,
+.Li psr.ic
+corresponds to a value of 0x2000. These masks are primarily intended for use
+with the
+.Li ssm
+/
+.Li sum
+and
+.Li rsm
+/
+.Li rum
+instructions, but they can be used anywhere else where an integer constant
+is expected.
+.Pp
+.Ss  Opcodes
+For detailed information on the IA-64 machine instruction set, see the
+.Lk http://developer.intel.com/design/itanium/arch_spec.htm .
+.Pp
+.Sh  MIPS Dependent Features
+GNU
+.Li as
+for mips architectures supports several different mips processors, and MIPS
+ISA levels I through V, MIPS32, and MIPS64. For information about the mips
+instruction set, see
+.Em MIPS RISC Architecture ,
+by Kane and Heindrich (Prentice-Hall). For an overview of mips assembly conventions,
+see \(lqAppendix D: Assembly Language Programming\(rq in the same work.
+.Pp
+.Ss  Assembler options
+The mips configurations of GNU
+.Li as
+support these special options:
+.Pp
+.Bl -tag -width Ds
+.It  -G Va num
+This option sets the largest size of an object that can be referenced implicitly
+with the
+.Li gp
+register. It is only accepted for targets that use ecoff format. The default
+value is 8.
+.Pp
+.It  -EB
+.It  -EL
+Any mips configuration of
+.Li as
+can select big-endian or little-endian output at run time (unlike the other
+GNU development tools, which must be configured for one or the other). Use
+.Li -EB
+to select big-endian output, and
+.Li -EL
+for little-endian.
+.Pp
+.It  -KPIC
+Generate SVR4-style PIC. This option tells the assembler to generate SVR4-style
+position-independent macro expansions. It also tells the assembler to mark
+the output file as PIC.
+.Pp
+.It  -mvxworks-pic
+Generate VxWorks PIC. This option tells the assembler to generate VxWorks-style
+position-independent macro expansions.
+.Pp
+.It  -mips1
+.It  -mips2
+.It  -mips3
+.It  -mips4
+.It  -mips5
+.It  -mips32
+.It  -mips32r2
+.It  -mips64
+.It  -mips64r2
+Generate code for a particular MIPS Instruction Set Architecture level.
+.Li -mips1
+corresponds to the r2000 and r3000 processors,
+.Li -mips2
+to the r6000 processor,
+.Li -mips3
+to the r4000 processor, and
+.Li -mips4
+to the r8000 and r10000 processors.
+.Li -mips5 ,
+.Li -mips32 ,
+.Li -mips32r2 ,
+.Li -mips64 ,
+and
+.Li -mips64r2
+correspond to generic MIPS V, MIPS32, MIPS32 Release 2, MIPS64, and MIPS64
+Release 2 ISA processors, respectively. You can also switch instruction sets
+during the assembly; see MIPS ISA, Directives to override the ISA level.
+.Pp
+.It  -mgp32
+.It  -mfp32
+Some macros have different expansions for 32-bit and 64-bit registers. The
+register sizes are normally inferred from the ISA and ABI, but these flags
+force a certain group of registers to be treated as 32 bits wide at all times.
+.Li -mgp32
+controls the size of general-purpose registers and
+.Li -mfp32
+controls the size of floating-point registers.
+.Pp
+The
+.Li .set gp=32
+and
+.Li .set fp=32
+directives allow the size of registers to be changed for parts of an object.
+The default value is restored by
+.Li .set gp=default
+and
+.Li .set fp=default .
+.Pp
+On some MIPS variants there is a 32-bit mode flag; when this flag is set,
+64-bit instructions generate a trap. Also, some 32-bit OSes only save the
+32-bit registers on a context switch, so it is essential never to use the
+64-bit registers.
+.Pp
+.It  -mgp64
+.It  -mfp64
+Assume that 64-bit registers are available. This is provided in the interests
+of symmetry with
+.Li -mgp32
+and
+.Li -mfp32 .
+.Pp
+The
+.Li .set gp=64
+and
+.Li .set fp=64
+directives allow the size of registers to be changed for parts of an object.
+The default value is restored by
+.Li .set gp=default
+and
+.Li .set fp=default .
+.Pp
+.It  -mips16
+.It  -no-mips16
+Generate code for the MIPS 16 processor. This is equivalent to putting
+.Li .set mips16
+at the start of the assembly file.
+.Li -no-mips16
+turns off this option.
+.Pp
+.It  -msmartmips
+.It  -mno-smartmips
+Enables the SmartMIPS extensions to the MIPS32 instruction set, which provides
+a number of new instructions which target smartcard and cryptographic applications.
+This is equivalent to putting
+.Li .set smartmips
+at the start of the assembly file.
+.Li -mno-smartmips
+turns off this option.
+.Pp
+.It  -mips3d
+.It  -no-mips3d
+Generate code for the MIPS-3D Application Specific Extension. This tells the
+assembler to accept MIPS-3D instructions.
+.Li -no-mips3d
+turns off this option.
+.Pp
+.It  -mdmx
+.It  -no-mdmx
+Generate code for the MDMX Application Specific Extension. This tells the
+assembler to accept MDMX instructions.
+.Li -no-mdmx
+turns off this option.
+.Pp
+.It  -mdsp
+.It  -mno-dsp
+Generate code for the DSP Release 1 Application Specific Extension. This tells
+the assembler to accept DSP Release 1 instructions.
+.Li -mno-dsp
+turns off this option.
+.Pp
+.It  -mdspr2
+.It  -mno-dspr2
+Generate code for the DSP Release 2 Application Specific Extension. This option
+implies -mdsp. This tells the assembler to accept DSP Release 2 instructions.
+.Li -mno-dspr2
+turns off this option.
+.Pp
+.It  -mmt
+.It  -mno-mt
+Generate code for the MT Application Specific Extension. This tells the assembler
+to accept MT instructions.
+.Li -mno-mt
+turns off this option.
+.Pp
+.It  -mfix7000
+.It  -mno-fix7000
+Cause nops to be inserted if the read of the destination register of an mfhi
+or mflo instruction occurs in the following two instructions.
+.Pp
+.It  -mfix-vr4120
+.It  -no-mfix-vr4120
+Insert nops to work around certain VR4120 errata. This option is intended
+to be used on GCC-generated code: it is not designed to catch all problems
+in hand-written assembler code.
+.Pp
+.It  -mfix-vr4130
+.It  -no-mfix-vr4130
+Insert nops to work around the VR4130
+.Li mflo
+/
+.Li mfhi
+errata.
+.Pp
+.It  -m4010
+.It  -no-m4010
+Generate code for the LSI r4010 chip. This tells the assembler to accept the
+r4010 specific instructions (
+.Li addciu ,
+.Li ffc ,
+etc.), and to not schedule
+.Li nop
+instructions around accesses to the
+.Li HI
+and
+.Li LO
+registers.
+.Li -no-m4010
+turns off this option.
+.Pp
+.It  -m4650
+.It  -no-m4650
+Generate code for the MIPS r4650 chip. This tells the assembler to accept
+the
+.Li mad
+and
+.Li madu
+instruction, and to not schedule
+.Li nop
+instructions around accesses to the
+.Li HI
+and
+.Li LO
+registers.
+.Li -no-m4650
+turns off this option.
+.Pp
+.It  -m3900
+.It  -no-m3900
+.It  -m4100
+.It  -no-m4100
+For each option
+.Li -m Va nnnn ,
+generate code for the MIPS r
+.Va nnnn
+chip. This tells the assembler to accept instructions specific to that chip,
+and to schedule for that chip's hazards.
+.Pp
+.It  -march= Va cpu
+Generate code for a particular MIPS cpu. It is exactly equivalent to
+.Li -m Va cpu ,
+except that there are more value of
+.Va cpu
+understood. Valid
+.Va cpu
+value are:
+.Pp
+.Qo
+2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, vr4181, 4300, 4400,
+4600, 4650, 5000, rm5200, rm5230, rm5231, rm5261, rm5721, vr5400, vr5500,
+6000, rm7000, 8000, rm9000, 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem,
+4kep, 4ksd, m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf,
+34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a
+.Qc
+.Pp
+.It  -mtune= Va cpu
+Schedule and tune for a particular MIPS cpu. Valid
+.Va cpu
+values are identical to
+.Li -march= Va cpu .
+.Pp
+.It  -mabi= Va abi
+Record which ABI the source code uses. The recognized arguments are:
+.Li 32 ,
+.Li n32 ,
+.Li o64 ,
+.Li 64
+and
+.Li eabi .
+.Pp
+.It  -msym32
+.It  -mno-sym32
+Equivalent to adding
+.Li .set sym32
+or
+.Li .set nosym32
+to the beginning of the assembler input.See Section
+.Dq MIPS symbol sizes .
+.Pp
+.It  -nocpp
+This option is ignored. It is accepted for command-line compatibility with
+other assemblers, which use it to turn off C style preprocessing. With GNU
+.Li as ,
+there is no need for
+.Li -nocpp ,
+because the GNU assembler itself never runs the C preprocessor.
+.Pp
+.It  --construct-floats
+.It  --no-construct-floats
+The
+.Li --no-construct-floats
+option disables the construction of double width floating point constants
+by loading the two halves of the value into the two single width floating
+point registers that make up the double width register. This feature is useful
+if the processor support the FR bit in its status register, and this bit is
+known (by the programmer) to be set. This bit prevents the aliasing of the
+double width register by the single width registers.
+.Pp
+By default
+.Li --construct-floats
+is selected, allowing construction of these floating point constants.
+.Pp
+.It  --trap
+.It  --no-break
+.Li as
+automatically macro expands certain division and multiplication instructions
+to check for overflow and division by zero. This option causes
+.Li as
+to generate code to take a trap exception rather than a break exception when
+an error is detected. The trap instructions are only supported at Instruction
+Set Architecture level 2 and higher.
+.Pp
+.It  --break
+.It  --no-trap
+Generate code to take a break exception rather than a trap exception when
+an error is detected. This is the default.
+.Pp
+.It  -mpdr
+.It  -mno-pdr
+Control generation of
+.Li .pdr
+sections. Off by default on IRIX, on elsewhere.
+.Pp
+.It  -mshared
+.It  -mno-shared
+When generating code using the Unix calling conventions (selected by
+.Li -KPIC
+or
+.Li -mcall_shared ) ,
+gas will normally generate code which can go into a shared library. The
+.Li -mno-shared
+option tells gas to generate code which uses the calling convention, but can
+not go into a shared library. The resulting code is slightly more efficient.
+This option only affects the handling of the
+.Li .cpload
+and
+.Li .cpsetup
+pseudo-ops.
+.El
+.Pp
+.Ss  MIPS ECOFF object code
+Assembling for a mips ecoff target supports some additional sections besides
+the usual
+.Li .text ,
+.Li .data
+and
+.Li .bss .
+The additional sections are
+.Li .rdata ,
+used for read-only data,
+.Li .sdata ,
+used for small data, and
+.Li .sbss ,
+used for small common objects.
+.Pp
+When assembling for ecoff, the assembler uses the
+.Li $gp
+(
+.Li $28 )
+register to form the address of a \(lqsmall object\(rq. Any object in the
+.Li .sdata
+or
+.Li .sbss
+sections is considered \(lqsmall\(rq in this sense. For external objects, or for objects
+in the
+.Li .bss
+section, you can use the
+.Li gcc
+.Li -G
+option to control the size of objects addressed via
+.Li $gp ;
+the default value is 8, meaning that a reference to any object eight bytes
+or smaller uses
+.Li $gp .
+Passing
+.Li -G 0
+to
+.Li as
+prevents it from using the
+.Li $gp
+register on the basis of object size (but the assembler uses
+.Li $gp
+for objects in
+.Li .sdata
+or
+.Li sbss
+in any case). The size of an object in the
+.Li .bss
+section is set by the
+.Li .comm
+or
+.Li .lcomm
+directive that defines it. The size of an external object may be set with
+the
+.Li .extern
+directive. For example,
+.Li .extern sym,4
+declares that the object at
+.Li sym
+is 4 bytes in length, whie leaving
+.Li sym
+otherwise undefined.
+.Pp
+Using small ecoff objects requires linker support, and assumes that the
+.Li $gp
+register is correctly initialized (normally done automatically by the startup
+code). mips ecoff assembly code must not modify the
+.Li $gp
+register.
+.Pp
+.Ss  Directives for debugging information
+mips ecoff
+.Li as
+supports several directives used for generating debugging information which
+are not support by traditional mips assemblers. These are
+.Li .def ,
+.Li .endef ,
+.Li .dim ,
+.Li .file ,
+.Li .scl ,
+.Li .size ,
+.Li .tag ,
+.Li .type ,
+.Li .val ,
+.Li .stabd ,
+.Li .stabn ,
+and
+.Li .stabs .
+The debugging information generated by the three
+.Li .stab
+directives can only be read by gdb, not by traditional mips debuggers (this
+enhancement is required to fully support C++ debugging). These directives
+are primarily used by compilers, not assembly language programmers!
+.Pp
+.Ss  Directives to override the size of symbols
+The n64 ABI allows symbols to have any 64-bit value. Although this provides
+a great deal of flexibility, it means that some macros have much longer expansions
+than their 32-bit counterparts. For example, the non-PIC expansion of
+.Li dla $4,sym
+is usually:
+.Pp
+.Bd -literal -offset indent
+lui     $4,%highest(sym)
+lui     $1,%hi(sym)
+daddiu  $4,$4,%higher(sym)
+daddiu  $1,$1,%lo(sym)
+dsll32  $4,$4,0
+daddu   $4,$4,$1
+.Ed
+.Pp
+whereas the 32-bit expansion is simply:
+.Pp
+.Bd -literal -offset indent
+lui     $4,%hi(sym)
+daddiu  $4,$4,%lo(sym)
+.Ed
+.Pp
+n64 code is sometimes constructed in such a way that all symbolic constants
+are known to have 32-bit values, and in such cases, it's preferable to use
+the 32-bit expansion instead of the 64-bit expansion.
+.Pp
+You can use the
+.Li .set sym32
+directive to tell the assembler that, from this point on, all expressions
+of the form
+.Li  Va symbol
+or
+.Li  Va symbol + Va offset
+have 32-bit values. For example:
+.Pp
+.Bd -literal -offset indent
+\&.set sym32
+dla     $4,sym
+lw      $4,sym+16
+sw      $4,sym+0x8000($4)
+.Ed
+.Pp
+will cause the assembler to treat
+.Li sym ,
+.Li sym+16
+and
+.Li sym+0x8000
+as 32-bit values. The handling of non-symbolic addresses is not affected.
+.Pp
+The directive
+.Li .set nosym32
+ends a
+.Li .set sym32
+block and reverts to the normal behavior. It is also possible to change the
+symbol size using the command-line options
+.Op -msym32
+and
+.Op -mno-sym32 .
+.Pp
+These options and directives are always accepted, but at present, they have
+no effect for anything other than n64.
+.Pp
+.Ss  Directives to override the ISA level
+GNU
+.Li as
+supports an additional directive to change the mips Instruction Set Architecture
+level on the fly:
+.Li .set mips Va n .
+.Va n
+should be a number from 0 to 5, or 32, 32r2, 64 or 64r2. The values other
+than 0 make the assembler accept instructions for the corresponding isa level,
+from that point on in the assembly.
+.Li .set mips Va n
+affects not only which instructions are permitted, but also how certain macros
+are expanded.
+.Li .set mips0
+restores the isa level to its original level: either the level you selected
+with command line options, or the default for your configuration. You can
+use this feature to permit specific mips3 instructions while assembling in
+32 bit mode. Use this directive with care!
+.Pp
+The
+.Li .set arch= Va cpu
+directive provides even finer control. It changes the effective CPU target
+and allows the assembler to use instructions specific to a particular CPU.
+All CPUs supported by the
+.Li -march
+command line option are also selectable by this directive. The original value
+is restored by
+.Li .set arch=default .
+.Pp
+The directive
+.Li .set mips16
+puts the assembler into MIPS 16 mode, in which it will assemble instructions
+for the MIPS 16 processor. Use
+.Li .set nomips16
+to return to normal 32 bit mode.
+.Pp
+Traditional mips assemblers do not support this directive.
+.Pp
+.Ss  Directives for extending MIPS 16 bit instructions
+By default, MIPS 16 instructions are automatically extended to 32 bits when
+necessary. The directive
+.Li .set noautoextend
+will turn this off. When
+.Li .set noautoextend
+is in effect, any 32 bit instruction must be explicitly extended with the
+.Li .e
+modifier (e.g.,
+.Li li.e $4,1000 ) .
+The directive
+.Li .set autoextend
+may be used to once again automatically extend instructions when necessary.
+.Pp
+This directive is only meaningful when in MIPS 16 mode. Traditional mips assemblers
+do not support this directive.
+.Pp
+.Ss  Directive to mark data as an instruction
+The
+.Li .insn
+directive tells
+.Li as
+that the following data is actually instructions. This makes a difference
+in MIPS 16 mode: when loading the address of a label which precedes instructions,
+.Li as
+automatically adds 1 to the value, so that jumping to the loaded address will
+do the right thing.
+.Pp
+.Ss  Directives to save and restore options
+The directives
+.Li .set push
+and
+.Li .set pop
+may be used to save and restore the current settings for all the options which
+are controlled by
+.Li .set .
+The
+.Li .set push
+directive saves the current settings on a stack. The
+.Li .set pop
+directive pops the stack and restores the settings.
+.Pp
+These directives can be useful inside an macro which must change an option
+such as the ISA level or instruction reordering but does not want to change
+the state of the code which invoked the macro.
+.Pp
+Traditional mips assemblers do not support these directives.
+.Pp
+.Ss  Directives to control generation of MIPS ASE instructions
+The directive
+.Li .set mips3d
+makes the assembler accept instructions from the MIPS-3D Application Specific
+Extension from that point on in the assembly. The
+.Li .set nomips3d
+directive prevents MIPS-3D instructions from being accepted.
+.Pp
+The directive
+.Li .set smartmips
+makes the assembler accept instructions from the SmartMIPS Application Specific
+Extension to the MIPS32 isa from that point on in the assembly. The
+.Li .set nosmartmips
+directive prevents SmartMIPS instructions from being accepted.
+.Pp
+The directive
+.Li .set mdmx
+makes the assembler accept instructions from the MDMX Application Specific
+Extension from that point on in the assembly. The
+.Li .set nomdmx
+directive prevents MDMX instructions from being accepted.
+.Pp
+The directive
+.Li .set dsp
+makes the assembler accept instructions from the DSP Release 1 Application
+Specific Extension from that point on in the assembly. The
+.Li .set nodsp
+directive prevents DSP Release 1 instructions from being accepted.
+.Pp
+The directive
+.Li .set dspr2
+makes the assembler accept instructions from the DSP Release 2 Application
+Specific Extension from that point on in the assembly. This dirctive implies
+.Li .set dsp .
+The
+.Li .set nodspr2
+directive prevents DSP Release 2 instructions from being accepted.
+.Pp
+The directive
+.Li .set mt
+makes the assembler accept instructions from the MT Application Specific Extension
+from that point on in the assembly. The
+.Li .set nomt
+directive prevents MT instructions from being accepted.
+.Pp
+Traditional mips assemblers do not support these directives.
+.Pp
+.Sh  PowerPC Dependent Features
+.Ss  Options
+The PowerPC chip family includes several successive levels, using the same
+core instruction set, but including a few additional instructions at each
+level. There are exceptions to this however. For details on what instructions
+each variant supports, please see the chip's architecture reference manual.
+.Pp
+The following table lists all available PowerPC options.
+.Pp
+.Bl -tag -width Ds
+.It  -mpwrx | -mpwr2
+Generate code for POWER/2 (RIOS2).
+.Pp
+.It  -mpwr
+Generate code for POWER (RIOS1)
+.Pp
+.It  -m601
+Generate code for PowerPC 601.
+.Pp
+.It  -mppc, -mppc32, -m603, -m604
+Generate code for PowerPC 603/604.
+.Pp
+.It  -m403, -m405
+Generate code for PowerPC 403/405.
+.Pp
+.It  -m440
+Generate code for PowerPC 440. BookE and some 405 instructions.
+.Pp
+.It  -m7400, -m7410, -m7450, -m7455
+Generate code for PowerPC 7400/7410/7450/7455.
+.Pp
+.It  -mppc64, -m620
+Generate code for PowerPC 620/625/630.
+.Pp
+.It  -me500, -me500x2
+Generate code for Motorola e500 core complex.
+.Pp
+.It  -mspe
+Generate code for Motorola SPE instructions.
+.Pp
+.It  -mppc64bridge
+Generate code for PowerPC 64, including bridge insns.
+.Pp
+.It  -mbooke64
+Generate code for 64-bit BookE.
+.Pp
+.It  -mbooke, mbooke32
+Generate code for 32-bit BookE.
+.Pp
+.It  -me300
+Generate code for PowerPC e300 family.
+.Pp
+.It  -maltivec
+Generate code for processors with AltiVec instructions.
+.Pp
+.It  -mpower4
+Generate code for Power4 architecture.
+.Pp
+.It  -mpower5
+Generate code for Power5 architecture.
+.Pp
+.It  -mpower6
+Generate code for Power6 architecture.
+.Pp
+.It  -mcell
+Generate code for Cell Broadband Engine architecture.
+.Pp
+.It  -mcom
+Generate code Power/PowerPC common instructions.
+.Pp
+.It  -many
+Generate code for any architecture (PWR/PWRX/PPC).
+.Pp
+.It  -mregnames
+Allow symbolic names for registers.
+.Pp
+.It  -mno-regnames
+Do not allow symbolic names for registers.
+.Pp
+.It  -mrelocatable
+Support for GCC's -mrelocatable option.
+.Pp
+.It  -mrelocatable-lib
+Support for GCC's -mrelocatable-lib option.
+.Pp
+.It  -memb
+Set PPC_EMB bit in ELF flags.
+.Pp
+.It  -mlittle, -mlittle-endian
+Generate code for a little endian machine.
+.Pp
+.It  -mbig, -mbig-endian
+Generate code for a big endian machine.
+.Pp
+.It  -msolaris
+Generate code for Solaris.
+.Pp
+.It  -mno-solaris
+Do not generate code for Solaris.
+.El
+.Pp
+.Ss  PowerPC Assembler Directives
+A number of assembler directives are available for PowerPC. The following
+table is far from complete.
+.Pp
+.Bl -tag -width Ds
+.It  .machine "string"
+This directive allows you to change the machine for which code is generated.
+.Li "string"
+may be any of the -m cpu selection options (without the -m) enclosed in double
+quotes,
+.Li "push" ,
+or
+.Li "pop" .
+.Li .machine "push"
+saves the currently selected cpu, which may be restored with
+.Li .machine "pop" .
+.El
+.Pp
+.Sh  SPARC Dependent Features
+.Ss  Options
+The SPARC chip family includes several successive levels, using the same core
+instruction set, but including a few additional instructions at each level.
+There are exceptions to this however. For details on what instructions each
+variant supports, please see the chip's architecture reference manual.
+.Pp
+By default,
+.Li as
+assumes the core instruction set (SPARC v6), but \(lqbumps\(rq the architecture level
+as needed: it switches to successively higher architectures as it encounters
+instructions that only exist in the higher levels.
+.Pp
+If not configured for SPARC v9 (
+.Li sparc64-*-* )
+GAS will not bump passed sparclite by default, an option must be passed to
+enable the v9 instructions.
+.Pp
+GAS treats sparclite as being compatible with v8, unless an architecture is
+explicitly requested. SPARC v9 is always incompatible with sparclite.
+.Pp
+.Bl -tag -width Ds
+.It  -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
+.It  -Av8plus | -Av8plusa | -Av9 | -Av9a
+Use one of the
+.Li -A
+options to select one of the SPARC architectures explicitly. If you select
+an architecture explicitly,
+.Li as
+reports a fatal error if it encounters an instruction or feature requiring
+an incompatible or higher level.
+.Pp
+.Li -Av8plus
+and
+.Li -Av8plusa
+select a 32 bit environment.
+.Pp
+.Li -Av9
+and
+.Li -Av9a
+select a 64 bit environment and are not available unless GAS is explicitly
+configured with 64 bit environment support.
+.Pp
+.Li -Av8plusa
+and
+.Li -Av9a
+enable the SPARC V9 instruction set with UltraSPARC extensions.
+.Pp
+.It  -xarch=v8plus | -xarch=v8plusa
+For compatibility with the Solaris v9 assembler. These options are equivalent
+to -Av8plus and -Av8plusa, respectively.
+.Pp
+.It  -bump
+Warn whenever it is necessary to switch to another level. If an architecture
+level is explicitly requested, GAS will not issue warnings until that level
+is reached, and will then bump the level as required (except between incompatible
+levels).
+.Pp
+.It  -32 | -64
+Select the word size, either 32 bits or 64 bits. These options are only available
+with the ELF object file format, and require that the necessary BFD support
+has been included.
+.El
+.Pp
+.Ss  Enforcing aligned data
+SPARC GAS normally permits data to be misaligned. For example, it permits
+the
+.Li .long
+pseudo-op to be used on a byte boundary. However, the native SunOS and Solaris
+assemblers issue an error when they see misaligned data.
+.Pp
+You can use the
+.Li --enforce-aligned-data
+option to make SPARC GAS also issue an error about misaligned data, just as
+the SunOS and Solaris assemblers do.
+.Pp
+The
+.Li --enforce-aligned-data
+option is not the default because gcc issues misaligned data pseudo-ops when
+it initializes certain packed data structures (structures defined using the
+.Li packed
+attribute). You may have to assemble with GAS in order to initialize packed
+data structures in your own code.
+.Pp
+.Ss  Floating Point
+The Sparc uses ieee floating-point numbers.
+.Pp
+.Ss  Sparc Machine Directives
+The Sparc version of
+.Li as
+supports the following additional machine directives:
+.Pp
+.Bl -tag -width Ds
+.It  .align
+This must be followed by the desired alignment in bytes.
+.Pp
+.It  .common
+This must be followed by a symbol name, a positive number, and
+.Li "bss" .
+This behaves somewhat like
+.Li .comm ,
+but the syntax is different.
+.Pp
+.It  .half
+This is functionally identical to
+.Li .short .
+.Pp
+.It  .nword
+On the Sparc, the
+.Li .nword
+directive produces native word sized value, ie. if assembling with -32 it
+is equivalent to
+.Li .word ,
+if assembling with -64 it is equivalent to
+.Li .xword .
+.Pp
+.It  .proc
+This directive is ignored. Any text following it on the same line is also
+ignored.
+.Pp
+.It  .register
+This directive declares use of a global application or system register. It
+must be followed by a register name %g2, %g3, %g6 or %g7, comma and the symbol
+name for that register. If symbol name is
+.Li #scratch ,
+it is a scratch register, if it is
+.Li #ignore ,
+it just suppresses any errors about using undeclared global register, but
+does not emit any information about it into the object file. This can be useful
+e.g. if you save the register before use and restore it after.
+.Pp
+.It  .reserve
+This must be followed by a symbol name, a positive number, and
+.Li "bss" .
+This behaves somewhat like
+.Li .lcomm ,
+but the syntax is different.
+.Pp
+.It  .seg
+This must be followed by
+.Li "text" ,
+.Li "data" ,
+or
+.Li "data1" .
+It behaves like
+.Li .text ,
+.Li .data ,
+or
+.Li .data 1 .
+.Pp
+.It  .skip
+This is functionally identical to the
+.Li .space
+directive.
+.Pp
+.It  .word
+On the Sparc, the
+.Li .word
+directive produces 32 bit values, instead of the 16 bit values it produces
+on many other machines.
+.Pp
+.It  .xword
+On the Sparc V9 processor, the
+.Li .xword
+directive produces 64 bit values.
+.El
+.Pp
+.Sh  Reporting Bugs
+Your bug reports play an essential role in making
+.Xr as
+reliable.
+.Pp
+Reporting a bug may help you by bringing a solution to your problem, or it
+may not. But in any case the principal function of a bug report is to help
+the entire community by making the next version of
+.Xr as
+work better. Bug reports are your contribution to the maintenance of
+.Xr as .
+.Pp
+In order for a bug report to serve its purpose, you must include the information
+that enables us to fix the bug.
+.Pp
+.Ss  Have You Found a Bug?
+If you are not sure whether you have found a bug, here are some guidelines:
+.Pp
+.Bl -bullet
+.It
+If the assembler gets a fatal signal, for any input whatever, that is a
+.Xr as
+bug. Reliable assemblers never crash.
+.Pp
+.It
+If
+.Xr as
+produces an error message for valid input, that is a bug.
+.Pp
+.It
+If
+.Xr as
+does not produce an error message for invalid input, that is a bug. However,
+you should note that your idea of \(lqinvalid input\(rq might be our idea of \(lqan extension\(rq
+or \(lqsupport for traditional practice\(rq.
+.Pp
+.It
+If you are an experienced user of assemblers, your suggestions for improvement
+of
+.Xr as
+are welcome in any case.
+.El
+.Pp
+.Ss  How to Report Bugs
+A number of companies and individuals offer support for GNU products. If you
+obtained
+.Xr as
+from a support organization, we recommend you contact that organization first.
+.Pp
+You can find contact information for many support companies and individuals
+in the file
+.Pa etc/SERVICE
+in the GNU Emacs distribution.
+.Pp
+The fundamental principle of reporting bugs usefully is this:
+.Sy report all the facts .
+If you are not sure whether to state a fact or leave it out, state it!
+.Pp
+Often people omit facts because they think they know what causes the problem
+and assume that some details do not matter. Thus, you might assume that the
+name of a symbol you use in an example does not matter. Well, probably it
+does not, but one cannot be sure. Perhaps the bug is a stray memory reference
+which happens to fetch from the location where that name is stored in memory;
+perhaps, if the name were different, the contents of that location would fool
+the assembler into doing the right thing despite the bug. Play it safe and
+give a specific, complete example. That is the easiest thing for you to do,
+and the most helpful.
+.Pp
+Keep in mind that the purpose of a bug report is to enable us to fix the bug
+if it is new to us. Therefore, always write your bug reports on the assumption
+that the bug has not been reported previously.
+.Pp
+Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq
+This cannot help us fix a bug, so it is basically useless. We respond by asking
+for enough details to enable us to investigate. You might as well expedite
+matters by sending them to begin with.
+.Pp
+To enable us to fix the bug, you should include all these things:
+.Pp
+.Bl -bullet
+.It
+The version of
+.Xr as .
+.Xr as
+announces it if you start it with the
+.Li --version
+argument.
+.Pp
+Without this, we will not know whether there is any point in looking for the
+bug in the current version of
+.Xr as .
+.Pp
+.It
+Any patches you may have applied to the
+.Xr as
+source.
+.Pp
+.It
+The type of machine you are using, and the operating system name and version
+number.
+.Pp
+.It
+What compiler (and its version) was used to compile
+.Xr as
+---e.g. \(lq
+.Li gcc-2.7
+\(rq\&.
+.Pp
+.It
+The command arguments you gave the assembler to assemble your example and
+observe the bug. To guarantee you will not omit something important, list
+them all. A copy of the Makefile (or the output from make) is sufficient.
+.Pp
+If we were to try to guess the arguments, we would probably guess wrong and
+then we might not encounter the bug.
+.Pp
+.It
+A complete input file that will reproduce the bug. If the bug is observed
+when the assembler is invoked via a compiler, send the assembler source, not
+the high level language source. Most compilers will produce the assembler
+source when run with the
+.Li -S
+option. If you are using
+.Li gcc ,
+use the options
+.Li -v --save-temps ;
+this will save the assembler source in a file with an extension of
+.Pa .s ,
+and also show you exactly how
+.Xr as
+is being run.
+.Pp
+.It
+A description of what behavior you observe that you believe is incorrect.
+For example, \(lqIt gets a fatal signal.\(rq
+.Pp
+Of course, if the bug is that
+.Xr as
+gets a fatal signal, then we will certainly notice it. But if the bug is incorrect
+output, we might not notice unless it is glaringly wrong. You might as well
+not give us a chance to make a mistake.
+.Pp
+Even if the problem you experience is a fatal signal, you should still say
+so explicitly. Suppose something strange is going on, such as, your copy of
+.Xr as
+is out of sync, or you have encountered a bug in the C library on your system.
+(This has happened!) Your copy might crash and ours would not. If you told
+us to expect a crash, then when ours fails to crash, we would know that the
+bug was not happening for us. If you had not told us to expect a crash, then
+we would not be able to draw any conclusion from our observations.
+.Pp
+.It
+If you wish to suggest changes to the
+.Xr as
+source, send us context diffs, as generated by
+.Li diff
+with the
+.Li -u ,
+.Li -c ,
+or
+.Li -p
+option. Always send diffs from the old file to the new file. If you even discuss
+something in the
+.Xr as
+source, refer to it by context, not by line number.
+.Pp
+The line numbers in our development sources will not match those in your sources.
+Your line numbers would convey no useful information to us.
+.El
+.Pp
+Here are some things that are not necessary:
+.Pp
+.Bl -bullet
+.It
+A description of the envelope of the bug.
+.Pp
+Often people who encounter a bug spend a lot of time investigating which changes
+to the input file will make the bug go away and which changes will not affect
+it.
+.Pp
+This is often time consuming and not very useful, because the way we will
+find the bug is by running a single example under the debugger with breakpoints,
+not by pure deduction from a series of examples. We recommend that you save
+your time for something else.
+.Pp
+Of course, if you can find a simpler example to report
+.Em instead
+of the original one, that is a convenience for us. Errors in the output will
+be easier to spot, running under the debugger will take less time, and so
+on.
+.Pp
+However, simplification is not vital; if you do not want to do this, report
+the bug anyway and send us the entire test case you used.
+.Pp
+.It
+A patch for the bug.
+.Pp
+A patch for the bug does help us if it is a good one. But do not omit the
+necessary information, such as the test case, on the assumption that a patch
+is all we need. We might see problems with your patch and decide to fix the
+problem another way, or we might not understand it at all.
+.Pp
+Sometimes with a program as complicated as
+.Xr as
+it is very hard to construct an example that will make the program follow
+a certain path through the code. If you do not send us the example, we will
+not be able to construct one, so we will not be able to verify that the bug
+is fixed.
+.Pp
+And if we cannot understand what bug you are trying to fix, or why your patch
+should be an improvement, we will not install it. A test case will help us
+to understand.
+.Pp
+.It
+A guess about what the bug is or what it depends on.
+.Pp
+Such guesses are usually wrong. Even we cannot guess right about such things
+without first using the debugger to find the facts.
+.El
+.Pp
+.Sh  Acknowledgements
+If you have contributed to GAS and your name isn't listed here, it is not
+meant as a slight. We just don't know about it. Send mail to the maintainer,
+and we'll correct the situation. Currently the maintainer is Ken Raeburn (email
+address
+.Li raeburn@cyGNUs.com ) .
+.Pp
+Dean Elsner wrote the original GNU assembler for the VAX.
+.Pp
+Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
+information and the 68k series machines, most of the preprocessing pass, and
+extensive changes in
+.Pa messages.c ,
+.Pa input-file.c ,
+.Pa write.c .
+.Pp
+K. Richard Pixley maintained GAS for a while, adding various enhancements
+and many bug fixes, including merging support for several processors, breaking
+GAS up to handle multiple object file format back ends (including heavy rewrite,
+testing, an integration of the coff and b.out back ends), adding configuration
+including heavy testing and verification of cross assemblers and file splits
+and renaming, converted GAS to strictly ANSI C including full prototypes,
+added support for m680[34]0 and cpu32, did considerable work on i960 including
+a COFF port (including considerable amounts of reverse engineering), a SPARC
+opcode file rewrite, DECstation, rs6000, and hp300hpux host ports, updated
+\(lqknow\(rq assertions and made them work, much other reorganization, cleanup, and
+lint.
+.Pp
+Ken Raeburn wrote the high-level BFD interface code to replace most of the
+code in format-specific I/O modules.
+.Pp
+The original VMS support was contributed by David L. Kashtan. Eric Youngdale
+has done much work with it since.
+.Pp
+The Intel 80386 machine description was written by Eliot Dresselhaus.
+.Pp
+Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
+.Pp
+The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
+University and Torbjorn Granlund of the Swedish Institute of Computer Science.
+.Pp
+Keith Knowles at the Open Software Foundation wrote the original MIPS back
+end (
+.Pa tc-mips.c ,
+.Pa tc-mips.h ) ,
+and contributed Rose format support (which hasn't been merged in yet). Ralph
+Campbell worked with the MIPS code to support a.out format.
+.Pp
+Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, tc-h8300),
+and IEEE 695 object file format (obj-ieee), was written by Steve Chamberlain
+of CyGNUs Support. Steve also modified the COFF back end to use BFD for some
+low-level operations, for use with the H8/300 and AMD 29k targets.
+.Pp
+John Gilmore built the AMD 29000 support, added
+.Li .include
+support, and simplified the configuration of which versions accept which directives.
+He updated the 68k machine description so that Motorola's opcodes always produced
+fixed-size instructions (e.g.,
+.Li jsr ) ,
+while synthetic instructions remained shrinkable (
+.Li jbsr ) .
+John fixed many bugs, including true tested cross-compilation support, and
+one bug in relaxation that took a week and required the proverbial one-bit
+fix.
+.Pp
+Ian Lance Taylor of CyGNUs Support merged the Motorola and MIT syntax for
+the 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO
+Unix), added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000
+and PowerPC assembler, and made a few other minor patches.
+.Pp
+Steve Chamberlain made GAS able to generate listings.
+.Pp
+Hewlett-Packard contributed support for the HP9000/300.
+.Pp
+Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
+along with a fairly extensive HPPA testsuite (for both SOM and ELF object
+formats). This work was supported by both the Center for Software Science
+at the University of Utah and CyGNUs Support.
+.Pp
+Support for ELF format files has been worked on by Mark Eichin of CyGNUs Support
+(original, incomplete implementation for SPARC), Pete Hoogenboom and Jeff
+Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
+Software Foundation (i386 mainly), and Ken Raeburn of CyGNUs Support (sparc,
+and some initial 64-bit support).
+.Pp
+Linas Vepstas added GAS support for the ESA/390 \(lqIBM 370\(rq architecture.
+.Pp
+Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and
+BFD support for openVMS/Alpha.
+.Pp
+Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic*
+flavors.
+.Pp
+David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica,
+Inc. added support for Xtensa processors.
+.Pp
+Several engineers at CyGNUs Support have also provided many small bug fixes
+and configuration enhancements.
+.Pp
+Many others have contributed large or small bugfixes and enhancements. If
+you have contributed significant work and are not mentioned on this list,
+and want to be, let us know. Some of the history has been lost; we are not
+intentionally leaving anyone out.
+.Pp
+.Sh  GNU Free Documentation License
+.Bd -filled -offset indent
+Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street,
+Fifth Floor, Boston, MA 02110-1301 USA
+.Pp
+Everyone is permitted to copy and distribute verbatim copies of this license
+document, but changing it is not allowed.
+.Ed
+.Pp
+.Bl -enum
+.It
+PREAMBLE
+.Pp
+The purpose of this License is to make a manual, textbook, or other written
+document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom
+to copy and redistribute it, with or without modifying it, either commercially
+or noncommercially. Secondarily, this License preserves for the author and
+publisher a way to get credit for their work, while not being considered responsible
+for modifications made by others.
+.Pp
+This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the
+document must themselves be free in the same sense. It complements the GNU
+General Public License, which is a copyleft license designed for free software.
+.Pp
+We have designed this License in order to use it for manuals for free software,
+because free software needs free documentation: a free program should come
+with manuals providing the same freedoms that the software does. But this
+License is not limited to software manuals; it can be used for any textual
+work, regardless of subject matter or whether it is published as a printed
+book. We recommend this License principally for works whose purpose is instruction
+or reference.
+.Pp
+.It
+APPLICABILITY AND DEFINITIONS
+.Pp
+This License applies to any manual or other work that contains a notice placed
+by the copyright holder saying it can be distributed under the terms of this
+License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member
+of the public is a licensee, and is addressed as \(lqyou.\(rq
+.Pp
+A \(lqModified Version\(rq of the Document means any work containing the Document
+or a portion of it, either copied verbatim, or with modifications and/or translated
+into another language.
+.Pp
+A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document
+that deals exclusively with the relationship of the publishers or authors
+of the Document to the Document's overall subject (or to related matters)
+and contains nothing that could fall directly within that overall subject.
+(For example, if the Document is in part a textbook of mathematics, a Secondary
+Section may not explain any mathematics.) The relationship could be a matter
+of historical connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding them.
+.Pp
+The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated,
+as being those of Invariant Sections, in the notice that says that the Document
+is released under this License.
+.Pp
+The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover
+Texts or Back-Cover Texts, in the notice that says that the Document is released
+under this License.
+.Pp
+A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented
+in a format whose specification is available to the general public, whose
+contents can be viewed and edited directly and straightforwardly with generic
+text editors or (for images composed of pixels) generic paint programs or
+(for drawings) some widely available drawing editor, and that is suitable
+for input to text formatters or for automatic translation to a variety of
+formats suitable for input to text formatters. A copy made in an otherwise
+Transparent file format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is not
+\(lqTransparent\(rq is called \(lqOpaque.\(rq
+.Pp
+Examples of suitable formats for Transparent copies include plain ASCII without
+markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly
+available DTD, and standard-conforming simple HTML designed for human modification.
+Opaque formats include PostScript, PDF, proprietary formats that can be read
+and edited only by proprietary word processors, SGML or XML for which the
+DTD and/or processing tools are not generally available, and the machine-generated
+HTML produced by some word processors for output purposes only.
+.Pp
+The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such
+following pages as are needed to hold, legibly, the material this License
+requires to appear in the title page. For works in formats which do not have
+any title page as such, \(lqTitle Page\(rq means the text near the most prominent
+appearance of the work's title, preceding the beginning of the body of the
+text.
+.Pp
+.It
+VERBATIM COPYING
+.Pp
+You may copy and distribute the Document in any medium, either commercially
+or noncommercially, provided that this License, the copyright notices, and
+the license notice saying this License applies to the Document are reproduced
+in all copies, and that you add no other conditions whatsoever to those of
+this License. You may not use technical measures to obstruct or control the
+reading or further copying of the copies you make or distribute. However,
+you may accept compensation in exchange for copies. If you distribute a large
+enough number of copies you must also follow the conditions in section 3.
+.Pp
+You may also lend copies, under the same conditions stated above, and you
+may publicly display copies.
+.Pp
+.It
+COPYING IN QUANTITY
+.Pp
+If you publish printed copies of the Document numbering more than 100, and
+the Document's license notice requires Cover Texts, you must enclose the copies
+in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover
+Texts on the front cover, and Back-Cover Texts on the back cover. Both covers
+must also clearly and legibly identify you as the publisher of these copies.
+The front cover must present the full title with all words of the title equally
+prominent and visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve the title
+of the Document and satisfy these conditions, can be treated as verbatim copying
+in other respects.
+.Pp
+If the required texts for either cover are too voluminous to fit legibly,
+you should put the first ones listed (as many as fit reasonably) on the actual
+cover, and continue the rest onto adjacent pages.
+.Pp
+If you publish or distribute Opaque copies of the Document numbering more
+than 100, you must either include a machine-readable Transparent copy along
+with each Opaque copy, or state in or with each Opaque copy a publicly-accessible
+computer-network location containing a complete Transparent copy of the Document,
+free of added material, which the general network-using public has access
+to download anonymously at no charge using public-standard network protocols.
+If you use the latter option, you must take reasonably prudent steps, when
+you begin distribution of Opaque copies in quantity, to ensure that this Transparent
+copy will remain thus accessible at the stated location until at least one
+year after the last time you distribute an Opaque copy (directly or through
+your agents or retailers) of that edition to the public.
+.Pp
+It is requested, but not required, that you contact the authors of the Document
+well before redistributing any large number of copies, to give them a chance
+to provide you with an updated version of the Document.
+.Pp
+.It
+MODIFICATIONS
+.Pp
+You may copy and distribute a Modified Version of the Document under the conditions
+of sections 2 and 3 above, provided that you release the Modified Version
+under precisely this License, with the Modified Version filling the role of
+the Document, thus licensing distribution and modification of the Modified
+Version to whoever possesses a copy of it. In addition, you must do these
+things in the Modified Version:
+.Pp
+A. Use in the Title Page (and on the covers, if any) a title distinct from
+that of the Document, and from those of previous versions (which should, if
+there were any, be listed in the History section of the Document). You may
+use the same title as a previous version if the original publisher of that
+version gives permission.  B. List on the Title Page, as authors, one or more
+persons or entities responsible for authorship of the modifications in the
+Modified Version, together with at least five of the principal authors of
+the Document (all of its principal authors, if it has less than five).  C.
+State on the Title page the name of the publisher of the Modified Version,
+as the publisher.  D. Preserve all the copyright notices of the Document. 
+E. Add an appropriate copyright notice for your modifications adjacent to
+the other copyright notices.  F. Include, immediately after the copyright
+notices, a license notice giving the public permission to use the Modified
+Version under the terms of this License, in the form shown in the Addendum
+below.  G. Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.  H. Include
+an unaltered copy of this License.  I. Preserve the section entitled \(lqHistory\(rq,
+and its title, and add to it an item stating at least the title, year, new
+authors, and publisher of the Modified Version as given on the Title Page.
+If there is no section entitled \(lqHistory\(rq in the Document, create one stating
+the title, year, authors, and publisher of the Document as given on its Title
+Page, then add an item describing the Modified Version as stated in the previous
+sentence.  J. Preserve the network location, if any, given in the Document
+for public access to a Transparent copy of the Document, and likewise the
+network locations given in the Document for previous versions it was based
+on. These may be placed in the \(lqHistory\(rq section. You may omit a network location
+for a work that was published at least four years before the Document itself,
+or if the original publisher of the version it refers to gives permission. 
+K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's
+title, and preserve in the section all the substance and tone of each of the
+contributor acknowledgements and/or dedications given therein.  L. Preserve
+all the Invariant Sections of the Document, unaltered in their text and in
+their titles. Section numbers or the equivalent are not considered part of
+the section titles.  M. Delete any section entitled \(lqEndorsements.\(rq Such a section
+may not be included in the Modified Version.  N. Do not retitle any existing
+section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. 
+.Pp
+If the Modified Version includes new front-matter sections or appendices that
+qualify as Secondary Sections and contain no material copied from the Document,
+you may at your option designate some or all of these sections as invariant.
+To do this, add their titles to the list of Invariant Sections in the Modified
+Version's license notice. These titles must be distinct from any other section
+titles.
+.Pp
+You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing
+but endorsements of your Modified Version by various parties--for example,
+statements of peer review or that the text has been approved by an organization
+as the authoritative definition of a standard.
+.Pp
+You may add a passage of up to five words as a Front-Cover Text, and a passage
+of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts
+in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover
+Text may be added by (or through arrangements made by) any one entity. If
+the Document already includes a cover text for the same cover, previously
+added by you or by arrangement made by the same entity you are acting on behalf
+of, you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+.Pp
+The author(s) and publisher(s) of the Document do not by this License give
+permission to use their names for publicity for or to assert or imply endorsement
+of any Modified Version.
+.Pp
+.It
+COMBINING DOCUMENTS
+.Pp
+You may combine the Document with other documents released under this License,
+under the terms defined in section 4 above for modified versions, provided
+that you include in the combination all of the Invariant Sections of all of
+the original documents, unmodified, and list them all as Invariant Sections
+of your combined work in its license notice.
+.Pp
+The combined work need only contain one copy of this License, and multiple
+identical Invariant Sections may be replaced with a single copy. If there
+are multiple Invariant Sections with the same name but different contents,
+make the title of each such section unique by adding at the end of it, in
+parentheses, the name of the original author or publisher of that section
+if known, or else a unique number. Make the same adjustment to the section
+titles in the list of Invariant Sections in the license notice of the combined
+work.
+.Pp
+In the combination, you must combine any sections entitled \(lqHistory\(rq in the
+various original documents, forming one section entitled \(lqHistory\(rq; likewise
+combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled
+\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq
+.Pp
+.It
+COLLECTIONS OF DOCUMENTS
+.Pp
+You may make a collection consisting of the Document and other documents released
+under this License, and replace the individual copies of this License in the
+various documents with a single copy that is included in the collection, provided
+that you follow the rules of this License for verbatim copying of each of
+the documents in all other respects.
+.Pp
+You may extract a single document from such a collection, and distribute it
+individually under this License, provided you insert a copy of this License
+into the extracted document, and follow this License in all other respects
+regarding verbatim copying of that document.
+.Pp
+.It
+AGGREGATION WITH INDEPENDENT WORKS
+.Pp
+A compilation of the Document or its derivatives with other separate and independent
+documents or works, in or on a volume of a storage or distribution medium,
+does not as a whole count as a Modified Version of the Document, provided
+no compilation copyright is claimed for the compilation. Such a compilation
+is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained
+works thus compiled with the Document, on account of their being thus compiled,
+if they are not themselves derivative works of the Document.
+.Pp
+If the Cover Text requirement of section 3 is applicable to these copies of
+the Document, then if the Document is less than one quarter of the entire
+aggregate, the Document's Cover Texts may be placed on covers that surround
+only the Document within the aggregate. Otherwise they must appear on covers
+around the whole aggregate.
+.Pp
+.It
+TRANSLATION
+.Pp
+Translation is considered a kind of modification, so you may distribute translations
+of the Document under the terms of section 4. Replacing Invariant Sections
+with translations requires special permission from their copyright holders,
+but you may include translations of some or all Invariant Sections in addition
+to the original versions of these Invariant Sections. You may include a translation
+of this License provided that you also include the original English version
+of this License. In case of a disagreement between the translation and the
+original English version of this License, the original English version will
+prevail.
+.Pp
+.It
+TERMINATION
+.Pp
+You may not copy, modify, sublicense, or distribute the Document except as
+expressly provided for under this License. Any other attempt to copy, modify,
+sublicense or distribute the Document is void, and will automatically terminate
+your rights under this License. However, parties who have received copies,
+or rights, from you under this License will not have their licenses terminated
+so long as such parties remain in full compliance.
+.Pp
+.It
+FUTURE REVISIONS OF THIS LICENSE
+.Pp
+The Free Software Foundation may publish new, revised versions of the GNU
+Free Documentation License from time to time. Such new versions will be similar
+in spirit to the present version, but may differ in detail to address new
+problems or concerns. See http://www.gnu.org/copyleft/.
+.Pp
+Each version of the License is given a distinguishing version number. If the
+Document specifies that a particular numbered version of this License \(lqor any
+later version\(rq applies to it, you have the option of following the terms and
+conditions either of that specified version or of any later version that has
+been published (not as a draft) by the Free Software Foundation. If the Document
+does not specify a version number of this License, you may choose any version
+ever published (not as a draft) by the Free Software Foundation.
+.Pp
+.El
+.Ss  ADDENDUM: How to use this License for your documents
+To use this License in a document you have written, include a copy of the
+License in the document and put the following copyright and license notices
+just after the title page:
+.Pp
+.Bd -literal -offset indent
+
+Copyright (C)  year  your name.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with the Invariant Sections being list their titles, with the
+Front-Cover Texts being list, and with the Back-Cover Texts being list.
+A copy of the license is included in the section entitled "GNU
+Free Documentation License."
+
+.Ed
+.Pp
+If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead
+of saying which ones are invariant. If you have no Front-Cover Texts, write
+\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being
+.Va list
+\(rq; likewise for Back-Cover Texts.
+.Pp
+If your document contains nontrivial examples of program code, we recommend
+releasing these examples in parallel under your choice of free software license,
+such as the GNU General Public License, to permit their use in free software.
+.Pp
+.Sh  AS Index
diff --git a/contrib/binutils/ld/ld.7 b/contrib/binutils/ld/ld.7
new file mode 100644
index 0000000..8ac5573
--- /dev/null
+++ b/contrib/binutils/ld/ld.7
@@ -0,0 +1,7819 @@
+.Dd 2015-03-02
+.Dt LD 7
+.Os
+.Sh NAME
+.Nm ld
+.Nd The GNU Linker
+.Sh  LD
+This file documents the GNU linker ld version "2.17.50 [FreeBSD] 2007-07-03".
+.Pp
+This document is distributed under the terms of the GNU Free Documentation
+License. A copy of the license is included in the section entitled \(lqGNU Free
+Documentation License\(rq.
+.Pp
+.Sh  Overview
+.Xr 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
+.Xr ld .
+.Pp
+.Xr 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.
+.Pp
+This version of
+.Xr ld
+uses the general purpose BFD libraries to operate on object files. This allows
+.Xr ld
+to read, combine, and write object files in many different formats---for example,
+COFF or
+.Li a.out .
+Different formats may be linked together to produce any available kind of
+object file.See Section
+.Dq BFD ,
+for more information.
+.Pp
+Aside from its flexibility, the GNU linker is more helpful than other linkers
+in providing diagnostic information. Many linkers abandon execution immediately
+upon encountering an error; whenever possible,
+.Xr ld
+continues executing, allowing you to identify other errors (or, in some cases,
+to get an output file in spite of the error).
+.Pp
+.Sh  Invocation
+The GNU linker
+.Xr 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.
+.Pp
+.Ss  Command Line Options
+The linker supports a plethora of command-line options, but in actual practice
+few of them are used in any particular context. For instance, a frequent use
+of
+.Xr ld
+is to link standard Unix object files on a standard, supported Unix system.
+On such a system, to link a file
+.Li hello.o :
+.Pp
+.Bd -literal -offset indent
+ld -o output /lib/crt0.o hello.o -lc
+.Ed
+.Pp
+This tells
+.Xr ld
+to produce a file called
+.Va output
+as the result of linking the file
+.Li /lib/crt0.o
+with
+.Li hello.o
+and the library
+.Li libc.a ,
+which will come from the standard search directories. (See the discussion
+of the
+.Li -l
+option below.)
+.Pp
+Some of the command-line options to
+.Xr ld
+may be specified at any point in the command line. However, options which
+refer to files, such as
+.Li -l
+or
+.Li -T ,
+cause the file to be read at the point at which the option appears in the
+command line, relative to the object files and other file options. Repeating
+non-file options with a different argument will either have no further effect,
+or override prior occurrences (those further to the left on the command line)
+of that option. Options which may be meaningfully specified more than once
+are noted in the descriptions below.
+.Pp
+Non-option arguments are object files or archives which are to be linked together.
+They may follow, precede, or be mixed in with command-line options, except
+that an object file argument may not be placed between an option and its argument.
+.Pp
+Usually the linker is invoked with at least one object file, but you can specify
+other forms of binary input files using
+.Li -l ,
+.Li -R ,
+and the script command language. If
+.Em no
+binary input files at all are specified, the linker does not produce any output,
+and issues the message
+.Li No input files .
+.Pp
+If the linker cannot recognize the format of an object file, it will assume
+that it is a linker script. A script specified in this way augments the main
+linker script used for the link (either the default linker script or the one
+specified by using
+.Li -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
+.Li INPUT
+or
+.Li GROUP
+to load other objects. Note that specifying a script in this way merely augments
+the main linker script; use the
+.Li -T
+option to replace the default linker script entirely.See Section
+.Dq Scripts .
+.Pp
+For options whose names are a single letter, option arguments must either
+follow the option letter without intervening whitespace, or be given as separate
+arguments immediately following the option that requires them.
+.Pp
+For options whose names are multiple letters, either one dash or two can precede
+the option name; for example,
+.Li -trace-symbol
+and
+.Li --trace-symbol
+are equivalent. Note---there is one exception to this rule. Multiple letter
+options that start with a lower case 'o' can only be preceded by two dashes.
+This is to reduce confusion with the
+.Li -o
+option. So for example
+.Li -omagic
+sets the output file name to
+.Li magic
+whereas
+.Li --omagic
+sets the NMAGIC flag on the output.
+.Pp
+Arguments to multiple-letter options must either be separated from the option
+name by an equals sign, or be given as separate arguments immediately following
+the option that requires them. For example,
+.Li --trace-symbol foo
+and
+.Li --trace-symbol=foo
+are equivalent. Unique abbreviations of the names of multiple-letter options
+are accepted.
+.Pp
+Note---if the linker is being invoked indirectly, via a compiler driver (e.g.
+.Li gcc )
+then all the linker command line options should be prefixed by
+.Li -Wl,
+(or whatever is appropriate for the particular compiler driver) like this:
+.Pp
+.Bd -literal -offset indent
+  gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
+.Ed
+.Pp
+This is important, because otherwise the compiler driver program may silently
+drop the linker options, resulting in a bad link.
+.Pp
+Here is a table of the generic command line switches accepted by the GNU linker:
+.Pp
+.Bl -tag -width Ds
+.It  @ Va file
+Read command-line options from
+.Va file .
+The options read are inserted in place of the original @
+.Va file
+option. If
+.Va file
+does not exist, or cannot be read, then the option will be treated literally,
+and not removed.
+.Pp
+Options in
+.Va file
+are separated by whitespace. A whitespace character may be included in an
+option by surrounding the entire option in either single or double quotes.
+Any character (including a backslash) may be included by prefixing the character
+to be included with a backslash. The
+.Va file
+may itself contain additional @
+.Va file
+options; any such options will be processed recursively.
+.Pp
+.It  -a Va keyword
+This option is supported for HP/UX compatibility. The
+.Va keyword
+argument must be one of the strings
+.Li archive ,
+.Li shared ,
+or
+.Li default .
+.Li -aarchive
+is functionally equivalent to
+.Li -Bstatic ,
+and the other two keywords are functionally equivalent to
+.Li -Bdynamic .
+This option may be used any number of times.
+.Pp
+.It  -A Va architecture
+.It  --architecture= Va architecture
+In the current release of
+.Xr ld ,
+this option is useful only for the Intel 960 family of architectures. In that
+.Xr ld
+configuration, the
+.Va architecture
+argument identifies the particular architecture in the 960 family, enabling
+some safeguards and modifying the archive-library search path.See Section
+.Dq i960 ,
+for details.
+.Pp
+Future releases of
+.Xr ld
+may support similar functionality for other architecture families.
+.Pp
+.It  -b Va input-format
+.It  --format= Va input-format
+.Xr ld
+may be configured to support more than one kind of object file. If your
+.Xr ld
+is configured this way, you can use the
+.Li -b
+option to specify the binary format for input object files that follow this
+option on the command line. Even when
+.Xr ld
+is configured to support alternative object formats, you don't usually need
+to specify this, as
+.Xr ld
+should be configured to expect as a default input format the most usual format
+on each machine.
+.Va 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
+.Li objdump -i . )
+See Section.Dq BFD .
+.Pp
+You may want to use this option if you are linking files with an unusual binary
+format. You can also use
+.Li -b
+to switch formats explicitly (when linking object files of different formats),
+by including
+.Li -b Va input-format
+before each group of object files in a particular format.
+.Pp
+The default format is taken from the environment variable
+.Li GNUTARGET .
+See Section.Dq Environment .
+You can also define the input format from a script, using the command
+.Li TARGET ;
+see Format Commands.
+.Pp
+.It  -c Va MRI-commandfile
+.It  --mri-script= Va MRI-commandfile
+For compatibility with linkers produced by MRI,
+.Xr ld
+accepts script files written in an alternate, restricted command language,
+described in MRI,,MRI Compatible Script Files. Introduce MRI script files
+with the option
+.Li -c ;
+use the
+.Li -T
+option to run linker scripts written in the general-purpose
+.Xr ld
+scripting language. If
+.Va MRI-cmdfile
+does not exist,
+.Xr ld
+looks for it in the directories specified by any
+.Li -L
+options.
+.Pp
+.It  -d
+.It  -dc
+.It  -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
+.Li -r ) .
+The script command
+.Li FORCE_COMMON_ALLOCATION
+has the same effect.See Section
+.Dq Miscellaneous Commands .
+.Pp
+.It  -e Va entry
+.It  --entry= Va entry
+Use
+.Va entry
+as the explicit symbol for beginning execution of your program, rather than
+the default entry point. If there is no symbol named
+.Va entry ,
+the linker will try to parse
+.Va entry
+as a number, and use that as the entry address (the number will be interpreted
+in base 10; you may use a leading
+.Li 0x
+for base 16, or a leading
+.Li 0
+for base 8).See Section
+.Dq Entry Point ,
+for a discussion of defaults and other ways of specifying the entry point.
+.Pp
+.It  --exclude-libs Va lib, Va lib,...
+Specifies a list of archive libraries from which symbols should not be automatically
+exported. The library names may be delimited by commas or colons. Specifying
+.Li --exclude-libs ALL
+excludes symbols in all archive libraries from automatic export. This option
+is available only for the i386 PE targeted port of the linker and for ELF
+targeted ports. For i386 PE, symbols explicitly listed in a .def file are
+still exported, regardless of this option. For ELF targeted ports, symbols
+affected by this option will be treated as hidden.
+.Pp
+.It  -E
+.It  --export-dynamic
+When creating a dynamically linked executable, add all symbols to the dynamic
+symbol table. The dynamic symbol table is the set of symbols which are visible
+from dynamic objects at run time.
+.Pp
+If you do not use this option, the dynamic symbol table will normally contain
+only those symbols which are referenced by some dynamic object mentioned in
+the link.
+.Pp
+If you use
+.Li dlopen
+to load a dynamic object which needs to refer back to the symbols defined
+by the program, rather than some other dynamic object, then you will probably
+need to use this option when linking the program itself.
+.Pp
+You can also use the dynamic list to control what symbols should be added
+to the dynamic symbol table if the output format supports it. See the description
+of
+.Li --dynamic-list .
+.Pp
+.It  -EB
+Link big-endian objects. This affects the default output format.
+.Pp
+.It  -EL
+Link little-endian objects. This affects the default output format.
+.Pp
+.It  -f
+.It  --auxiliary Va name
+When creating an ELF shared object, set the internal DT_AUXILIARY field to
+the specified name. This tells the dynamic linker that the symbol table of
+the shared object should be used as an auxiliary filter on the symbol table
+of the shared object
+.Va name .
+.Pp
+If you later link a program against this filter object, then, when you run
+the program, the dynamic linker will see the DT_AUXILIARY field. If the dynamic
+linker resolves any symbols from the filter object, it will first check whether
+there is a definition in the shared object
+.Va name .
+If there is one, it will be used instead of the definition in the filter object.
+The shared object
+.Va name
+need not exist. Thus the shared object
+.Va name
+may be used to provide an alternative implementation of certain functions,
+perhaps for debugging or for machine specific performance.
+.Pp
+This option may be specified more than once. The DT_AUXILIARY entries will
+be created in the order in which they appear on the command line.
+.Pp
+.It  -F Va name
+.It  --filter Va name
+When creating an ELF shared object, set the internal DT_FILTER field to the
+specified name. This tells the dynamic linker that the symbol table of the
+shared object which is being created should be used as a filter on the symbol
+table of the shared object
+.Va name .
+.Pp
+If you later link a program against this filter object, then, when you run
+the program, the dynamic linker will see the DT_FILTER field. The dynamic
+linker will resolve symbols according to the symbol table of the filter object
+as usual, but it will actually link to the definitions found in the shared
+object
+.Va name .
+Thus the filter object can be used to select a subset of the symbols provided
+by the object
+.Va name .
+.Pp
+Some older linkers used the
+.Op -F
+option throughout a compilation toolchain for specifying object-file format
+for both input and output object files. The GNU linker uses other mechanisms
+for this purpose: the
+.Op -b ,
+.Op --format ,
+.Op --oformat
+options, the
+.Li TARGET
+command in linker scripts, and the
+.Li GNUTARGET
+environment variable. The GNU linker will ignore the
+.Op -F
+option when not creating an ELF shared object.
+.Pp
+.It  -fini Va name
+When creating an ELF executable or shared object, call NAME when the executable
+or shared object is unloaded, by setting DT_FINI to the address of the function.
+By default, the linker uses
+.Li _fini
+as the function to call.
+.Pp
+.It  -g
+Ignored. Provided for compatibility with other tools.
+.Pp
+.It  -G Va value
+.It  --gpsize= Va value
+Set the maximum size of objects to be optimized using the GP register to
+.Va size .
+This is only meaningful for object file formats such as MIPS ECOFF which supports
+putting large and small objects into different sections. This is ignored for
+other object file formats.
+.Pp
+.It  -h Va name
+.It  -soname= Va 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.
+.Pp
+.It  -i
+Perform an incremental link (same as option
+.Li -r ) .
+.Pp
+.It  -init Va name
+When creating an ELF executable or shared object, call NAME when the executable
+or shared object is loaded, by setting DT_INIT to the address of the function.
+By default, the linker uses
+.Li _init
+as the function to call.
+.Pp
+.It  -l Va namespec
+.It  --library= Va namespec
+Add the archive or object file specified by
+.Va namespec
+to the list of files to link. This option may be used any number of times.
+If
+.Va namespec
+is of the form
+.Pa : Va filename ,
+.Xr ld
+will search the library path for a file called
+.Va filename ,
+otherise it will search the library path for a file called
+.Pa lib Va namespec.a .
+.Pp
+On systems which support shared libraries,
+.Xr ld
+may also search for files other than
+.Pa lib Va namespec.a .
+Specifically, on ELF and SunOS systems,
+.Xr ld
+will search a directory for a library called
+.Pa lib Va namespec.so
+before searching for one called
+.Pa lib Va namespec.a .
+(By convention, a
+.Li .so
+extension indicates a shared library.) Note that this behavior does not apply
+to
+.Pa : Va filename ,
+which always specifies a file called
+.Va filename .
+.Pp
+The linker will search an archive only once, at the location where it is specified
+on the command line. If the archive defines a symbol which was undefined in
+some object which appeared before the archive on the command line, the linker
+will include the appropriate file(s) from the archive. However, an undefined
+symbol in an object appearing later on the command line will not cause the
+linker to search the archive again.
+.Pp
+See the
+.Op -(
+option for a way to force the linker to search archives multiple times.
+.Pp
+You may list the same archive multiple times on the command line.
+.Pp
+This type of archive searching is standard for Unix linkers. However, if you
+are using
+.Xr ld
+on AIX, note that it is different from the behaviour of the AIX linker.
+.Pp
+.It  -L Va searchdir
+.It  --library-path= Va searchdir
+Add path
+.Va searchdir
+to the list of paths that
+.Xr ld
+will search for archive libraries and
+.Xr 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
+.Op -L
+options apply to all
+.Op -l
+options, regardless of the order in which the options appear.
+.Pp
+If
+.Va searchdir
+begins with
+.Li = ,
+then the
+.Li =
+will be replaced by the
+.Em sysroot prefix ,
+a path specified when the linker is configured.
+.Pp
+The default set of paths searched (without being specified with
+.Li -L )
+depends on which emulation mode
+.Xr ld
+is using, and in some cases also on how it was configured.See Section
+.Dq Environment .
+.Pp
+The paths can also be specified in a link script with the
+.Li SEARCH_DIR
+command. Directories specified this way are searched at the point in which
+the linker script appears in the command line.
+.Pp
+.It  -m Va emulation
+Emulate the
+.Va emulation
+linker. You can list the available emulations with the
+.Li --verbose
+or
+.Li -V
+options.
+.Pp
+If the
+.Li -m
+option is not used, the emulation is taken from the
+.Li LDEMULATION
+environment variable, if that is defined.
+.Pp
+Otherwise, the default emulation depends upon how the linker was configured.
+.Pp
+.It  -M
+.It  --print-map
+Print a link map to the standard output. A link map provides information about
+the link, including the following:
+.Pp
+.Bl -bullet
+.It
+Where object files are mapped into memory.
+.It
+How common symbols are allocated.
+.It
+All archive members included in the link, with a mention of the symbol which
+caused the archive member to be brought in.
+.It
+The values assigned to symbols.
+.Pp
+Note - symbols whose values are computed by an expression which involves a
+reference to a previous value of the same symbol may not have correct result
+displayed in the link map. This is because the linker discards intermediate
+results and only retains the final value of an expression. Under such circumstances
+the linker will display the final value enclosed by square brackets. Thus
+for example a linker script containing:
+.Pp
+.Bd -literal -offset indent
+   foo = 1
+   foo = foo * 4
+   foo = foo + 8
+.Ed
+.Pp
+will produce the following output in the link map if the
+.Op -M
+option is used:
+.Pp
+.Bd -literal -offset indent
+   0x00000001                foo = 0x1
+   [0x0000000c]                foo = (foo * 0x4)
+   [0x0000000c]                foo = (foo + 0x8)
+.Ed
+.Pp
+See Expressions for more information about expressions in linker scripts.
+.El
+.Pp
+.It  -n
+.It  --nmagic
+Turn off page alignment of sections, and mark the output as
+.Li NMAGIC
+if possible.
+.Pp
+.It  -N
+.It  --omagic
+Set the text and data sections to be readable and writable. Also, do not page-align
+the data segment, and disable linking against shared libraries. If the output
+format supports Unix style magic numbers, mark the output as
+.Li OMAGIC .
+Note: Although a writable text section is allowed for PE-COFF targets, it
+does not conform to the format specification published by Microsoft.
+.Pp
+.It  --no-omagic
+This option negates most of the effects of the
+.Op -N
+option. It sets the text section to be read-only, and forces the data segment
+to be page-aligned. Note - this option does not enable linking against shared
+libraries. Use
+.Op -Bdynamic
+for this.
+.Pp
+.It  -o Va output
+.It  --output= Va output
+Use
+.Va output
+as the name for the program produced by
+.Xr ld ;
+if this option is not specified, the name
+.Pa a.out
+is used by default. The script command
+.Li OUTPUT
+can also specify the output file name.
+.Pp
+.It  -O Va level
+If
+.Va level
+is a numeric values greater than zero
+.Xr ld
+optimizes the output. This might take significantly longer and therefore probably
+should only be enabled for the final binary.
+.Pp
+.It  -q
+.It  --emit-relocs
+Leave relocation sections and contents in fully linked executables. Post link
+analysis and optimization tools may need this information in order to perform
+correct modifications of executables. This results in larger executables.
+.Pp
+This option is currently only supported on ELF platforms.
+.Pp
+.It  --force-dynamic
+Force the output file to have dynamic sections. This option is specific to
+VxWorks targets.
+.Pp
+.It  -r
+.It  --relocatable
+Generate relocatable output---i.e., generate an output file that can in turn
+serve as input to
+.Xr ld .
+This is often called
+.Em 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
+.Li OMAGIC .
+If this option is not specified, an absolute file is produced. When linking
+C++ programs, this option
+.Em will not
+resolve references to constructors; to do that, use
+.Li -Ur .
+.Pp
+When an input file does not have the same format as the output file, partial
+linking is only supported if that input file does not contain any relocations.
+Different output formats can have further restrictions; for example some
+.Li a.out
+-based formats do not support partial linking with input files in other formats
+at all.
+.Pp
+This option does the same thing as
+.Li -i .
+.Pp
+.It  -R Va filename
+.It  --just-symbols= Va filename
+Read symbol names and their addresses from
+.Va filename ,
+but do not relocate it or include it in the output. This allows your output
+file to refer symbolically to absolute locations of memory defined in other
+programs. You may use this option more than once.
+.Pp
+For compatibility with other ELF linkers, if the
+.Op -R
+option is followed by a directory name, rather than a file name, it is treated
+as the
+.Op -rpath
+option.
+.Pp
+.It  -s
+.It  --strip-all
+Omit all symbol information from the output file.
+.Pp
+.It  -S
+.It  --strip-debug
+Omit debugger symbol information (but not all symbols) from the output file.
+.Pp
+.It  -t
+.It  --trace
+Print the names of the input files as
+.Xr ld
+processes them.
+.Pp
+.It  -T Va scriptfile
+.It  --script= Va scriptfile
+Use
+.Va scriptfile
+as the linker script. This script replaces
+.Xr ld
+\&'s default linker script (rather than adding to it), so
+.Va commandfile
+must specify everything necessary to describe the output file.See Section
+.Dq Scripts .
+If
+.Va scriptfile
+does not exist in the current directory,
+.Li ld
+looks for it in the directories specified by any preceding
+.Li -L
+options. Multiple
+.Li -T
+options accumulate.
+.Pp
+.It  -dT Va scriptfile
+.It  --default-script= Va scriptfile
+Use
+.Va scriptfile
+as the default linker script.See Section
+.Dq Scripts .
+.Pp
+This option is similar to the
+.Op --script
+option except that processing of the script is delayed until after the rest
+of the command line has been processed. This allows options placed after the
+.Op --default-script
+option on the command line to affect the behaviour of the linker script, which
+can be important when the linker command line cannot be directly controlled
+by the user. (eg because the command line is being constructed by another
+tool, such as
+.Li gcc ) .
+.Pp
+.It  -u Va symbol
+.It  --undefined= Va symbol
+Force
+.Va 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.
+.Li -u
+may be repeated with different option arguments to enter additional undefined
+symbols. This option is equivalent to the
+.Li EXTERN
+linker script command.
+.Pp
+.It  -Ur
+For anything other than C++ programs, this option is equivalent to
+.Li -r :
+it generates relocatable output---i.e., an output file that can in turn serve
+as input to
+.Xr ld .
+When linking C++ programs,
+.Li -Ur
+.Em does
+resolve references to constructors, unlike
+.Li -r .
+It does not work to use
+.Li -Ur
+on files that were themselves linked with
+.Li -Ur ;
+once the constructor table has been built, it cannot be added to. Use
+.Li -Ur
+only for the last partial link, and
+.Li -r
+for the others.
+.Pp
+.It  --unique[= Va SECTION]
+Creates a separate output section for every input section matching
+.Va SECTION ,
+or if the optional wildcard
+.Va SECTION
+argument is missing, for every orphan input section. An orphan section is
+one not specifically mentioned in a linker script. You may use this option
+multiple times on the command line; It prevents the normal merging of input
+sections with the same name, overriding output section assignments in a linker
+script.
+.Pp
+.It  -v
+.It  --version
+.It  -V
+Display the version number for
+.Xr ld .
+The
+.Op -V
+option also lists the supported emulations.
+.Pp
+.It  -x
+.It  --discard-all
+Delete all local symbols.
+.Pp
+.It  -X
+.It  --discard-locals
+Delete all temporary local symbols. (These symbols start with system-specific
+local label prefixes, typically
+.Li .L
+for ELF systems or
+.Li L
+for traditional a.out systems.)
+.Pp
+.It  -y Va symbol
+.It  --trace-symbol= Va symbol
+Print the name of each linked file in which
+.Va symbol
+appears. This option may be given any number of times. On many systems it
+is necessary to prepend an underscore.
+.Pp
+This option is useful when you have an undefined symbol in your link but don't
+know where the reference is coming from.
+.Pp
+.It  -Y Va path
+Add
+.Va path
+to the default library search path. This option exists for Solaris compatibility.
+.Pp
+.It  -z Va keyword
+The recognized keywords are:
+.Bl -tag -width Ds
+.It  combreloc
+Combines multiple reloc sections and sorts them to make dynamic symbol lookup
+caching possible.
+.Pp
+.It  defs
+Disallows undefined symbols in object files. Undefined symbols in shared libraries
+are still allowed.
+.Pp
+.It  execstack
+Marks the object as requiring executable stack.
+.Pp
+.It  initfirst
+This option is only meaningful when building a shared object. It marks the
+object so that its runtime initialization will occur before the runtime initialization
+of any other objects brought into the process at the same time. Similarly
+the runtime finalization of the object will occur after the runtime finalization
+of any other objects.
+.Pp
+.It  interpose
+Marks the object that its symbol table interposes before all symbols but the
+primary executable.
+.Pp
+.It  lazy
+When generating an executable or shared library, mark it to tell the dynamic
+linker to defer function call resolution to the point when the function is
+called (lazy binding), rather than at load time. Lazy binding is the default.
+.Pp
+.It  loadfltr
+Marks the object that its filters be processed immediately at runtime.
+.Pp
+.It  muldefs
+Allows multiple definitions.
+.Pp
+.It  nocombreloc
+Disables multiple reloc sections combining.
+.Pp
+.It  nocopyreloc
+Disables production of copy relocs.
+.Pp
+.It  nodefaultlib
+Marks the object that the search for dependencies of this object will ignore
+any default library search paths.
+.Pp
+.It  nodelete
+Marks the object shouldn't be unloaded at runtime.
+.Pp
+.It  nodlopen
+Marks the object not available to
+.Li dlopen .
+.Pp
+.It  nodump
+Marks the object can not be dumped by
+.Li dldump .
+.Pp
+.It  noexecstack
+Marks the object as not requiring executable stack.
+.Pp
+.It  norelro
+Don't create an ELF
+.Li PT_GNU_RELRO
+segment header in the object.
+.Pp
+.It  now
+When generating an executable or shared library, mark it to tell the dynamic
+linker to resolve all symbols when the program is started, or when the shared
+library is linked to using dlopen, instead of deferring function call resolution
+to the point when the function is first called.
+.Pp
+.It  origin
+Marks the object may contain $ORIGIN.
+.Pp
+.It  relro
+Create an ELF
+.Li PT_GNU_RELRO
+segment header in the object.
+.Pp
+.It  max-page-size= Va value
+Set the emulation maximum page size to
+.Va value .
+.Pp
+.It  common-page-size= Va value
+Set the emulation common page size to
+.Va value .
+.Pp
+.El
+Other keywords are ignored for Solaris compatibility.
+.Pp
+.It  -( Va archives -)
+.It  --start-group Va archives --end-group
+The
+.Va archives
+should be a list of archive files. They may be either explicit file names,
+or
+.Li -l
+options.
+.Pp
+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.
+.Pp
+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.
+.Pp
+.It  --accept-unknown-input-arch
+.It  --no-accept-unknown-input-arch
+Tells the linker to accept input files whose architecture cannot be recognised.
+The assumption is that the user knows what they are doing and deliberately
+wants to link in these unknown input files. This was the default behaviour
+of the linker, before release 2.14. The default behaviour from release 2.14
+onwards is to reject such input files, and so the
+.Li --accept-unknown-input-arch
+option has been added to restore the old behaviour.
+.Pp
+.It  --as-needed
+.It  --no-as-needed
+This option affects ELF DT_NEEDED tags for dynamic libraries mentioned on
+the command line after the
+.Op --as-needed
+option. Normally, the linker will add a DT_NEEDED tag for each dynamic library
+mentioned on the command line, regardless of whether the library is actually
+needed.
+.Op --as-needed
+causes DT_NEEDED tags to only be emitted for libraries that satisfy some symbol
+reference from regular objects which is undefined at the point that the library
+was linked.
+.Op --no-as-needed
+restores the default behaviour.
+.Pp
+.It  --add-needed
+.It  --no-add-needed
+This option affects the treatment of dynamic libraries from ELF DT_NEEDED
+tags in dynamic libraries mentioned on the command line after the
+.Op --no-add-needed
+option. Normally, the linker will add a DT_NEEDED tag for each dynamic library
+from DT_NEEDED tags.
+.Op --no-add-needed
+causes DT_NEEDED tags will never be emitted for those libraries from DT_NEEDED
+tags.
+.Op --add-needed
+restores the default behaviour.
+.Pp
+.It  -assert Va keyword
+This option is ignored for SunOS compatibility.
+.Pp
+.It  -Bdynamic
+.It  -dy
+.It  -call_shared
+Link against dynamic libraries. This is only meaningful on platforms for which
+shared libraries are supported. This option is normally the default on such
+platforms. The different variants of this option are for compatibility with
+various systems. You may use this option multiple times on the command line:
+it affects library searching for
+.Op -l
+options which follow it.
+.Pp
+.It  -Bgroup
+Set the
+.Li DF_1_GROUP
+flag in the
+.Li DT_FLAGS_1
+entry in the dynamic section. This causes the runtime linker to handle lookups
+in this object and its dependencies to be performed only inside the group.
+.Op --unresolved-symbols=report-all
+is implied. This option is only meaningful on ELF platforms which support
+shared libraries.
+.Pp
+.It  -Bstatic
+.It  -dn
+.It  -non_shared
+.It  -static
+Do not link against shared libraries. This is only meaningful on platforms
+for which shared libraries are supported. The different variants of this option
+are for compatibility with various systems. You may use this option multiple
+times on the command line: it affects library searching for
+.Op -l
+options which follow it. This option also implies
+.Op --unresolved-symbols=report-all .
+This option can be used with
+.Op -shared .
+Doing so means that a shared library is being created but that all of the
+library's external references must be resolved by pulling in entries from
+static libraries.
+.Pp
+.It  -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.
+.Pp
+.It  -Bsymbolic-functions
+When creating a shared library, bind references to global function symbols
+to the definition within the shared library, if any. This option is only meaningful
+on ELF platforms which support shared libraries.
+.Pp
+.It  --dynamic-list= Va dynamic-list-file
+Specify the name of a dynamic list file to the linker. This is typically used
+when creating shared libraries to specify a list of global symbols whose references
+shouldn't be bound to the definition within the shared library, or creating
+dynamically linked executables to specify a list of symbols which should be
+added to the symbol table in the executable. This option is only meaningful
+on ELF platforms which support shared libraries.
+.Pp
+The format of the dynamic list is the same as the version node without scope
+and node name. See VERSION for more information.
+.Pp
+.It  --dynamic-list-data
+Include all global data symbols to the dynamic list.
+.Pp
+.It  --dynamic-list-cpp-new
+Provide the builtin dynamic list for C++ operator new and delete. It is mainly
+useful for building shared libstdc++.
+.Pp
+.It  --dynamic-list-cpp-typeinfo
+Provide the builtin dynamic list for C++ runtime type identification.
+.Pp
+.It  --check-sections
+.It  --no-check-sections
+Asks the linker
+.Em not
+to check section addresses after they have been assigned to see if there are
+any overlaps. Normally the linker will perform this check, and if it finds
+any overlaps it will produce suitable error messages. The linker does know
+about, and does make allowances for sections in overlays. The default behaviour
+can be restored by using the command line switch
+.Op --check-sections .
+.Pp
+.It  --cref
+Output a cross reference table. If a linker map file is being generated, the
+cross reference table is printed to the map file. Otherwise, it is printed
+on the standard output.
+.Pp
+The format of the table is intentionally simple, so that it may be easily
+processed by a script if necessary. The symbols are printed out, sorted by
+name. For each symbol, a list of file names is given. If the symbol is defined,
+the first file listed is the location of the definition. The remaining files
+contain references to the symbol.
+.Pp
+.It  --no-define-common
+This option inhibits the assignment of addresses to common symbols. The script
+command
+.Li INHIBIT_COMMON_ALLOCATION
+has the same effect.See Section
+.Dq Miscellaneous Commands .
+.Pp
+The
+.Li --no-define-common
+option allows decoupling the decision to assign addresses to Common symbols
+from the choice of the output file type; otherwise a non-Relocatable output
+type forces assigning addresses to Common symbols. Using
+.Li --no-define-common
+allows Common symbols that are referenced from a shared library to be assigned
+addresses only in the main program. This eliminates the unused duplicate space
+in the shared library, and also prevents any possible confusion over resolving
+to the wrong duplicate when there are many dynamic modules with specialized
+search paths for runtime symbol resolution.
+.Pp
+.It  --defsym Va symbol= Va expression
+Create a global symbol in the output file, containing the absolute address
+given by
+.Va 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
+.Va expression
+in this context: you may give a hexadecimal constant or the name of an existing
+symbol, or use
+.Li +
+and
+.Li -
+to add or subtract hexadecimal constants or symbols. If you need more elaborate
+expressions, consider using the linker command language from a script (see Section
+.Dq Assignments ) .
+.Em Note:
+there should be no white space between
+.Va symbol ,
+the equals sign (\(lq=\(rq), and
+.Va expression .
+.Pp
+.It  --demangle[= Va style]
+.It  --no-demangle
+These options control whether to demangle symbol names in error messages and
+other output. When the linker is told to demangle, it tries to present symbol
+names in a readable fashion: it strips leading underscores if they are used
+by the object file format, and converts C++ mangled symbol names into user
+readable names. Different compilers have different mangling styles. The optional
+demangling style argument can be used to choose an appropriate demangling
+style for your compiler. The linker will demangle by default unless the environment
+variable
+.Li COLLECT_NO_DEMANGLE
+is set. These options may be used to override the default.
+.Pp
+.It  --dynamic-linker Va 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.
+.Pp
+.It  --fatal-warnings
+Treat all warnings as errors.
+.Pp
+.It  --force-exe-suffix
+Make sure that an output file has a .exe suffix.
+.Pp
+If a successfully built fully linked output file does not have a
+.Li .exe
+or
+.Li .dll
+suffix, this option forces the linker to copy the output file to one of the
+same name with a
+.Li .exe
+suffix. This option is useful when using unmodified Unix makefiles on a Microsoft
+Windows host, since some versions of Windows won't run an image unless it
+ends in a
+.Li .exe
+suffix.
+.Pp
+.It  --gc-sections
+.It  --no-gc-sections
+Enable garbage collection of unused input sections. It is ignored on targets
+that do not support this option. This option is not compatible with
+.Li -r
+or
+.Li --emit-relocs .
+The default behaviour (of not performing this garbage collection) can be restored
+by specifying
+.Li --no-gc-sections
+on the command line.
+.Pp
+.It  --print-gc-sections
+.It  --no-print-gc-sections
+List all sections removed by garbage collection. The listing is printed on
+stderr. This option is only effective if garbage collection has been enabled
+via the
+.Li --gc-sections )
+option. The default behaviour (of not listing the sections that are removed)
+can be restored by specifying
+.Li --no-print-gc-sections
+on the command line.
+.Pp
+.It  --help
+Print a summary of the command-line options on the standard output and exit.
+.Pp
+.It  --target-help
+Print a summary of all target specific options on the standard output and
+exit.
+.Pp
+.It  -Map Va mapfile
+Print a link map to the file
+.Va mapfile .
+See the description of the
+.Op -M
+option, above.
+.Pp
+.It  --no-keep-memory
+.Xr ld
+normally optimizes for speed over memory usage by caching the symbol tables
+of input files in memory. This option tells
+.Xr ld
+to instead optimize for memory usage, by rereading the symbol tables as necessary.
+This may be required if
+.Xr ld
+runs out of memory space while linking a large executable.
+.Pp
+.It  --no-undefined
+.It  -z defs
+Report unresolved symbol references from regular object files. This is done
+even if the linker is creating a non-symbolic shared library. The switch
+.Op --[no-]allow-shlib-undefined
+controls the behaviour for reporting unresolved references found in shared
+libraries being linked in.
+.Pp
+.It  --allow-multiple-definition
+.It  -z muldefs
+Normally when a symbol is defined multiple times, the linker will report a
+fatal error. These options allow multiple definitions and the first definition
+will be used.
+.Pp
+.It  --allow-shlib-undefined
+.It  --no-allow-shlib-undefined
+Allows (the default) or disallows undefined symbols in shared libraries. This
+switch is similar to
+.Op --no-undefined
+except that it determines the behaviour when the undefined symbols are in
+a shared library rather than a regular object file. It does not affect how
+undefined symbols in regular object files are handled.
+.Pp
+The reason that
+.Op --allow-shlib-undefined
+is the default is that the shared library being specified at link time may
+not be the same as the one that is available at load time, so the symbols
+might actually be resolvable at load time. Plus there are some systems, (eg
+BeOS) where undefined symbols in shared libraries is normal. (The kernel patches
+them at load time to select which function is most appropriate for the current
+architecture. This is used for example to dynamically select an appropriate
+memset function). Apparently it is also normal for HPPA shared libraries to
+have undefined symbols.
+.Pp
+.It  --no-undefined-version
+Normally when a symbol has an undefined version, the linker will ignore it.
+This option disallows symbols with undefined version and a fatal error will
+be issued instead.
+.Pp
+.It  --default-symver
+Create and use a default symbol version (the soname) for unversioned exported
+symbols.
+.Pp
+.It  --default-imported-symver
+Create and use a default symbol version (the soname) for unversioned imported
+symbols.
+.Pp
+.It  --no-warn-mismatch
+Normally
+.Xr ld
+will give an error if you try to link together input files that are mismatched
+for some reason, perhaps because they have been compiled for different processors
+or for different endiannesses. This option tells
+.Xr ld
+that it should silently permit such possible errors. This option should only
+be used with care, in cases when you have taken some special action that ensures
+that the linker errors are inappropriate.
+.Pp
+.It  --no-warn-search-mismatch
+Normally
+.Xr ld
+will give a warning if it finds an incompatible library during a library search.
+This option silences the warning.
+.Pp
+.It  --no-whole-archive
+Turn off the effect of the
+.Op --whole-archive
+option for subsequent archive files.
+.Pp
+.It  --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.
+.Pp
+.It  -nostdlib
+Only search library directories explicitly specified on the command line.
+Library directories specified in linker scripts (including linker scripts
+specified on the command line) are ignored.
+.Pp
+.It  --oformat Va output-format
+.Xr ld
+may be configured to support more than one kind of object file. If your
+.Xr ld
+is configured this way, you can use the
+.Li --oformat
+option to specify the binary format for the output object file. Even when
+.Xr ld
+is configured to support alternative object formats, you don't usually need
+to specify this, as
+.Xr ld
+should be configured to produce as a default output format the most usual
+format on each machine.
+.Va 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
+.Li objdump -i . )
+The script command
+.Li OUTPUT_FORMAT
+can also specify the output format, but this option overrides it.See Section
+.Dq BFD .
+.Pp
+.It  -pie
+.It  --pic-executable
+Create a position independent executable. This is currently only supported
+on ELF platforms. Position independent executables are similar to shared libraries
+in that they are relocated by the dynamic linker to the virtual address the
+OS chooses for them (which can vary between invocations). Like normal dynamically
+linked executables they can be executed and symbols defined in the executable
+cannot be overridden by shared libraries.
+.Pp
+.It  -qmagic
+This option is ignored for Linux compatibility.
+.Pp
+.It  -Qy
+This option is ignored for SVR4 compatibility.
+.Pp
+.It  --relax
+An option with machine dependent effects. This option is only supported on
+a few targets.See Section
+.Dq H8/300 .
+See Section.Dq i960 .
+See Section.Dq Xtensa .
+See Section.Dq M68HC11/68HC12 .
+See Section.Dq PowerPC ELF32 .
+.Pp
+On some platforms, the
+.Li --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.
+.Pp
+On some platforms these link time global optimizations may make symbolic debugging
+of the resulting executable impossible. This is known to be the case for the
+Matsushita MN10200 and MN10300 family of processors.
+.Pp
+On platforms where this is not supported,
+.Li --relax
+is accepted, but ignored.
+.Pp
+.It  --retain-symbols-file Va filename
+Retain
+.Em only
+the symbols listed in the file
+.Va filename ,
+discarding all others.
+.Va filename
+is simply a flat file, with one symbol name per line. This option is especially
+useful in environments (such as VxWorks) where a large global symbol table
+is accumulated gradually, to conserve run-time memory.
+.Pp
+.Li --retain-symbols-file
+does
+.Em not
+discard undefined symbols, or symbols needed for relocations.
+.Pp
+You may only specify
+.Li --retain-symbols-file
+once in the command line. It overrides
+.Li -s
+and
+.Li -S .
+.Pp
+.It  -rpath Va dir
+Add a directory to the runtime library search path. This is used when linking
+an ELF executable with shared objects. All
+.Op -rpath
+arguments are concatenated and passed to the runtime linker, which uses them
+to locate shared objects at runtime. The
+.Op -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
+.Op -rpath-link
+option. If
+.Op -rpath
+is not used when linking an ELF executable, the contents of the environment
+variable
+.Li LD_RUN_PATH
+will be used if it is defined.
+.Pp
+The
+.Op -rpath
+option may also be used on SunOS. By default, on SunOS, the linker will form
+a runtime search patch out of all the
+.Op -L
+options it is given. If a
+.Op -rpath
+option is used, the runtime search path will be formed exclusively using the
+.Op -rpath
+options, ignoring the
+.Op -L
+options. This can be useful when using gcc, which adds many
+.Op -L
+options which may be on NFS mounted file systems.
+.Pp
+For compatibility with other ELF linkers, if the
+.Op -R
+option is followed by a directory name, rather than a file name, it is treated
+as the
+.Op -rpath
+option.
+.Pp
+.It  -rpath-link Va DIR
+When using ELF or SunOS, one shared library may require another. This happens
+when an
+.Li ld -shared
+link includes a shared library as one of the input files.
+.Pp
+When the linker encounters such a dependency when doing a non-shared, non-relocatable
+link, it will automatically try to locate the required shared library and
+include it in the link, if it is not included explicitly. In such a case,
+the
+.Op -rpath-link
+option specifies the first set of directories to search. The
+.Op -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.
+.Pp
+This option should be used with caution as it overrides the search path that
+may have been hard compiled into a shared library. In such a case it is possible
+to use unintentionally a different search path than the runtime linker would
+do.
+.Pp
+The linker uses the following search paths to locate required shared libraries:
+.Bl -enum
+.It
+Any directories specified by
+.Op -rpath-link
+options.
+.It
+Any directories specified by
+.Op -rpath
+options. The difference between
+.Op -rpath
+and
+.Op -rpath-link
+is that directories specified by
+.Op -rpath
+options are included in the executable and used at runtime, whereas the
+.Op -rpath-link
+option is only effective at link time. Searching
+.Op -rpath
+in this way is only supported by native linkers and cross linkers which have
+been configured with the
+.Op --with-sysroot
+option.
+.It
+On an ELF system, if the
+.Op -rpath
+and
+.Li rpath-link
+options were not used, search the contents of the environment variable
+.Li LD_RUN_PATH .
+It is for the native linker only.
+.It
+On SunOS, if the
+.Op -rpath
+option was not used, search any directories specified using
+.Op -L
+options.
+.It
+For a native linker, the contents of the environment variable
+.Li LD_LIBRARY_PATH .
+.It
+For a native ELF linker, the directories in
+.Li DT_RUNPATH
+or
+.Li DT_RPATH
+of a shared library are searched for shared libraries needed by it. The
+.Li DT_RPATH
+entries are ignored if
+.Li DT_RUNPATH
+entries exist.
+.It
+The default directories, normally
+.Pa /lib
+and
+.Pa /usr/lib .
+.It
+For a native linker on an ELF system, if the file
+.Pa /etc/ld.so.conf
+exists, the list of directories found in that file.
+.El
+.Pp
+If the required shared library is not found, the linker will issue a warning
+and continue with the link.
+.Pp
+.It  -shared
+.It  -Bshareable
+Create a shared library. This is currently only supported on ELF, XCOFF and
+SunOS platforms. On SunOS, the linker will automatically create a shared library
+if the
+.Op -e
+option is not used and there are undefined symbols in the link.
+.Pp
+.It  --sort-common
+This option tells
+.Xr ld
+to sort the common symbols by size when it places them in the appropriate
+output sections. First come all the one byte symbols, then all the two byte,
+then all the four byte, and then everything else. This is to prevent gaps
+between symbols due to alignment constraints.
+.Pp
+.It  --sort-section name
+This option will apply
+.Li SORT_BY_NAME
+to all wildcard section patterns in the linker script.
+.Pp
+.It  --sort-section alignment
+This option will apply
+.Li SORT_BY_ALIGNMENT
+to all wildcard section patterns in the linker script.
+.Pp
+.It  --split-by-file [ Va size]
+Similar to
+.Op --split-by-reloc
+but creates a new output section for each input file when
+.Va size
+is reached.
+.Va size
+defaults to a size of 1 if not given.
+.Pp
+.It  --split-by-reloc [ Va count]
+Tries to creates extra sections in the output file so that no single output
+section in the file contains more than
+.Va count
+relocations. This is useful when generating huge relocatable files for downloading
+into certain real time kernels with the COFF object file format; since COFF
+cannot represent more than 65535 relocations in a single section. Note that
+this will fail to work with object file formats which do not support arbitrary
+sections. The linker will not split up individual input sections for redistribution,
+so if a single input section contains more than
+.Va count
+relocations one output section will contain that many relocations.
+.Va count
+defaults to a value of 32768.
+.Pp
+.It  --stats
+Compute and display statistics about the operation of the linker, such as
+execution time and memory usage.
+.Pp
+.It  --sysroot= Va directory
+Use
+.Va directory
+as the location of the sysroot, overriding the configure-time default. This
+option is only supported by linkers that were configured using
+.Op --with-sysroot .
+.Pp
+.It  --traditional-format
+For some targets, the output of
+.Xr ld
+is different in some ways from the output of some existing linker. This switch
+requests
+.Xr ld
+to use the traditional format instead.
+.Pp
+For example, on SunOS,
+.Xr 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
+.Li dbx
+program can not read the resulting program (
+.Li gdb
+has no trouble). The
+.Li --traditional-format
+switch tells
+.Xr ld
+to not combine duplicate entries.
+.Pp
+.It  --section-start Va sectionname= Va org
+Locate a section in the output file at the absolute address given by
+.Va org .
+You may use this option as many times as necessary to locate multiple sections
+in the command line.
+.Va org
+must be a single hexadecimal integer; for compatibility with other linkers,
+you may omit the leading
+.Li 0x
+usually associated with hexadecimal values.
+.Em Note:
+there should be no white space between
+.Va sectionname ,
+the equals sign (\(lq=\(rq), and
+.Va org .
+.Pp
+.It  -Tbss Va org
+.It  -Tdata Va org
+.It  -Ttext Va org
+Same as --section-start, with
+.Li .bss ,
+.Li .data
+or
+.Li .text
+as the
+.Va sectionname .
+.Pp
+.It  --unresolved-symbols= Va method
+Determine how to handle unresolved symbols. There are four possible values
+for
+.Li method :
+.Pp
+.Bl -tag -width Ds
+.It  ignore-all
+Do not report any unresolved symbols.
+.Pp
+.It  report-all
+Report all unresolved symbols. This is the default.
+.Pp
+.It  ignore-in-object-files
+Report unresolved symbols that are contained in shared libraries, but ignore
+them if they come from regular object files.
+.Pp
+.It  ignore-in-shared-libs
+Report unresolved symbols that come from regular object files, but ignore
+them if they come from shared libraries. This can be useful when creating
+a dynamic binary and it is known that all the shared libraries that it should
+be referencing are included on the linker's command line.
+.El
+.Pp
+The behaviour for shared libraries on their own can also be controlled by
+the
+.Op --[no-]allow-shlib-undefined
+option.
+.Pp
+Normally the linker will generate an error message for each reported unresolved
+symbol but the option
+.Op --warn-unresolved-symbols
+can change this to a warning.
+.Pp
+.It  --dll-verbose
+.It  --verbose
+Display the version number for
+.Xr ld
+and list the linker emulations supported. Display which input files can and
+cannot be opened. Display the linker script being used by the linker.
+.Pp
+.It  --version-script= Va version-scriptfile
+Specify the name of a version script to the linker. This is typically used
+when creating shared libraries to specify additional information about the
+version hierarchy for the library being created. This option is only meaningful
+on ELF platforms which support shared libraries.See Section
+.Dq VERSION .
+.Pp
+.It  --warn-common
+Warn when a common symbol is combined with another common symbol or with a
+symbol definition. Unix linkers allow this somewhat sloppy practise, 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 practise, so you may get some warnings about symbols in the libraries
+as well as in your programs.
+.Pp
+There are three kinds of global symbols, illustrated here by C examples:
+.Pp
+.Bl -tag -width Ds
+.It  int i = 1;
+A definition, which goes in the initialized data section of the output file.
+.Pp
+.It  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.
+.Pp
+.It  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.
+.El
+.Pp
+The
+.Li --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.
+.Pp
+.Bl -enum
+.It
+Turning a common symbol into a reference, because there is already a definition
+for the symbol.
+.Bd -literal -offset indent
+file(section): warning: common of `symbol'
+   overridden by definition
+file(section): warning: defined here
+.Ed
+.Pp
+.It
+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.
+.Bd -literal -offset indent
+file(section): warning: definition of `symbol'
+   overriding common
+file(section): warning: common is here
+.Ed
+.Pp
+.It
+Merging a common symbol with a previous same-sized common symbol.
+.Bd -literal -offset indent
+file(section): warning: multiple common
+   of `symbol'
+file(section): warning: previous common is here
+.Ed
+.Pp
+.It
+Merging a common symbol with a previous larger common symbol.
+.Bd -literal -offset indent
+file(section): warning: common of `symbol'
+   overridden by larger common
+file(section): warning: larger common is here
+.Ed
+.Pp
+.It
+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.
+.Bd -literal -offset indent
+file(section): warning: common of `symbol'
+   overriding smaller common
+file(section): warning: smaller common is here
+.Ed
+.El
+.Pp
+.It  --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.
+.Pp
+.It  --warn-multiple-gp
+Warn if multiple global pointer values are required in the output file. This
+is only meaningful for certain processors, such as the Alpha. Specifically,
+some processors put large-valued constants in a special section. A special
+register (the global pointer) points into the middle of this section, so that
+constants can be loaded efficiently via a base-register relative addressing
+mode. Since the offset in base-register relative mode is fixed and relatively
+small (e.g., 16 bits), this limits the maximum size of the constant pool.
+Thus, in large programs, it is often necessary to use multiple global pointer
+values in order to be able to address all possible constants. This option
+causes a warning to be issued whenever this case occurs.
+.Pp
+.It  --warn-once
+Only warn once for each undefined symbol, rather than once per module which
+refers to it.
+.Pp
+.It  --warn-section-align
+Warn if the address of an output section is changed because of alignment.
+Typically, the alignment will be set by an input section. The address will
+only be changed if it not explicitly specified; that is, if the
+.Li SECTIONS
+command does not specify a start address for the section (see Section
+.Dq SECTIONS ) .
+.Pp
+.It  --warn-shared-textrel
+Warn if the linker adds a DT_TEXTREL to a shared object.
+.Pp
+.It  --warn-unresolved-symbols
+If the linker is going to report an unresolved symbol (see the option
+.Op --unresolved-symbols )
+it will normally generate an error. This option makes it generate a warning
+instead.
+.Pp
+.It  --error-unresolved-symbols
+This restores the linker's default behaviour of generating errors when it
+is reporting unresolved symbols.
+.Pp
+.It  --whole-archive
+For each archive mentioned on the command line after the
+.Op --whole-archive
+option, include every object file in the archive in the link, rather than
+searching the archive for the required object files. This is normally used
+to turn an archive file into a shared library, forcing every object to be
+included in the resulting shared library. This option may be used more than
+once.
+.Pp
+Two notes when using this option from gcc: First, gcc doesn't know about this
+option, so you have to use
+.Op -Wl,-whole-archive .
+Second, don't forget to use
+.Op -Wl,-no-whole-archive
+after your list of archives, because gcc will add its own list of archives
+to your link and you may not want this flag to affect those as well.
+.Pp
+.It  --wrap Va symbol
+Use a wrapper function for
+.Va symbol .
+Any undefined reference to
+.Va symbol
+will be resolved to
+.Li __wrap_ Va symbol .
+Any undefined reference to
+.Li __real_ Va symbol
+will be resolved to
+.Va symbol .
+.Pp
+This can be used to provide a wrapper for a system function. The wrapper function
+should be called
+.Li __wrap_ Va symbol .
+If it wishes to call the system function, it should call
+.Li __real_ Va symbol .
+.Pp
+Here is a trivial example:
+.Pp
+.Bd -literal -offset indent
+void *
+__wrap_malloc (size_t c)
+{
+  printf ("malloc called with %zu\en", c);
+  return __real_malloc (c);
+}
+.Ed
+.Pp
+If you link other code with this file using
+.Op --wrap malloc ,
+then all calls to
+.Li malloc
+will call the function
+.Li __wrap_malloc
+instead. The call to
+.Li __real_malloc
+in
+.Li __wrap_malloc
+will call the real
+.Li malloc
+function.
+.Pp
+You may wish to provide a
+.Li __real_malloc
+function as well, so that links without the
+.Op --wrap
+option will succeed. If you do this, you should not put the definition of
+.Li __real_malloc
+in the same file as
+.Li __wrap_malloc ;
+if you do, the assembler may resolve the call before the linker has a chance
+to wrap it to
+.Li malloc .
+.Pp
+.It  --eh-frame-hdr
+Request creation of
+.Li .eh_frame_hdr
+section and ELF
+.Li PT_GNU_EH_FRAME
+segment header.
+.Pp
+.It  --enable-new-dtags
+.It  --disable-new-dtags
+This linker can create the new dynamic tags in ELF. But the older ELF systems
+may not understand them. If you specify
+.Op --enable-new-dtags ,
+the dynamic tags will be created as needed. If you specify
+.Op --disable-new-dtags ,
+no new dynamic tags will be created. By default, the new dynamic tags are
+not created. Note that those options are only available for ELF systems.
+.Pp
+.It  --hash-size= Va number
+Set the default size of the linker's hash tables to a prime number close to
+.Va number .
+Increasing this value can reduce the length of time it takes the linker to
+perform its tasks, at the expense of increasing the linker's memory requirements.
+Similarly reducing this value can reduce the memory requirements at the expense
+of speed.
+.Pp
+.It  --hash-style= Va style
+Set the type of linker's hash table(s).
+.Va style
+can be either
+.Li sysv
+for classic ELF
+.Li .hash
+section,
+.Li GNU
+for new style GNU
+.Li .GNU.hash
+section or
+.Li both
+for both the classic ELF
+.Li .hash
+and new style GNU
+.Li .GNU.hash
+hash tables. The default is
+.Li sysv .
+.Pp
+.It  --reduce-memory-overheads
+This option reduces memory requirements at ld runtime, at the expense of linking
+speed. This was introduced to select the old O(n^2) algorithm for link map
+file generation, rather than the new O(n) algorithm which uses about 40% more
+memory for symbol storage.
+.Pp
+Another effect of the switch is to set the default hash table size to 1021,
+which again saves memory at the cost of lengthening the linker's run time.
+This is not done however if the
+.Op --hash-size
+switch has been used.
+.Pp
+The
+.Op --reduce-memory-overheads
+switch may be also be used to enable other tradeoffs in future versions of
+the linker.
+.Pp
+.El
+.Em  Options Specific to i386 PE Targets
+.Pp
+The i386 PE linker supports the
+.Op -shared
+option, which causes the output to be a dynamically linked library (DLL) instead
+of a normal executable. You should name the output
+.Li *.dll
+when you use this option. In addition, the linker fully supports the standard
+.Li *.def
+files, which may be specified on the linker command line like an object file
+(in fact, it should precede archives it exports symbols from, to ensure that
+they get linked in, just like a normal object file).
+.Pp
+In addition to the options common to all targets, the i386 PE linker support
+additional command line options that are specific to the i386 PE target. Options
+that take values may be separated from their values by either a space or an
+equals sign.
+.Pp
+.Bl -tag -width Ds
+.It  --add-stdcall-alias
+If given, symbols with a stdcall suffix (@
+.Va nn )
+will be exported as-is and also with the suffix stripped. [This option is
+specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --base-file Va file
+Use
+.Va file
+as the name of a file in which to save the base addresses of all the relocations
+needed for generating DLLs with
+.Pa dlltool .
+[This is an i386 PE specific option]
+.Pp
+.It  --dll
+Create a DLL instead of a regular executable. You may also use
+.Op -shared
+or specify a
+.Li LIBRARY
+in a given
+.Li .def
+file. [This option is specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --enable-stdcall-fixup
+.It  --disable-stdcall-fixup
+If the link finds a symbol that it cannot resolve, it will attempt to do \(lqfuzzy
+linking\(rq by looking for another defined symbol that differs only in the format
+of the symbol name (cdecl vs stdcall) and will resolve that symbol by linking
+to the match. For example, the undefined symbol
+.Li _foo
+might be linked to the function
+.Li _foo@12 ,
+or the undefined symbol
+.Li _bar@16
+might be linked to the function
+.Li _bar .
+When the linker does this, it prints a warning, since it normally should have
+failed to link, but sometimes import libraries generated from third-party
+dlls may need this feature to be usable. If you specify
+.Op --enable-stdcall-fixup ,
+this feature is fully enabled and warnings are not printed. If you specify
+.Op --disable-stdcall-fixup ,
+this feature is disabled and such mismatches are considered to be errors.
+[This option is specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --export-all-symbols
+If given, all global symbols in the objects used to build a DLL will be exported
+by the DLL. Note that this is the default if there otherwise wouldn't be any
+exported symbols. When symbols are explicitly exported via DEF files or implicitly
+exported via function attributes, the default is to not export anything else
+unless this option is given. Note that the symbols
+.Li DllMain@12 ,
+.Li DllEntryPoint@0 ,
+.Li DllMainCRTStartup@12 ,
+and
+.Li impure_ptr
+will not be automatically exported. Also, symbols imported from other DLLs
+will not be re-exported, nor will symbols specifying the DLL's internal layout
+such as those beginning with
+.Li _head_
+or ending with
+.Li _iname .
+In addition, no symbols from
+.Li libgcc ,
+.Li libstd++ ,
+.Li libmingw32 ,
+or
+.Li crtX.o
+will be exported. Symbols whose names begin with
+.Li __rtti_
+or
+.Li __builtin_
+will not be exported, to help with C++ DLLs. Finally, there is an extensive
+list of cygwin-private symbols that are not exported (obviously, this applies
+on when building DLLs for cygwin targets). These cygwin-excludes are:
+.Li _cygwin_dll_entry@12 ,
+.Li _cygwin_crt0_common@8 ,
+.Li _cygwin_noncygwin_dll_entry@12 ,
+.Li _fmode ,
+.Li _impure_ptr ,
+.Li cygwin_attach_dll ,
+.Li cygwin_premain0 ,
+.Li cygwin_premain1 ,
+.Li cygwin_premain2 ,
+.Li cygwin_premain3 ,
+and
+.Li environ .
+[This option is specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --exclude-symbols Va symbol, Va symbol,...
+Specifies a list of symbols which should not be automatically exported. The
+symbol names may be delimited by commas or colons. [This option is specific
+to the i386 PE targeted port of the linker]
+.Pp
+.It  --file-alignment
+Specify the file alignment. Sections in the file will always begin at file
+offsets which are multiples of this number. This defaults to 512. [This option
+is specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --heap Va reserve
+.It  --heap Va reserve, Va commit
+Specify the amount of memory to reserve (and optionally commit) to be used
+as heap for this program. The default is 1Mb reserved, 4K committed. [This
+option is specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --image-base Va value
+Use
+.Va value
+as the base address of your program or dll. This is the lowest memory location
+that will be used when your program or dll is loaded. To reduce the need to
+relocate and improve performance of your dlls, each should have a unique base
+address and not overlap any other dlls. The default is 0x400000 for executables,
+and 0x10000000 for dlls. [This option is specific to the i386 PE targeted
+port of the linker]
+.Pp
+.It  --kill-at
+If given, the stdcall suffixes (@
+.Va nn )
+will be stripped from symbols before they are exported. [This option is specific
+to the i386 PE targeted port of the linker]
+.Pp
+.It  --large-address-aware
+If given, the appropriate bit in the \(lqCharacteristics\(rq field of the COFF header
+is set to indicate that this executable supports virtual addresses greater
+than 2 gigabytes. This should be used in conjunction with the /3GB or /USERVA=
+.Va value
+megabytes switch in the \(lq[operating systems]\(rq section of the BOOT.INI. Otherwise,
+this bit has no effect. [This option is specific to PE targeted ports of the
+linker]
+.Pp
+.It  --major-image-version Va value
+Sets the major number of the \(lqimage version\(rq. Defaults to 1. [This option is
+specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --major-os-version Va value
+Sets the major number of the \(lqos version\(rq. Defaults to 4. [This option is specific
+to the i386 PE targeted port of the linker]
+.Pp
+.It  --major-subsystem-version Va value
+Sets the major number of the \(lqsubsystem version\(rq. Defaults to 4. [This option
+is specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --minor-image-version Va value
+Sets the minor number of the \(lqimage version\(rq. Defaults to 0. [This option is
+specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --minor-os-version Va value
+Sets the minor number of the \(lqos version\(rq. Defaults to 0. [This option is specific
+to the i386 PE targeted port of the linker]
+.Pp
+.It  --minor-subsystem-version Va value
+Sets the minor number of the \(lqsubsystem version\(rq. Defaults to 0. [This option
+is specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --output-def Va file
+The linker will create the file
+.Va file
+which will contain a DEF file corresponding to the DLL the linker is generating.
+This DEF file (which should be called
+.Li *.def )
+may be used to create an import library with
+.Li dlltool
+or may be used as a reference to automatically or implicitly exported symbols.
+[This option is specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --out-implib Va file
+The linker will create the file
+.Va file
+which will contain an import lib corresponding to the DLL the linker is generating.
+This import lib (which should be called
+.Li *.dll.a
+or
+.Li *.a
+may be used to link clients against the generated DLL; this behaviour makes
+it possible to skip a separate
+.Li dlltool
+import library creation step. [This option is specific to the i386 PE targeted
+port of the linker]
+.Pp
+.It  --enable-auto-image-base
+Automatically choose the image base for DLLs, unless one is specified using
+the
+.Li --image-base
+argument. By using a hash generated from the dllname to create unique image
+bases for each DLL, in-memory collisions and relocations which can delay program
+execution are avoided. [This option is specific to the i386 PE targeted port
+of the linker]
+.Pp
+.It  --disable-auto-image-base
+Do not automatically generate a unique image base. If there is no user-specified
+image base (
+.Li --image-base )
+then use the platform default. [This option is specific to the i386 PE targeted
+port of the linker]
+.Pp
+.It  --dll-search-prefix Va string
+When linking dynamically to a dll without an import library, search for
+.Li <string><basename>.dll
+in preference to
+.Li lib<basename>.dll .
+This behaviour allows easy distinction between DLLs built for the various
+"subplatforms": native, cygwin, uwin, pw, etc. For instance, cygwin DLLs typically
+use
+.Li --dll-search-prefix=cyg .
+[This option is specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --enable-auto-import
+Do sophisticated linking of
+.Li _symbol
+to
+.Li __imp__symbol
+for DATA imports from DLLs, and create the necessary thunking symbols when
+building the import libraries with those DATA exports. Note: Use of the 'auto-import'
+extension will cause the text section of the image file to be made writable.
+This does not conform to the PE-COFF format specification published by Microsoft.
+.Pp
+Using 'auto-import' generally will 'just work' -- but sometimes you may see
+this message:
+.Pp
+"variable '<var>' can't be auto-imported. Please read the documentation for
+ld's
+.Li --enable-auto-import
+for details."
+.Pp
+This message occurs when some (sub)expression accesses an address ultimately
+given by the sum of two constants (Win32 import tables only allow one). Instances
+where this may occur include accesses to member fields of struct variables
+imported from a DLL, as well as using a constant index into an array variable
+imported from a DLL. Any multiword variable (arrays, structs, long long, etc)
+may trigger this error condition. However, regardless of the exact data type
+of the offending exported variable, ld will always detect it, issue the warning,
+and exit.
+.Pp
+There are several ways to address this difficulty, regardless of the data
+type of the exported variable:
+.Pp
+One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task
+of adjusting references in your client code for runtime environment, so this
+method works only when runtime environment supports this feature.
+.Pp
+A second solution is to force one of the 'constants' to be a variable -- that
+is, unknown and un-optimizable at compile time. For arrays, there are two
+possibilities: a) make the indexee (the array's address) a variable, or b)
+make the 'constant' index a variable. Thus:
+.Pp
+.Bd -literal -offset indent
+extern type extern_array[];
+extern_array[1] --> 
+   { volatile type *t=extern_array; t[1] }
+.Ed
+.Pp
+or
+.Pp
+.Bd -literal -offset indent
+extern type extern_array[];
+extern_array[1] --> 
+   { volatile int t=1; extern_array[t] }
+.Ed
+.Pp
+For structs (and most other multiword data types) the only option is to make
+the struct itself (or the long long, or the ...) variable:
+.Pp
+.Bd -literal -offset indent
+extern struct s extern_struct;
+extern_struct.field --> 
+   { volatile struct s *t=&extern_struct; t->field }
+.Ed
+.Pp
+or
+.Pp
+.Bd -literal -offset indent
+extern long long extern_ll;
+extern_ll -->
+  { volatile long long * local_ll=&extern_ll; *local_ll }
+.Ed
+.Pp
+A third method of dealing with this difficulty is to abandon 'auto-import'
+for the offending symbol and mark it with
+.Li __declspec(dllimport) .
+However, in practise that requires using compile-time #defines to indicate
+whether you are building a DLL, building client code that will link to the
+DLL, or merely building/linking to a static library. In making the choice
+between the various methods of resolving the 'direct address with constant
+offset' problem, you should consider typical real-world usage:
+.Pp
+Original:
+.Bd -literal -offset indent
+--foo.h
+extern int arr[];
+--foo.c
+#include "foo.h"
+void main(int argc, char **argv){
+  printf("%d\en",arr[1]);
+}
+.Ed
+.Pp
+Solution 1:
+.Bd -literal -offset indent
+--foo.h
+extern int arr[];
+--foo.c
+#include "foo.h"
+void main(int argc, char **argv){
+  /* This workaround is for win32 and cygwin; do not "optimize" */
+  volatile int *parr = arr;
+  printf("%d\en",parr[1]);
+}
+.Ed
+.Pp
+Solution 2:
+.Bd -literal -offset indent
+--foo.h
+/* Note: auto-export is assumed (no __declspec(dllexport)) */
+#if (defined(_WIN32) || defined(__CYGWIN__)) && \e
+  !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
+#define FOO_IMPORT __declspec(dllimport)
+#else
+#define FOO_IMPORT
+#endif
+extern FOO_IMPORT int arr[];
+--foo.c
+#include "foo.h"
+void main(int argc, char **argv){
+  printf("%d\en",arr[1]);
+}
+.Ed
+.Pp
+A fourth way to avoid this problem is to re-code your library to use a functional
+interface rather than a data interface for the offending variables (e.g. set_foo()
+and get_foo() accessor functions). [This option is specific to the i386 PE
+targeted port of the linker]
+.Pp
+.It  --disable-auto-import
+Do not attempt to do sophisticated linking of
+.Li _symbol
+to
+.Li __imp__symbol
+for DATA imports from DLLs. [This option is specific to the i386 PE targeted
+port of the linker]
+.Pp
+.It  --enable-runtime-pseudo-reloc
+If your code contains expressions described in --enable-auto-import section,
+that is, DATA imports from DLL with non-zero offset, this switch will create
+a vector of 'runtime pseudo relocations' which can be used by runtime environment
+to adjust references to such data in your client code. [This option is specific
+to the i386 PE targeted port of the linker]
+.Pp
+.It  --disable-runtime-pseudo-reloc
+Do not create pseudo relocations for non-zero offset DATA imports from DLLs.
+This is the default. [This option is specific to the i386 PE targeted port
+of the linker]
+.Pp
+.It  --enable-extra-pe-debug
+Show additional debug info related to auto-import symbol thunking. [This option
+is specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --section-alignment
+Sets the section alignment. Sections in memory will always begin at addresses
+which are a multiple of this number. Defaults to 0x1000. [This option is specific
+to the i386 PE targeted port of the linker]
+.Pp
+.It  --stack Va reserve
+.It  --stack Va reserve, Va commit
+Specify the amount of memory to reserve (and optionally commit) to be used
+as stack for this program. The default is 2Mb reserved, 4K committed. [This
+option is specific to the i386 PE targeted port of the linker]
+.Pp
+.It  --subsystem Va which
+.It  --subsystem Va which: Va major
+.It  --subsystem Va which: Va major. Va minor
+Specifies the subsystem under which your program will execute. The legal values
+for
+.Va which
+are
+.Li native ,
+.Li windows ,
+.Li console ,
+.Li posix ,
+and
+.Li xbox .
+You may optionally set the subsystem version also. Numeric values are also
+accepted for
+.Va which .
+[This option is specific to the i386 PE targeted port of the linker]
+.Pp
+.El
+.Em  Options specific to Motorola 68HC11 and 68HC12 targets
+.Pp
+The 68HC11 and 68HC12 linkers support specific options to control the memory
+bank switching mapping and trampoline code generation.
+.Pp
+.Bl -tag -width Ds
+.It  --no-trampoline
+This option disables the generation of trampoline. By default a trampoline
+is generated for each far function which is called using a
+.Li jsr
+instruction (this happens when a pointer to a far function is taken).
+.Pp
+.It  --bank-window Va name
+This option indicates to the linker the name of the memory region in the
+.Li MEMORY
+specification that describes the memory bank window. The definition of such
+region is then used by the linker to compute paging and addresses within the
+memory window.
+.Pp
+.El
+.Ss  Environment Variables
+You can change the behaviour of
+.Xr ld
+with the environment variables
+.Li GNUTARGET ,
+.Li LDEMULATION
+and
+.Li COLLECT_NO_DEMANGLE .
+.Pp
+.Li GNUTARGET
+determines the input-file object format if you don't use
+.Li -b
+(or its synonym
+.Li --format ) .
+Its value should be one of the BFD names for an input format (see Section
+.Dq BFD ) .
+If there is no
+.Li GNUTARGET
+in the environment,
+.Xr ld
+uses the natural format of the target. If
+.Li GNUTARGET
+is set to
+.Li 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.
+.Pp
+.Li LDEMULATION
+determines the default emulation if you don't use the
+.Li -m
+option. The emulation can affect various aspects of linker behaviour, particularly
+the default linker script. You can list the available emulations with the
+.Li --verbose
+or
+.Li -V
+options. If the
+.Li -m
+option is not used, and the
+.Li LDEMULATION
+environment variable is not defined, the default emulation depends upon how
+the linker was configured.
+.Pp
+Normally, the linker will default to demangling symbols. However, if
+.Li COLLECT_NO_DEMANGLE
+is set in the environment, then it will default to not demangling symbols.
+This environment variable is used in a similar fashion by the
+.Li gcc
+linker wrapper program. The default may be overridden by the
+.Li --demangle
+and
+.Li --no-demangle
+options.
+.Pp
+.Sh  Linker Scripts
+Every link is controlled by a
+.Em linker script .
+This script is written in the linker command language.
+.Pp
+The main purpose of the linker script is to describe how the sections in the
+input files should be mapped into the output file, and to control the memory
+layout of the output file. Most linker scripts do nothing more than this.
+However, when necessary, the linker script can also direct the linker to perform
+many other operations, using the commands described below.
+.Pp
+The linker always uses a linker script. If you do not supply one yourself,
+the linker will use a default script that is compiled into the linker executable.
+You can use the
+.Li --verbose
+command line option to display the default linker script. Certain command
+line options, such as
+.Li -r
+or
+.Li -N ,
+will affect the default linker script.
+.Pp
+You may supply your own linker script by using the
+.Li -T
+command line option. When you do this, your linker script will replace the
+default linker script.
+.Pp
+You may also use linker scripts implicitly by naming them as input files to
+the linker, as though they were files to be linked.See Section
+.Dq Implicit Linker Scripts .
+.Pp
+.Ss  Basic Linker Script Concepts
+We need to define some basic concepts and vocabulary in order to describe
+the linker script language.
+.Pp
+The linker combines input files into a single output file. The output file
+and each input file are in a special data format known as an
+.Em object file format .
+Each file is called an
+.Em object file .
+The output file is often called an
+.Em executable ,
+but for our purposes we will also call it an object file. Each object file
+has, among other things, a list of
+.Em sections .
+We sometimes refer to a section in an input file as an
+.Em input section ;
+similarly, a section in the output file is an
+.Em output section .
+.Pp
+Each section in an object file has a name and a size. Most sections also have
+an associated block of data, known as the
+.Em section contents .
+A section may be marked as
+.Em loadable ,
+which mean that the contents should be loaded into memory when the output
+file is run. A section with no contents may be
+.Em allocatable ,
+which means that an area in memory should be set aside, but nothing in particular
+should be loaded there (in some cases this memory must be zeroed out). A section
+which is neither loadable nor allocatable typically contains some sort of
+debugging information.
+.Pp
+Every loadable or allocatable output section has two addresses. The first
+is the
+.Em VMA ,
+or virtual memory address. This is the address the section will have when
+the output file is run. The second is the
+.Em LMA ,
+or load memory address. This is the address at which the section will be loaded.
+In most cases the two addresses will be the same. An example of when they
+might be different is when a data section is loaded into ROM, and then copied
+into RAM when the program starts up (this technique is often used to initialize
+global variables in a ROM based system). In this case the ROM address would
+be the LMA, and the RAM address would be the VMA.
+.Pp
+You can see the sections in an object file by using the
+.Li objdump
+program with the
+.Li -h
+option.
+.Pp
+Every object file also has a list of
+.Em symbols ,
+known as the
+.Em symbol table .
+A symbol may be defined or undefined. Each symbol has a name, and each defined
+symbol has an address, among other information. If you compile a C or C++
+program into an object file, you will get a defined symbol for every defined
+function and global or static variable. Every undefined function or global
+variable which is referenced in the input file will become an undefined symbol.
+.Pp
+You can see the symbols in an object file by using the
+.Li nm
+program, or by using the
+.Li objdump
+program with the
+.Li -t
+option.
+.Pp
+.Ss  Linker Script Format
+Linker scripts are text files.
+.Pp
+You write a linker script as a series of commands. Each command is either
+a keyword, possibly followed by arguments, or an assignment to a symbol. You
+may separate commands using semicolons. Whitespace is generally ignored.
+.Pp
+Strings such as file or format names can normally be entered directly. If
+the file name contains a character such as a comma which would otherwise serve
+to separate file names, you may put the file name in double quotes. There
+is no way to use a double quote character in a file name.
+.Pp
+You may include comments in linker scripts just as in C, delimited by
+.Li /*
+and
+.Li */ .
+As in C, comments are syntactically equivalent to whitespace.
+.Pp
+.Ss  Simple Linker Script Example
+Many linker scripts are fairly simple.
+.Pp
+The simplest possible linker script has just one command:
+.Li SECTIONS .
+You use the
+.Li SECTIONS
+command to describe the memory layout of the output file.
+.Pp
+The
+.Li SECTIONS
+command is a powerful command. Here we will describe a simple use of it. Let's
+assume your program consists only of code, initialized data, and uninitialized
+data. These will be in the
+.Li .text ,
+.Li .data ,
+and
+.Li .bss
+sections, respectively. Let's assume further that these are the only sections
+which appear in your input files.
+.Pp
+For this example, let's say that the code should be loaded at address 0x10000,
+and that the data should start at address 0x8000000. Here is a linker script
+which will do that:
+.Bd -literal -offset indent
+SECTIONS
+{
+  . = 0x10000;
+  .text : { *(.text) }
+  . = 0x8000000;
+  .data : { *(.data) }
+  .bss : { *(.bss) }
+}
+.Ed
+.Pp
+You write the
+.Li SECTIONS
+command as the keyword
+.Li SECTIONS ,
+followed by a series of symbol assignments and output section descriptions
+enclosed in curly braces.
+.Pp
+The first line inside the
+.Li SECTIONS
+command of the above example sets the value of the special symbol
+.Li . ,
+which is the location counter. If you do not specify the address of an output
+section in some other way (other ways are described later), the address is
+set from the current value of the location counter. The location counter is
+then incremented by the size of the output section. At the start of the
+.Li SECTIONS
+command, the location counter has the value
+.Li 0 .
+.Pp
+The second line defines an output section,
+.Li .text .
+The colon is required syntax which may be ignored for now. Within the curly
+braces after the output section name, you list the names of the input sections
+which should be placed into this output section. The
+.Li *
+is a wildcard which matches any file name. The expression
+.Li *(.text)
+means all
+.Li .text
+input sections in all input files.
+.Pp
+Since the location counter is
+.Li 0x10000
+when the output section
+.Li .text
+is defined, the linker will set the address of the
+.Li .text
+section in the output file to be
+.Li 0x10000 .
+.Pp
+The remaining lines define the
+.Li .data
+and
+.Li .bss
+sections in the output file. The linker will place the
+.Li .data
+output section at address
+.Li 0x8000000 .
+After the linker places the
+.Li .data
+output section, the value of the location counter will be
+.Li 0x8000000
+plus the size of the
+.Li .data
+output section. The effect is that the linker will place the
+.Li .bss
+output section immediately after the
+.Li .data
+output section in memory.
+.Pp
+The linker will ensure that each output section has the required alignment,
+by increasing the location counter if necessary. In this example, the specified
+addresses for the
+.Li .text
+and
+.Li .data
+sections will probably satisfy any alignment constraints, but the linker may
+have to create a small gap between the
+.Li .data
+and
+.Li .bss
+sections.
+.Pp
+That's it! That's a simple and complete linker script.
+.Pp
+.Ss  Simple Linker Script Commands
+In this section we describe the simple linker script commands.
+.Pp
+.Em  Setting the Entry Point
+.Pp
+The first instruction to execute in a program is called the
+.Em entry point .
+You can use the
+.Li ENTRY
+linker script command to set the entry point. The argument is a symbol name:
+.Bd -literal -offset indent
+ENTRY(symbol)
+.Ed
+.Pp
+There are several ways to set the entry point. The linker will set the entry
+point by trying each of the following methods in order, and stopping when
+one of them succeeds:
+.Bl -bullet
+.It
+the
+.Li -e
+.Va entry
+command-line option;
+.It
+the
+.Li ENTRY( Va symbol)
+command in a linker script;
+.It
+the value of the symbol
+.Li start ,
+if defined;
+.It
+the address of the first byte of the
+.Li .text
+section, if present;
+.It
+The address
+.Li 0 .
+.El
+.Pp
+.Em  Commands Dealing with Files
+.Pp
+Several linker script commands deal with files.
+.Pp
+.Bl -tag -width Ds
+.It  INCLUDE Va filename
+Include the linker script
+.Va filename
+at this point. The file will be searched for in the current directory, and
+in any directory specified with the
+.Op -L
+option. You can nest calls to
+.Li INCLUDE
+up to 10 levels deep.
+.Pp
+.It  INPUT( Va file, Va file, ...)
+.It  INPUT( Va file Va file ...)
+The
+.Li INPUT
+command directs the linker to include the named files in the link, as though
+they were named on the command line.
+.Pp
+For example, if you always want to include
+.Pa subr.o
+any time you do a link, but you can't be bothered to put it on every link
+command line, then you can put
+.Li INPUT (subr.o)
+in your linker script.
+.Pp
+In fact, if you like, you can list all of your input files in the linker script,
+and then invoke the linker with nothing but a
+.Li -T
+option.
+.Pp
+In case a
+.Em sysroot prefix
+is configured, and the filename starts with the
+.Li /
+character, and the script being processed was located inside the
+.Em sysroot prefix ,
+the filename will be looked for in the
+.Em sysroot prefix .
+Otherwise, the linker will try to open the file in the current directory.
+If it is not found, the linker will search through the archive library search
+path. See the description of
+.Li -L
+in Options,,Command Line Options.
+.Pp
+If you use
+.Li INPUT (-l Va file) ,
+.Xr ld
+will transform the name to
+.Li lib Va file.a ,
+as with the command line argument
+.Li -l .
+.Pp
+When you use the
+.Li INPUT
+command in an implicit linker script, the files will be included in the link
+at the point at which the linker script file is included. This can affect
+archive searching.
+.Pp
+.It  GROUP( Va file, Va file, ...)
+.It  GROUP( Va file Va file ...)
+The
+.Li GROUP
+command is like
+.Li 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
+.Li -(
+in Options,,Command Line Options.
+.Pp
+.It  AS_NEEDED( Va file, Va file, ...)
+.It  AS_NEEDED( Va file Va file ...)
+This construct can appear only inside of the
+.Li INPUT
+or
+.Li GROUP
+commands, among other filenames. The files listed will be handled as if they
+appear directly in the
+.Li INPUT
+or
+.Li GROUP
+commands, with the exception of ELF shared libraries, that will be added only
+when they are actually needed. This construct essentially enables
+.Op --as-needed
+option for all the files listed inside of it and restores previous
+.Op --as-needed
+resp.
+.Op --no-as-needed
+setting afterwards.
+.Pp
+.It  OUTPUT( Va filename)
+The
+.Li OUTPUT
+command names the output file. Using
+.Li OUTPUT( Va filename)
+in the linker script is exactly like using
+.Li -o Va filename
+on the command line (see Section
+.Dq Options ) .
+If both are used, the command line option takes precedence.
+.Pp
+You can use the
+.Li OUTPUT
+command to define a default name for the output file other than the usual
+default of
+.Pa a.out .
+.Pp
+.It  SEARCH_DIR( Va path)
+The
+.Li SEARCH_DIR
+command adds
+.Va path
+to the list of paths where
+.Xr ld
+looks for archive libraries. Using
+.Li SEARCH_DIR( Va path)
+is exactly like using
+.Li -L Va path
+on the command line (see Section
+.Dq Options ) .
+If both are used, then the linker will search both paths. Paths specified
+using the command line option are searched first.
+.Pp
+.It  STARTUP( Va filename)
+The
+.Li STARTUP
+command is just like the
+.Li INPUT
+command, except that
+.Va filename
+will become the first input file to be linked, as though it were specified
+first on the command line. This may be useful when using a system in which
+the entry point is always the start of the first file.
+.El
+.Pp
+.Em  Commands Dealing with Object File Formats
+.Pp
+A couple of linker script commands deal with object file formats.
+.Pp
+.Bl -tag -width Ds
+.It  OUTPUT_FORMAT( Va bfdname)
+.It  OUTPUT_FORMAT( Va default, Va big, Va little)
+The
+.Li OUTPUT_FORMAT
+command names the BFD format to use for the output file (see Section
+.Dq BFD ) .
+Using
+.Li OUTPUT_FORMAT( Va bfdname)
+is exactly like using
+.Li --oformat Va bfdname
+on the command line (see Section
+.Dq Options ) .
+If both are used, the command line option takes precedence.
+.Pp
+You can use
+.Li OUTPUT_FORMAT
+with three arguments to use different formats based on the
+.Li -EB
+and
+.Li -EL
+command line options. This permits the linker script to set the output format
+based on the desired endianness.
+.Pp
+If neither
+.Li -EB
+nor
+.Li -EL
+are used, then the output format will be the first argument,
+.Va default .
+If
+.Li -EB
+is used, the output format will be the second argument,
+.Va big .
+If
+.Li -EL
+is used, the output format will be the third argument,
+.Va little .
+.Pp
+For example, the default linker script for the MIPS ELF target uses this command:
+.Bd -literal -offset indent
+OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
+.Ed
+This says that the default format for the output file is
+.Li elf32-bigmips ,
+but if the user uses the
+.Li -EL
+command line option, the output file will be created in the
+.Li elf32-littlemips
+format.
+.Pp
+.It  TARGET( Va bfdname)
+The
+.Li TARGET
+command names the BFD format to use when reading input files. It affects subsequent
+.Li INPUT
+and
+.Li GROUP
+commands. This command is like using
+.Li -b Va bfdname
+on the command line (see Section
+.Dq Options ) .
+If the
+.Li TARGET
+command is used but
+.Li OUTPUT_FORMAT
+is not, then the last
+.Li TARGET
+command is also used to set the format for the output file.See Section
+.Dq BFD .
+.El
+.Pp
+.Em  Other Linker Script Commands
+.Pp
+There are a few other linker scripts commands.
+.Pp
+.Bl -tag -width Ds
+.It  ASSERT( Va exp, Va message)
+Ensure that
+.Va exp
+is non-zero. If it is zero, then exit the linker with an error code, and print
+.Va message .
+.Pp
+.It  EXTERN( Va symbol Va symbol ...)
+Force
+.Va symbol
+to be entered in the output file as an undefined symbol. Doing this may, for
+example, trigger linking of additional modules from standard libraries. You
+may list several
+.Va symbol
+s for each
+.Li EXTERN ,
+and you may use
+.Li EXTERN
+multiple times. This command has the same effect as the
+.Li -u
+command-line option.
+.Pp
+.It  FORCE_COMMON_ALLOCATION
+This command has the same effect as the
+.Li -d
+command-line option: to make
+.Xr ld
+assign space to common symbols even if a relocatable output file is specified
+(
+.Li -r ) .
+.Pp
+.It  INHIBIT_COMMON_ALLOCATION
+This command has the same effect as the
+.Li --no-define-common
+command-line option: to make
+.Li ld
+omit the assignment of addresses to common symbols even for a non-relocatable
+output file.
+.Pp
+.It  NOCROSSREFS( Va section Va section ...)
+This command may be used to tell
+.Xr ld
+to issue an error about any references among certain output sections.
+.Pp
+In certain types of programs, particularly on embedded systems when using
+overlays, when one section is loaded into memory, another section will not
+be. Any direct references between the two sections would be errors. For example,
+it would be an error if code in one section called a function defined in the
+other section.
+.Pp
+The
+.Li NOCROSSREFS
+command takes a list of output section names. If
+.Xr ld
+detects any cross references between the sections, it reports an error and
+returns a non-zero exit status. Note that the
+.Li NOCROSSREFS
+command uses output section names, not input section names.
+.Pp
+.It  OUTPUT_ARCH( Va bfdarch)
+Specify a particular output machine architecture. The argument is one of the
+names used by the BFD library (see Section
+.Dq BFD ) .
+You can see the architecture of an object file by using the
+.Li objdump
+program with the
+.Li -f
+option.
+.El
+.Pp
+.Ss  Assigning Values to Symbols
+You may assign a value to a symbol in a linker script. This will define the
+symbol and place it into the symbol table with a global scope.
+.Pp
+.Em  Simple Assignments
+.Pp
+You may assign to a symbol using any of the C assignment operators:
+.Pp
+.Bl -tag -width Ds
+.It  Va symbol = Va expression ;
+.It  Va symbol += Va expression ;
+.It  Va symbol -= Va expression ;
+.It  Va symbol *= Va expression ;
+.It  Va symbol /= Va expression ;
+.It  Va symbol <<= Va expression ;
+.It  Va symbol >>= Va expression ;
+.It  Va symbol &= Va expression ;
+.It  Va symbol |= Va expression ;
+.El
+.Pp
+The first case will define
+.Va symbol
+to the value of
+.Va expression .
+In the other cases,
+.Va symbol
+must already be defined, and the value will be adjusted accordingly.
+.Pp
+The special symbol name
+.Li .
+indicates the location counter. You may only use this within a
+.Li SECTIONS
+command.See Section
+.Dq Location Counter .
+.Pp
+The semicolon after
+.Va expression
+is required.
+.Pp
+Expressions are defined below; see Expressions.
+.Pp
+You may write symbol assignments as commands in their own right, or as statements
+within a
+.Li SECTIONS
+command, or as part of an output section description in a
+.Li SECTIONS
+command.
+.Pp
+The section of the symbol will be set from the section of the expression;
+for more information, see Expression Section.
+.Pp
+Here is an example showing the three different places that symbol assignments
+may be used:
+.Pp
+.Bd -literal -offset indent
+floating_point = 0;
+SECTIONS
+{
+  .text :
+    {
+      *(.text)
+      _etext = .;
+    }
+  _bdata = (. + 3) & ~ 3;
+  .data : { *(.data) }
+}
+.Ed
+In this example, the symbol
+.Li floating_point
+will be defined as zero. The symbol
+.Li _etext
+will be defined as the address following the last
+.Li .text
+input section. The symbol
+.Li _bdata
+will be defined as the address following the
+.Li .text
+output section aligned upward to a 4 byte boundary.
+.Pp
+.Em  PROVIDE
+.Pp
+In some cases, it is desirable for a linker script to define a symbol only
+if it is referenced and is not defined by any object included in the link.
+For example, traditional linkers defined the symbol
+.Li etext .
+However, ANSI C requires that the user be able to use
+.Li etext
+as a function name without encountering an error. The
+.Li PROVIDE
+keyword may be used to define a symbol, such as
+.Li etext ,
+only if it is referenced but not defined. The syntax is
+.Li PROVIDE( Va symbol = Va expression) .
+.Pp
+Here is an example of using
+.Li PROVIDE
+to define
+.Li etext :
+.Bd -literal -offset indent
+SECTIONS
+{
+  .text :
+    {
+      *(.text)
+      _etext = .;
+      PROVIDE(etext = .);
+    }
+}
+.Ed
+.Pp
+In this example, if the program defines
+.Li _etext
+(with a leading underscore), the linker will give a multiple definition error.
+If, on the other hand, the program defines
+.Li etext
+(with no leading underscore), the linker will silently use the definition
+in the program. If the program references
+.Li etext
+but does not define it, the linker will use the definition in the linker script.
+.Pp
+.Em  PROVIDE_HIDDEN
+.Pp
+Similar to
+.Li PROVIDE .
+For ELF targeted ports, the symbol will be hidden and won't be exported.
+.Pp
+.Em  Source Code Reference
+.Pp
+Accessing a linker script defined variable from source code is not intuitive.
+In particular a linker script symbol is not equivalent to a variable declaration
+in a high level language, it is instead a symbol that does not have a value.
+.Pp
+Before going further, it is important to note that compilers often transform
+names in the source code into different names when they are stored in the
+symbol table. For example, Fortran compilers commonly prepend or append an
+underscore, and C++ performs extensive
+.Li name mangling .
+Therefore there might be a discrepancy between the name of a variable as it
+is used in source code and the name of the same variable as it is defined
+in a linker script. For example in C a linker script variable might be referred
+to as:
+.Pp
+.Bd -literal -offset indent
+  extern int foo;
+.Ed
+.Pp
+But in the linker script it might be defined as:
+.Pp
+.Bd -literal -offset indent
+  _foo = 1000;
+.Ed
+.Pp
+In the remaining examples however it is assumed that no name transformation
+has taken place.
+.Pp
+When a symbol is declared in a high level language such as C, two things happen.
+The first is that the compiler reserves enough space in the program's memory
+to hold the
+.Em value
+of the symbol. The second is that the compiler creates an entry in the program's
+symbol table which holds the symbol's
+.Em address .
+ie the symbol table contains the address of the block of memory holding the
+symbol's value. So for example the following C declaration, at file scope:
+.Pp
+.Bd -literal -offset indent
+  int foo = 1000;
+.Ed
+.Pp
+creates a entry called
+.Li foo
+in the symbol table. This entry holds the address of an
+.Li int
+sized block of memory where the number 1000 is initially stored.
+.Pp
+When a program references a symbol the compiler generates code that first
+accesses the symbol table to find the address of the symbol's memory block
+and then code to read the value from that memory block. So:
+.Pp
+.Bd -literal -offset indent
+  foo = 1;
+.Ed
+.Pp
+looks up the symbol
+.Li foo
+in the symbol table, gets the address associated with this symbol and then
+writes the value 1 into that address. Whereas:
+.Pp
+.Bd -literal -offset indent
+  int * a = & foo;
+.Ed
+.Pp
+looks up the symbol
+.Li foo
+in the symbol table, gets it address and then copies this address into the
+block of memory associated with the variable
+.Li a .
+.Pp
+Linker scripts symbol declarations, by contrast, create an entry in the symbol
+table but do not assign any memory to them. Thus they are an address without
+a value. So for example the linker script definition:
+.Pp
+.Bd -literal -offset indent
+  foo = 1000;
+.Ed
+.Pp
+creates an entry in the symbol table called
+.Li foo
+which holds the address of memory location 1000, but nothing special is stored
+at address 1000. This means that you cannot access the
+.Em value
+of a linker script defined symbol - it has no value - all you can do is access
+the
+.Em address
+of a linker script defined symbol.
+.Pp
+Hence when you are using a linker script defined symbol in source code you
+should always take the address of the symbol, and never attempt to use its
+value. For example suppose you want to copy the contents of a section of memory
+called .ROM into a section called .FLASH and the linker script contains these
+declarations:
+.Pp
+.Bd -literal -offset indent
+
+  start_of_ROM   = .ROM;
+  end_of_ROM     = .ROM + sizeof (.ROM) - 1;
+  start_of_FLASH = .FLASH;
+
+.Ed
+.Pp
+Then the C source code to perform the copy would be:
+.Pp
+.Bd -literal -offset indent
+
+  extern char start_of_ROM, end_of_ROM, start_of_FLASH;
+  
+  memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
+
+.Ed
+.Pp
+Note the use of the
+.Li &
+operators. These are correct.
+.Pp
+.Ss  SECTIONS Command
+The
+.Li SECTIONS
+command tells the linker how to map input sections into output sections, and
+how to place the output sections in memory.
+.Pp
+The format of the
+.Li SECTIONS
+command is:
+.Bd -literal -offset indent
+SECTIONS
+{
+  sections-command
+  sections-command
+  ...
+}
+.Ed
+.Pp
+Each
+.Va sections-command
+may of be one of the following:
+.Pp
+.Bl -bullet
+.It
+an
+.Li ENTRY
+command (see Section
+.Dq Entry Point )
+.It
+a symbol assignment (see Section
+.Dq Assignments )
+.It
+an output section description
+.It
+an overlay description
+.El
+.Pp
+The
+.Li ENTRY
+command and symbol assignments are permitted inside the
+.Li SECTIONS
+command for convenience in using the location counter in those commands. This
+can also make the linker script easier to understand because you can use those
+commands at meaningful points in the layout of the output file.
+.Pp
+Output section descriptions and overlay descriptions are described below.
+.Pp
+If you do not use a
+.Li SECTIONS
+command in your linker script, the linker will place each input section into
+an identically named output section in the order that the sections are first
+encountered in the input files. If all input sections are present in the first
+file, for example, the order of sections in the output file will match the
+order in the first input file. The first section will be at address zero.
+.Pp
+.Em  Output Section Description
+.Pp
+The full description of an output section looks like this:
+.Bd -literal -offset indent
+
+section [address] [(type)] :
+  [AT(lma)] [ALIGN(section_align)] [SUBALIGN(subsection_align)]
+  {
+    output-section-command
+    output-section-command
+    ...
+  } [>region] [AT>lma_region] [:phdr :phdr ...] [=fillexp]
+
+.Ed
+.Pp
+Most output sections do not use most of the optional section attributes.
+.Pp
+The whitespace around
+.Va section
+is required, so that the section name is unambiguous. The colon and the curly
+braces are also required. The line breaks and other white space are optional.
+.Pp
+Each
+.Va output-section-command
+may be one of the following:
+.Pp
+.Bl -bullet
+.It
+a symbol assignment (see Section
+.Dq Assignments )
+.It
+an input section description (see Section
+.Dq Input Section )
+.It
+data values to include directly (see Section
+.Dq Output Section Data )
+.It
+a special output section keyword (see Section
+.Dq Output Section Keywords )
+.El
+.Pp
+.Em  Output Section Name
+.Pp
+The name of the output section is
+.Va section .
+.Va section
+must meet the constraints of your output format. In formats which only support
+a limited number of sections, such as
+.Li a.out ,
+the name must be one of the names supported by the format (
+.Li a.out ,
+for example, allows only
+.Li .text ,
+.Li .data
+or
+.Li .bss ) .
+If the output format supports any number of sections, but with numbers and
+not names (as is the case for Oasys), the name should be supplied as a quoted
+numeric string. A section name may consist of any sequence of characters,
+but a name which contains any unusual characters such as commas must be quoted.
+.Pp
+The output section name
+.Li /DISCARD/
+is special; Output Section Discarding.
+.Pp
+.Em  Output Section Address
+.Pp
+The
+.Va address
+is an expression for the VMA (the virtual memory address) of the output section.
+If you do not provide
+.Va address ,
+the linker will set it based on
+.Va region
+if present, or otherwise based on the current value of the location counter.
+.Pp
+If you provide
+.Va address ,
+the address of the output section will be set to precisely that. If you provide
+neither
+.Va address
+nor
+.Va region ,
+then the address of the output section will be set to the current value of
+the location counter aligned to the alignment requirements of the output section.
+The alignment requirement of the output section is the strictest alignment
+of any input section contained within the output section.
+.Pp
+For example,
+.Bd -literal -offset indent
+\&.text . : { *(.text) }
+.Ed
+and
+.Bd -literal -offset indent
+\&.text : { *(.text) }
+.Ed
+are subtly different. The first will set the address of the
+.Li .text
+output section to the current value of the location counter. The second will
+set it to the current value of the location counter aligned to the strictest
+alignment of a
+.Li .text
+input section.
+.Pp
+The
+.Va address
+may be an arbitrary expression; Expressions. For example, if you want to align
+the section on a 0x10 byte boundary, so that the lowest four bits of the section
+address are zero, you could do something like this:
+.Bd -literal -offset indent
+\&.text ALIGN(0x10) : { *(.text) }
+.Ed
+This works because
+.Li ALIGN
+returns the current location counter aligned upward to the specified value.
+.Pp
+Specifying
+.Va address
+for a section will change the value of the location counter.
+.Pp
+.Em  Input Section Description
+.Pp
+The most common output section command is an input section description.
+.Pp
+The input section description is the most basic linker script operation. You
+use output sections to tell the linker how to lay out your program in memory.
+You use input section descriptions to tell the linker how to map the input
+files into your memory layout.
+.Pp
+.No  Input Section Basics
+.Pp
+An input section description consists of a file name optionally followed by
+a list of section names in parentheses.
+.Pp
+The file name and the section name may be wildcard patterns, which we describe
+further below (see Section
+.Dq Input Section Wildcards ) .
+.Pp
+The most common input section description is to include all input sections
+with a particular name in the output section. For example, to include all
+input
+.Li .text
+sections, you would write:
+.Bd -literal -offset indent
+*(.text)
+.Ed
+Here the
+.Li *
+is a wildcard which matches any file name. To exclude a list of files from
+matching the file name wildcard, EXCLUDE_FILE may be used to match all files
+except the ones specified in the EXCLUDE_FILE list. For example:
+.Bd -literal -offset indent
+(*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors))
+.Ed
+will cause all .ctors sections from all files except
+.Pa crtend.o
+and
+.Pa otherfile.o
+to be included.
+.Pp
+There are two ways to include more than one section:
+.Bd -literal -offset indent
+*(.text .rdata)
+*(.text) *(.rdata)
+.Ed
+The difference between these is the order in which the
+.Li .text
+and
+.Li .rdata
+input sections will appear in the output section. In the first example, they
+will be intermingled, appearing in the same order as they are found in the
+linker input. In the second example, all
+.Li .text
+input sections will appear first, followed by all
+.Li .rdata
+input sections.
+.Pp
+You can specify a file name to include sections from a particular file. You
+would do this if one or more of your files contain special data that needs
+to be at a particular location in memory. For example:
+.Bd -literal -offset indent
+data.o(.data)
+.Ed
+.Pp
+If you use a file name without a list of sections, then all sections in the
+input file will be included in the output section. This is not commonly done,
+but it may by useful on occasion. For example:
+.Bd -literal -offset indent
+data.o
+.Ed
+.Pp
+When you use a file name which does not contain any wild card characters,
+the linker will first see if you also specified the file name on the linker
+command line or in an
+.Li INPUT
+command. If you did not, the linker will attempt to open the file as an input
+file, as though it appeared on the command line. Note that this differs from
+an
+.Li INPUT
+command, because the linker will not search for the file in the archive search
+path.
+.Pp
+.No  Input Section Wildcard Patterns
+.Pp
+In an input section description, either the file name or the section name
+or both may be wildcard patterns.
+.Pp
+The file name of
+.Li *
+seen in many examples is a simple wildcard pattern for the file name.
+.Pp
+The wildcard patterns are like those used by the Unix shell.
+.Pp
+.Bl -tag -width Ds
+.It  *
+matches any number of characters
+.It  ?
+matches any single character
+.It  [ Va chars]
+matches a single instance of any of the
+.Va chars ;
+the
+.Li -
+character may be used to specify a range of characters, as in
+.Li [a-z]
+to match any lower case letter
+.It  \e
+quotes the following character
+.El
+.Pp
+When a file name is matched with a wildcard, the wildcard characters will
+not match a
+.Li /
+character (used to separate directory names on Unix). A pattern consisting
+of a single
+.Li *
+character is an exception; it will always match any file name, whether it
+contains a
+.Li /
+or not. In a section name, the wildcard characters will match a
+.Li /
+character.
+.Pp
+File name wildcard patterns only match files which are explicitly specified
+on the command line or in an
+.Li INPUT
+command. The linker does not search directories to expand wildcards.
+.Pp
+If a file name matches more than one wildcard pattern, or if a file name appears
+explicitly and is also matched by a wildcard pattern, the linker will use
+the first match in the linker script. For example, this sequence of input
+section descriptions is probably in error, because the
+.Pa data.o
+rule will not be used:
+.Bd -literal -offset indent
+\&.data : { *(.data) }
+\&.data1 : { data.o(.data) }
+.Ed
+.Pp
+Normally, the linker will place files and sections matched by wildcards in
+the order in which they are seen during the link. You can change this by using
+the
+.Li SORT_BY_NAME
+keyword, which appears before a wildcard pattern in parentheses (e.g.,
+.Li SORT_BY_NAME(.text*) ) .
+When the
+.Li SORT_BY_NAME
+keyword is used, the linker will sort the files or sections into ascending
+order by name before placing them in the output file.
+.Pp
+.Li SORT_BY_ALIGNMENT
+is very similar to
+.Li SORT_BY_NAME .
+The difference is
+.Li SORT_BY_ALIGNMENT
+will sort sections into ascending order by alignment before placing them in
+the output file.
+.Pp
+.Li SORT
+is an alias for
+.Li SORT_BY_NAME .
+.Pp
+When there are nested section sorting commands in linker script, there can
+be at most 1 level of nesting for section sorting commands.
+.Pp
+.Bl -enum
+.It
+.Li SORT_BY_NAME
+(
+.Li SORT_BY_ALIGNMENT
+(wildcard section pattern)). It will sort the input sections by name first,
+then by alignment if 2 sections have the same name.
+.It
+.Li SORT_BY_ALIGNMENT
+(
+.Li SORT_BY_NAME
+(wildcard section pattern)). It will sort the input sections by alignment
+first, then by name if 2 sections have the same alignment.
+.It
+.Li SORT_BY_NAME
+(
+.Li SORT_BY_NAME
+(wildcard section pattern)) is treated the same as
+.Li SORT_BY_NAME
+(wildcard section pattern).
+.It
+.Li SORT_BY_ALIGNMENT
+(
+.Li SORT_BY_ALIGNMENT
+(wildcard section pattern)) is treated the same as
+.Li SORT_BY_ALIGNMENT
+(wildcard section pattern).
+.It
+All other nested section sorting commands are invalid.
+.El
+.Pp
+When both command line section sorting option and linker script section sorting
+command are used, section sorting command always takes precedence over the
+command line option.
+.Pp
+If the section sorting command in linker script isn't nested, the command
+line option will make the section sorting command to be treated as nested
+sorting command.
+.Pp
+.Bl -enum
+.It
+.Li SORT_BY_NAME
+(wildcard section pattern ) with
+.Op --sort-sections alignment
+is equivalent to
+.Li SORT_BY_NAME
+(
+.Li SORT_BY_ALIGNMENT
+(wildcard section pattern)).
+.It
+.Li SORT_BY_ALIGNMENT
+(wildcard section pattern) with
+.Op --sort-section name
+is equivalent to
+.Li SORT_BY_ALIGNMENT
+(
+.Li SORT_BY_NAME
+(wildcard section pattern)).
+.El
+.Pp
+If the section sorting command in linker script is nested, the command line
+option will be ignored.
+.Pp
+If you ever get confused about where input sections are going, use the
+.Li -M
+linker option to generate a map file. The map file shows precisely how input
+sections are mapped to output sections.
+.Pp
+This example shows how wildcard patterns might be used to partition files.
+This linker script directs the linker to place all
+.Li .text
+sections in
+.Li .text
+and all
+.Li .bss
+sections in
+.Li .bss .
+The linker will place the
+.Li .data
+section from all files beginning with an upper case character in
+.Li .DATA ;
+for all other files, the linker will place the
+.Li .data
+section in
+.Li .data .
+.Bd -literal -offset indent
+
+SECTIONS {
+  .text : { *(.text) }
+  .DATA : { [A-Z]*(.data) }
+  .data : { *(.data) }
+  .bss : { *(.bss) }
+}
+
+.Ed
+.Pp
+.No  Input Section for Common Symbols
+.Pp
+A special notation is needed for common symbols, because in many object file
+formats common symbols do not have a particular input section. The linker
+treats common symbols as though they are in an input section named
+.Li COMMON .
+.Pp
+You may use file names with the
+.Li COMMON
+section just as with any other input sections. You can use this to place common
+symbols from a particular input file in one section while common symbols from
+other input files are placed in another section.
+.Pp
+In most cases, common symbols in input files will be placed in the
+.Li .bss
+section in the output file. For example:
+.Bd -literal -offset indent
+\&.bss { *(.bss) *(COMMON) }
+.Ed
+.Pp
+Some object file formats have more than one type of common symbol. For example,
+the MIPS ELF object file format distinguishes standard common symbols and
+small common symbols. In this case, the linker will use a different special
+section name for other types of common symbols. In the case of MIPS ELF, the
+linker uses
+.Li COMMON
+for standard common symbols and
+.Li .scommon
+for small common symbols. This permits you to map the different types of common
+symbols into memory at different locations.
+.Pp
+You will sometimes see
+.Li [COMMON]
+in old linker scripts. This notation is now considered obsolete. It is equivalent
+to
+.Li *(COMMON) .
+.Pp
+.No  Input Section and Garbage Collection
+.Pp
+When link-time garbage collection is in use (
+.Li --gc-sections ) ,
+it is often useful to mark sections that should not be eliminated. This is
+accomplished by surrounding an input section's wildcard entry with
+.Li KEEP() ,
+as in
+.Li KEEP(*(.init))
+or
+.Li KEEP(SORT_BY_NAME(*)(.ctors)) .
+.Pp
+.No  Input Section Example
+.Pp
+The following example is a complete linker script. It tells the linker to
+read all of the sections from file
+.Pa all.o
+and place them at the start of output section
+.Li outputa
+which starts at location
+.Li 0x10000 .
+All of section
+.Li .input1
+from file
+.Pa foo.o
+follows immediately, in the same output section. All of section
+.Li .input2
+from
+.Pa foo.o
+goes into output section
+.Li outputb ,
+followed by section
+.Li .input1
+from
+.Pa foo1.o .
+All of the remaining
+.Li .input1
+and
+.Li .input2
+sections from any files are written to output section
+.Li outputc .
+.Pp
+.Bd -literal -offset indent
+
+SECTIONS {
+  outputa 0x10000 :
+    {
+    all.o
+    foo.o (.input1)
+    }
+
+
+  outputb :
+    {
+    foo.o (.input2)
+    foo1.o (.input1)
+    }
+
+
+  outputc :
+    {
+    *(.input1)
+    *(.input2)
+    }
+}
+
+.Ed
+.Pp
+.Em  Output Section Data
+.Pp
+You can include explicit bytes of data in an output section by using
+.Li BYTE ,
+.Li SHORT ,
+.Li LONG ,
+.Li QUAD ,
+or
+.Li SQUAD
+as an output section command. Each keyword is followed by an expression in
+parentheses providing the value to store (see Section
+.Dq Expressions ) .
+The value of the expression is stored at the current value of the location
+counter.
+.Pp
+The
+.Li BYTE ,
+.Li SHORT ,
+.Li LONG ,
+and
+.Li QUAD
+commands store one, two, four, and eight bytes (respectively). After storing
+the bytes, the location counter is incremented by the number of bytes stored.
+.Pp
+For example, this will store the byte 1 followed by the four byte value of
+the symbol
+.Li addr :
+.Bd -literal -offset indent
+BYTE(1)
+LONG(addr)
+.Ed
+.Pp
+When using a 64 bit host or target,
+.Li QUAD
+and
+.Li SQUAD
+are the same; they both store an 8 byte, or 64 bit, value. When both host
+and target are 32 bits, an expression is computed as 32 bits. In this case
+.Li QUAD
+stores a 32 bit value zero extended to 64 bits, and
+.Li SQUAD
+stores a 32 bit value sign extended to 64 bits.
+.Pp
+If the object file format of the output file has an explicit endianness, which
+is the normal case, the value will be stored in that endianness. When the
+object file format does not have an explicit endianness, as is true of, for
+example, S-records, the value will be stored in the endianness of the first
+input object file.
+.Pp
+Note---these commands only work inside a section description and not between
+them, so the following will produce an error from the linker:
+.Bd -literal -offset indent
+SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } } 
+.Ed
+whereas this will work:
+.Bd -literal -offset indent
+SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } } 
+.Ed
+.Pp
+You may use the
+.Li FILL
+command to set the fill pattern for the current section. It is followed by
+an expression in parentheses. Any otherwise unspecified regions of memory
+within the section (for example, gaps left due to the required alignment of
+input sections) are filled with the value of the expression, repeated as necessary.
+A
+.Li FILL
+statement covers memory locations after the point at which it occurs in the
+section definition; by including more than one
+.Li FILL
+statement, you can have different fill patterns in different parts of an output
+section.
+.Pp
+This example shows how to fill unspecified regions of memory with the value
+.Li 0x90 :
+.Bd -literal -offset indent
+FILL(0x90909090)
+.Ed
+.Pp
+The
+.Li FILL
+command is similar to the
+.Li = Va fillexp
+output section attribute, but it only affects the part of the section following
+the
+.Li FILL
+command, rather than the entire section. If both are used, the
+.Li FILL
+command takes precedence.See Section
+.Dq Output Section Fill ,
+for details on the fill expression.
+.Pp
+.Em  Output Section Keywords
+.Pp
+There are a couple of keywords which can appear as output section commands.
+.Pp
+.Bl -tag -width Ds
+.It  CREATE_OBJECT_SYMBOLS
+The command tells the linker to create a symbol for each input file. The name
+of each symbol will be the name of the corresponding input file. The section
+of each symbol will be the output section in which the
+.Li CREATE_OBJECT_SYMBOLS
+command appears.
+.Pp
+This is conventional for the a.out object file format. It is not normally
+used for any other object file format.
+.Pp
+.It  CONSTRUCTORS
+When linking using the a.out object file format, the linker uses an unusual
+set construct to support C++ global constructors and destructors. When linking
+object file formats which do not support arbitrary sections, such as ECOFF
+and XCOFF, the linker will automatically recognize C++ global constructors
+and destructors by name. For these object file formats, the
+.Li CONSTRUCTORS
+command tells the linker to place constructor information in the output section
+where the
+.Li CONSTRUCTORS
+command appears. The
+.Li CONSTRUCTORS
+command is ignored for other object file formats.
+.Pp
+The symbol
+.Li __CTOR_LIST__
+marks the start of the global constructors, and the symbol
+.Li __CTOR_END__
+marks the end. Similarly,
+.Li __DTOR_LIST__
+and
+.Li __DTOR_END__
+mark the start and end of the global destructors. The first word in the list
+is the number of entries, followed by the address of each constructor or destructor,
+followed by a zero word. The compiler must arrange to actually run the code.
+For these object file formats GNU C++ normally calls constructors from a subroutine
+.Li __main ;
+a call to
+.Li __main
+is automatically inserted into the startup code for
+.Li main .
+GNU C++ normally runs destructors either by using
+.Li atexit ,
+or directly from the function
+.Li exit .
+.Pp
+For object file formats such as
+.Li COFF
+or
+.Li ELF
+which support arbitrary section names, GNU C++ will normally arrange to put
+the addresses of global constructors and destructors into the
+.Li .ctors
+and
+.Li .dtors
+sections. Placing the following sequence into your linker script will build
+the sort of table which the GNU C++ runtime code expects to see.
+.Pp
+.Bd -literal -offset indent
+      __CTOR_LIST__ = .;
+      LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
+      *(.ctors)
+      LONG(0)
+      __CTOR_END__ = .;
+      __DTOR_LIST__ = .;
+      LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
+      *(.dtors)
+      LONG(0)
+      __DTOR_END__ = .;
+.Ed
+.Pp
+If you are using the GNU C++ support for initialization priority, which provides
+some control over the order in which global constructors are run, you must
+sort the constructors at link time to ensure that they are executed in the
+correct order. When using the
+.Li CONSTRUCTORS
+command, use
+.Li SORT_BY_NAME(CONSTRUCTORS)
+instead. When using the
+.Li .ctors
+and
+.Li .dtors
+sections, use
+.Li *(SORT_BY_NAME(.ctors))
+and
+.Li *(SORT_BY_NAME(.dtors))
+instead of just
+.Li *(.ctors)
+and
+.Li *(.dtors) .
+.Pp
+Normally the compiler and linker will handle these issues automatically, and
+you will not need to concern yourself with them. However, you may need to
+consider this if you are using C++ and writing your own linker scripts.
+.Pp
+.El
+.Em  Output Section Discarding
+.Pp
+The linker will not create output sections with no contents. This is for convenience
+when referring to input sections that may or may not be present in any of
+the input files. For example:
+.Bd -literal -offset indent
+\&.foo : { *(.foo) }
+.Ed
+will only create a
+.Li .foo
+section in the output file if there is a
+.Li .foo
+section in at least one input file, and if the input sections are not all
+empty. Other link script directives that allocate space in an output section
+will also create the output section.
+.Pp
+The linker will ignore address assignments (see Section
+.Dq Output Section Address )
+on discarded output sections, except when the linker script defines symbols
+in the output section. In that case the linker will obey the address assignments,
+possibly advancing dot even though the section is discarded.
+.Pp
+The special output section name
+.Li /DISCARD/
+may be used to discard input sections. Any input sections which are assigned
+to an output section named
+.Li /DISCARD/
+are not included in the output file.
+.Pp
+.Em  Output Section Attributes
+.Pp
+We showed above that the full description of an output section looked like
+this:
+.Bd -literal -offset indent
+
+section [address] [(type)] :
+  [AT(lma)] [ALIGN(section_align)] [SUBALIGN(subsection_align)]
+  {
+    output-section-command
+    output-section-command
+    ...
+  } [>region] [AT>lma_region] [:phdr :phdr ...] [=fillexp]
+
+.Ed
+We've already described
+.Va section ,
+.Va address ,
+and
+.Va output-section-command .
+In this section we will describe the remaining section attributes.
+.Pp
+.No  Output Section Type
+.Pp
+Each output section may have a type. The type is a keyword in parentheses.
+The following types are defined:
+.Pp
+.Bl -tag -width Ds
+.It  NOLOAD
+The section should be marked as not loadable, so that it will not be loaded
+into memory when the program is run.
+.It  DSECT
+.It  COPY
+.It  INFO
+.It  OVERLAY
+These type names are supported for backward compatibility, and are rarely
+used. They all have the same effect: the section should be marked as not allocatable,
+so that no memory is allocated for the section when the program is run.
+.El
+.Pp
+The linker normally sets the attributes of an output section based on the
+input sections which map into it. You can override this by using the section
+type. For example, in the script sample below, the
+.Li ROM
+section is addressed at memory location
+.Li 0
+and does not need to be loaded when the program is run. The contents of the
+.Li ROM
+section will appear in the linker output file as usual.
+.Bd -literal -offset indent
+
+SECTIONS {
+  ROM 0 (NOLOAD) : { ... }
+  ...
+}
+
+.Ed
+.Pp
+.No  Output Section LMA
+.Pp
+Every section has a virtual address (VMA) and a load address (LMA); see Basic
+Script Concepts. The address expression which may appear in an output section
+description sets the VMA (see Section
+.Dq Output Section Address ) .
+.Pp
+The expression
+.Va lma
+that follows the
+.Li AT
+keyword specifies the load address of the section.
+.Pp
+Alternatively, with
+.Li AT> Va lma_region
+expression, you may specify a memory region for the section's load address.See Section
+.Dq MEMORY .
+Note that if the section has not had a VMA assigned to it then the linker
+will use the
+.Va lma_region
+as the VMA region as well.
+.Pp
+If neither
+.Li AT
+nor
+.Li AT>
+is specified for an allocatable section, the linker will set the LMA such
+that the difference between VMA and LMA for the section is the same as the
+preceding output section in the same region. If there is no preceding output
+section or the section is not allocatable, the linker will set the LMA equal
+to the VMA.See Section
+.Dq Output Section Region .
+.Pp
+This feature is designed to make it easy to build a ROM image. For example,
+the following linker script creates three output sections: one called
+.Li .text ,
+which starts at
+.Li 0x1000 ,
+one called
+.Li .mdata ,
+which is loaded at the end of the
+.Li .text
+section even though its VMA is
+.Li 0x2000 ,
+and one called
+.Li .bss
+to hold uninitialized data at address
+.Li 0x3000 .
+The symbol
+.Li _data
+is defined with the value
+.Li 0x2000 ,
+which shows that the location counter holds the VMA value, not the LMA value.
+.Pp
+.Bd -literal -offset indent
+
+SECTIONS
+  {
+  .text 0x1000 : { *(.text) _etext = . ; }
+  .mdata 0x2000 :
+    AT ( ADDR (.text) + SIZEOF (.text) )
+    { _data = . ; *(.data); _edata = . ;  }
+  .bss 0x3000 :
+    { _bstart = . ;  *(.bss) *(COMMON) ; _bend = . ;}
+}
+
+.Ed
+.Pp
+The run-time initialization code for use with a program generated with this
+linker script would include something like the following, to copy the initialized
+data from the ROM image to its runtime address. Notice how this code takes
+advantage of the symbols defined by the linker script.
+.Pp
+.Bd -literal -offset indent
+
+extern char _etext, _data, _edata, _bstart, _bend;
+char *src = &_etext;
+char *dst = &_data;
+
+/* ROM has data at end of text; copy it. */
+while (dst < &_edata) {
+  *dst++ = *src++;
+}
+
+/* Zero bss */
+for (dst = &_bstart; dst< &_bend; dst++)
+  *dst = 0;
+
+.Ed
+.Pp
+.No  Forced Output Alignment
+.Pp
+You can increase an output section's alignment by using ALIGN.
+.Pp
+.No  Forced Input Alignment
+.Pp
+You can force input section alignment within an output section by using SUBALIGN.
+The value specified overrides any alignment given by input sections, whether
+larger or smaller.
+.Pp
+.No  Output Section Region
+.Pp
+You can assign a section to a previously defined region of memory by using
+.Li > Va region .
+See Section.Dq MEMORY .
+.Pp
+Here is a simple example:
+.Bd -literal -offset indent
+
+MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 }
+SECTIONS { ROM : { *(.text) } >rom }
+
+.Ed
+.Pp
+.No  Output Section Phdr
+.Pp
+You can assign a section to a previously defined program segment by using
+.Li : Va phdr .
+See Section.Dq PHDRS .
+If a section is assigned to one or more segments, then all subsequent allocated
+sections will be assigned to those segments as well, unless they use an explicitly
+.Li : Va phdr
+modifier. You can use
+.Li :NONE
+to tell the linker to not put the section in any segment at all.
+.Pp
+Here is a simple example:
+.Bd -literal -offset indent
+
+PHDRS { text PT_LOAD ; }
+SECTIONS { .text : { *(.text) } :text }
+
+.Ed
+.Pp
+.No  Output Section Fill
+.Pp
+You can set the fill pattern for an entire section by using
+.Li = Va fillexp .
+.Va fillexp
+is an expression (see Section
+.Dq Expressions ) .
+Any otherwise unspecified regions of memory within the output section (for
+example, gaps left due to the required alignment of input sections) will be
+filled with the value, repeated as necessary. If the fill expression is a
+simple hex number, ie. a string of hex digit starting with
+.Li 0x
+and without a trailing
+.Li k
+or
+.Li M ,
+then an arbitrarily long sequence of hex digits can be used to specify the
+fill pattern; Leading zeros become part of the pattern too. For all other
+cases, including extra parentheses or a unary
+.Li + ,
+the fill pattern is the four least significant bytes of the value of the expression.
+In all cases, the number is big-endian.
+.Pp
+You can also change the fill value with a
+.Li FILL
+command in the output section commands; (see Section
+.Dq Output Section Data ) .
+.Pp
+Here is a simple example:
+.Bd -literal -offset indent
+
+SECTIONS { .text : { *(.text) } =0x90909090 }
+
+.Ed
+.Pp
+.Em  Overlay Description
+.Pp
+An overlay description provides an easy way to describe sections which are
+to be loaded as part of a single memory image but are to be run at the same
+memory address. At run time, some sort of overlay manager will copy the overlaid
+sections in and out of the runtime memory address as required, perhaps by
+simply manipulating addressing bits. This approach can be useful, for example,
+when a certain region of memory is faster than another.
+.Pp
+Overlays are described using the
+.Li OVERLAY
+command. The
+.Li OVERLAY
+command is used within a
+.Li SECTIONS
+command, like an output section description. The full syntax of the
+.Li OVERLAY
+command is as follows:
+.Bd -literal -offset indent
+
+OVERLAY [start] : [NOCROSSREFS] [AT ( ldaddr )]
+  {
+    secname1
+      {
+        output-section-command
+        output-section-command
+        ...
+      } [:phdr...] [=fill]
+    secname2
+      {
+        output-section-command
+        output-section-command
+        ...
+      } [:phdr...] [=fill]
+    ...
+  } [>region] [:phdr...] [=fill]
+
+.Ed
+.Pp
+Everything is optional except
+.Li OVERLAY
+(a keyword), and each section must have a name (
+.Va secname1
+and
+.Va secname2
+above). The section definitions within the
+.Li OVERLAY
+construct are identical to those within the general
+.Li SECTIONS
+contruct (see Section
+.Dq SECTIONS ) ,
+except that no addresses and no memory regions may be defined for sections
+within an
+.Li OVERLAY .
+.Pp
+The sections are all defined with the same starting address. The load addresses
+of the sections are arranged such that they are consecutive in memory starting
+at the load address used for the
+.Li OVERLAY
+as a whole (as with normal section definitions, the load address is optional,
+and defaults to the start address; the start address is also optional, and
+defaults to the current value of the location counter).
+.Pp
+If the
+.Li NOCROSSREFS
+keyword is used, and there any references among the sections, the linker will
+report an error. Since the sections all run at the same address, it normally
+does not make sense for one section to refer directly to another.See Section
+.Dq Miscellaneous Commands .
+.Pp
+For each section within the
+.Li OVERLAY ,
+the linker automatically provides two symbols. The symbol
+.Li __load_start_ Va secname
+is defined as the starting load address of the section. The symbol
+.Li __load_stop_ Va secname
+is defined as the final load address of the section. Any characters within
+.Va secname
+which are not legal within C identifiers are removed. C (or assembler) code
+may use these symbols to move the overlaid sections around as necessary.
+.Pp
+At the end of the overlay, the value of the location counter is set to the
+start address of the overlay plus the size of the largest section.
+.Pp
+Here is an example. Remember that this would appear inside a
+.Li SECTIONS
+construct.
+.Bd -literal -offset indent
+
+  OVERLAY 0x1000 : AT (0x4000)
+   {
+     .text0 { o1/*.o(.text) }
+     .text1 { o2/*.o(.text) }
+   }
+
+.Ed
+This will define both
+.Li .text0
+and
+.Li .text1
+to start at address 0x1000.
+.Li .text0
+will be loaded at address 0x4000, and
+.Li .text1
+will be loaded immediately after
+.Li .text0 .
+The following symbols will be defined if referenced:
+.Li __load_start_text0 ,
+.Li __load_stop_text0 ,
+.Li __load_start_text1 ,
+.Li __load_stop_text1 .
+.Pp
+C code to copy overlay
+.Li .text1
+into the overlay area might look like the following.
+.Pp
+.Bd -literal -offset indent
+
+  extern char __load_start_text1, __load_stop_text1;
+  memcpy ((char *) 0x1000, &__load_start_text1,
+          &__load_stop_text1 - &__load_start_text1);
+
+.Ed
+.Pp
+Note that the
+.Li OVERLAY
+command is just syntactic sugar, since everything it does can be done using
+the more basic commands. The above example could have been written identically
+as follows.
+.Pp
+.Bd -literal -offset indent
+
+  .text0 0x1000 : AT (0x4000) { o1/*.o(.text) }
+  PROVIDE (__load_start_text0 = LOADADDR (.text0));
+  PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
+  .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
+  PROVIDE (__load_start_text1 = LOADADDR (.text1));
+  PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
+  . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
+
+.Ed
+.Pp
+.Ss  MEMORY Command
+The linker's default configuration permits allocation of all available memory.
+You can override this by using the
+.Li MEMORY
+command.
+.Pp
+The
+.Li MEMORY
+command describes the location and size of blocks of memory in the target.
+You can use it to describe which memory regions may be used by the linker,
+and which memory regions it must avoid. You can then assign sections to particular
+memory regions. The linker will set section addresses based on the memory
+regions, and will warn about regions that become too full. The linker will
+not shuffle sections around to fit into the available regions.
+.Pp
+A linker script may contain at most one use of the
+.Li MEMORY
+command. However, you can define as many blocks of memory within it as you
+wish. The syntax is:
+.Bd -literal -offset indent
+
+MEMORY
+  {
+    name [(attr)] : ORIGIN = origin, LENGTH = len
+    ...
+  }
+
+.Ed
+.Pp
+The
+.Va name
+is a name used in the linker script to refer to the region. The region name
+has no meaning outside of the linker script. Region names are stored in a
+separate name space, and will not conflict with symbol names, file names,
+or section names. Each memory region must have a distinct name.
+.Pp
+The
+.Va attr
+string is an optional list of attributes that specify whether to use a particular
+memory region for an input section which is not explicitly mapped in the linker
+script. As described in SECTIONS, if you do not specify an output section
+for some input section, the linker will create an output section with the
+same name as the input section. If you define region attributes, the linker
+will use them to select the memory region for the output section that it creates.
+.Pp
+The
+.Va attr
+string must consist only of the following characters:
+.Bl -tag -width Ds
+.It  R
+Read-only section
+.It  W
+Read/write section
+.It  X
+Executable section
+.It  A
+Allocatable section
+.It  I
+Initialized section
+.It  L
+Same as
+.Li I
+.It  !
+Invert the sense of any of the preceding attributes
+.El
+.Pp
+If a unmapped section matches any of the listed attributes other than
+.Li ! ,
+it will be placed in the memory region. The
+.Li !
+attribute reverses this test, so that an unmapped section will be placed in
+the memory region only if it does not match any of the listed attributes.
+.Pp
+The
+.Va origin
+is an numerical expression for the start address of the memory region. The
+expression must evaluate to a constant and it cannot involve any symbols.
+The keyword
+.Li ORIGIN
+may be abbreviated to
+.Li org
+or
+.Li o
+(but not, for example,
+.Li ORG ) .
+.Pp
+The
+.Va len
+is an expression for the size in bytes of the memory region. As with the
+.Va origin
+expression, the expression must be numerical only and must evaluate to a constant.
+The keyword
+.Li LENGTH
+may be abbreviated to
+.Li len
+or
+.Li l .
+.Pp
+In the following example, we specify that there are two memory regions available
+for allocation: one starting at
+.Li 0
+for 256 kilobytes, and the other starting at
+.Li 0x40000000
+for four megabytes. The linker will place into the
+.Li rom
+memory region every section which is not explicitly mapped into a memory region,
+and is either read-only or executable. The linker will place other sections
+which are not explicitly mapped into a memory region into the
+.Li ram
+memory region.
+.Pp
+.Bd -literal -offset indent
+
+MEMORY
+  {
+    rom (rx)  : ORIGIN = 0, LENGTH = 256K
+    ram (!rx) : org = 0x40000000, l = 4M
+  }
+
+.Ed
+.Pp
+Once you define a memory region, you can direct the linker to place specific
+output sections into that memory region by using the
+.Li > Va region
+output section attribute. For example, if you have a memory region named
+.Li mem ,
+you would use
+.Li >mem
+in the output section definition.See Section
+.Dq Output Section Region .
+If no address was specified for the output section, the linker will set the
+address to the next available address within the memory region. If the combined
+output sections directed to a memory region are too large for the region,
+the linker will issue an error message.
+.Pp
+It is possible to access the origin and length of a memory in an expression
+via the
+.Li ORIGIN( Va memory)
+and
+.Li LENGTH( Va memory)
+functions:
+.Pp
+.Bd -literal -offset indent
+
+  _fstack = ORIGIN(ram) + LENGTH(ram) - 4;  
+
+.Ed
+.Pp
+.Ss  PHDRS Command
+The ELF object file format uses
+.Em program headers ,
+also knows as
+.Em segments .
+The program headers describe how the program should be loaded into memory.
+You can print them out by using the
+.Li objdump
+program with the
+.Li -p
+option.
+.Pp
+When you run an ELF program on a native ELF system, the system loader reads
+the program headers in order to figure out how to load the program. This will
+only work if the program headers are set correctly. This manual does not describe
+the details of how the system loader interprets program headers; for more
+information, see the ELF ABI.
+.Pp
+The linker will create reasonable program headers by default. However, in
+some cases, you may need to specify the program headers more precisely. You
+may use the
+.Li PHDRS
+command for this purpose. When the linker sees the
+.Li PHDRS
+command in the linker script, it will not create any program headers other
+than the ones specified.
+.Pp
+The linker only pays attention to the
+.Li PHDRS
+command when generating an ELF output file. In other cases, the linker will
+simply ignore
+.Li PHDRS .
+.Pp
+This is the syntax of the
+.Li PHDRS
+command. The words
+.Li PHDRS ,
+.Li FILEHDR ,
+.Li AT ,
+and
+.Li FLAGS
+are keywords.
+.Pp
+.Bd -literal -offset indent
+
+PHDRS
+{
+  name type [ FILEHDR ] [ PHDRS ] [ AT ( address ) ]
+        [ FLAGS ( flags ) ] ;
+}
+
+.Ed
+.Pp
+The
+.Va name
+is used only for reference in the
+.Li SECTIONS
+command of the linker script. It is not put into the output file. Program
+header names are stored in a separate name space, and will not conflict with
+symbol names, file names, or section names. Each program header must have
+a distinct name.
+.Pp
+Certain program header types describe segments of memory which the system
+loader will load from the file. In the linker script, you specify the contents
+of these segments by placing allocatable output sections in the segments.
+You use the
+.Li : Va phdr
+output section attribute to place a section in a particular segment.See Section
+.Dq Output Section Phdr .
+.Pp
+It is normal to put certain sections in more than one segment. This merely
+implies that one segment of memory contains another. You may repeat
+.Li : Va phdr ,
+using it once for each segment which should contain the section.
+.Pp
+If you place a section in one or more segments using
+.Li : Va phdr ,
+then the linker will place all subsequent allocatable sections which do not
+specify
+.Li : Va phdr
+in the same segments. This is for convenience, since generally a whole set
+of contiguous sections will be placed in a single segment. You can use
+.Li :NONE
+to override the default segment and tell the linker to not put the section
+in any segment at all.
+.Pp
+You may use the
+.Li FILEHDR
+and
+.Li PHDRS
+keywords appear after the program header type to further describe the contents
+of the segment. The
+.Li FILEHDR
+keyword means that the segment should include the ELF file header. The
+.Li PHDRS
+keyword means that the segment should include the ELF program headers themselves.
+.Pp
+The
+.Va type
+may be one of the following. The numbers indicate the value of the keyword.
+.Pp
+.Bl -tag -width Ds
+.It  Li PT_NULL (0)
+Indicates an unused program header.
+.Pp
+.It  Li PT_LOAD (1)
+Indicates that this program header describes a segment to be loaded from the
+file.
+.Pp
+.It  Li PT_DYNAMIC (2)
+Indicates a segment where dynamic linking information can be found.
+.Pp
+.It  Li PT_INTERP (3)
+Indicates a segment where the name of the program interpreter may be found.
+.Pp
+.It  Li PT_NOTE (4)
+Indicates a segment holding note information.
+.Pp
+.It  Li PT_SHLIB (5)
+A reserved program header type, defined but not specified by the ELF ABI.
+.Pp
+.It  Li PT_PHDR (6)
+Indicates a segment where the program headers may be found.
+.Pp
+.It  Va expression
+An expression giving the numeric type of the program header. This may be used
+for types not defined above.
+.El
+.Pp
+You can specify that a segment should be loaded at a particular address in
+memory by using an
+.Li AT
+expression. This is identical to the
+.Li AT
+command used as an output section attribute (see Section
+.Dq Output Section LMA ) .
+The
+.Li AT
+command for a program header overrides the output section attribute.
+.Pp
+The linker will normally set the segment flags based on the sections which
+comprise the segment. You may use the
+.Li FLAGS
+keyword to explicitly specify the segment flags. The value of
+.Va flags
+must be an integer. It is used to set the
+.Li p_flags
+field of the program header.
+.Pp
+Here is an example of
+.Li PHDRS .
+This shows a typical set of program headers used on a native ELF system.
+.Pp
+.Bd -literal -offset indent
+
+PHDRS
+{
+  headers PT_PHDR PHDRS ;
+  interp PT_INTERP ;
+  text PT_LOAD FILEHDR PHDRS ;
+  data PT_LOAD ;
+  dynamic PT_DYNAMIC ;
+}
+
+SECTIONS
+{
+  . = SIZEOF_HEADERS;
+  .interp : { *(.interp) } :text :interp
+  .text : { *(.text) } :text
+  .rodata : { *(.rodata) } /* defaults to :text */
+  ...
+  . = . + 0x1000; /* move to a new page in memory */
+  .data : { *(.data) } :data
+  .dynamic : { *(.dynamic) } :data :dynamic
+  ...
+}
+
+.Ed
+.Pp
+.Ss  VERSION Command
+The linker supports symbol versions when using ELF. Symbol versions are only
+useful when using shared libraries. The dynamic linker can use symbol versions
+to select a specific version of a function when it runs a program that may
+have been linked against an earlier version of the shared library.
+.Pp
+You can include a version script directly in the main linker script, or you
+can supply the version script as an implicit linker script. You can also use
+the
+.Li --version-script
+linker option.
+.Pp
+The syntax of the
+.Li VERSION
+command is simply
+.Bd -literal -offset indent
+VERSION { version-script-commands }
+.Ed
+.Pp
+The format of the version script commands is identical to that used by Sun's
+linker in Solaris 2.5. The version script defines a tree of version nodes.
+You specify the node names and interdependencies in the version script. You
+can specify which symbols are bound to which version nodes, and you can reduce
+a specified set of symbols to local scope so that they are not globally visible
+outside of the shared library.
+.Pp
+The easiest way to demonstrate the version script language is with a few examples.
+.Pp
+.Bd -literal -offset indent
+VERS_1.1 {
+	 global:
+		 foo1;
+	 local:
+		 old*;
+		 original*;
+		 new*;
+};
+
+VERS_1.2 {
+		 foo2;
+} VERS_1.1;
+
+VERS_2.0 {
+		 bar1; bar2;
+	 extern "C++" {       
+		 ns::*;
+		 "int f(int, double)";
+         }         
+} VERS_1.2;
+.Ed
+.Pp
+This example version script defines three version nodes. The first version
+node defined is
+.Li VERS_1.1 ;
+it has no other dependencies. The script binds the symbol
+.Li foo1
+to
+.Li VERS_1.1 .
+It reduces a number of symbols to local scope so that they are not visible
+outside of the shared library; this is done using wildcard patterns, so that
+any symbol whose name begins with
+.Li old ,
+.Li original ,
+or
+.Li new
+is matched. The wildcard patterns available are the same as those used in
+the shell when matching filenames (also known as \(lqglobbing\(rq). However, if you
+specify the symbol name inside double quotes, then the name is treated as
+literal, rather than as a glob pattern.
+.Pp
+Next, the version script defines node
+.Li VERS_1.2 .
+This node depends upon
+.Li VERS_1.1 .
+The script binds the symbol
+.Li foo2
+to the version node
+.Li VERS_1.2 .
+.Pp
+Finally, the version script defines node
+.Li VERS_2.0 .
+This node depends upon
+.Li VERS_1.2 .
+The scripts binds the symbols
+.Li bar1
+and
+.Li bar2
+are bound to the version node
+.Li VERS_2.0 .
+.Pp
+When the linker finds a symbol defined in a library which is not specifically
+bound to a version node, it will effectively bind it to an unspecified base
+version of the library. You can bind all otherwise unspecified symbols to
+a given version node by using
+.Li global: *;
+somewhere in the version script.
+.Pp
+The names of the version nodes have no specific meaning other than what they
+might suggest to the person reading them. The
+.Li 2.0
+version could just as well have appeared in between
+.Li 1.1
+and
+.Li 1.2 .
+However, this would be a confusing way to write a version script.
+.Pp
+Node name can be omitted, provided it is the only version node in the version
+script. Such version script doesn't assign any versions to symbols, only selects
+which symbols will be globally visible out and which won't.
+.Pp
+.Bd -literal -offset indent
+{ global: foo; bar; local: *; };
+.Ed
+.Pp
+When you link an application against a shared library that has versioned symbols,
+the application itself knows which version of each symbol it requires, and
+it also knows which version nodes it needs from each shared library it is
+linked against. Thus at runtime, the dynamic loader can make a quick check
+to make sure that the libraries you have linked against do in fact supply
+all of the version nodes that the application will need to resolve all of
+the dynamic symbols. In this way it is possible for the dynamic linker to
+know with certainty that all external symbols that it needs will be resolvable
+without having to search for each symbol reference.
+.Pp
+The symbol versioning is in effect a much more sophisticated way of doing
+minor version checking that SunOS does. The fundamental problem that is being
+addressed here is that typically references to external functions are bound
+on an as-needed basis, and are not all bound when the application starts up.
+If a shared library is out of date, a required interface may be missing; when
+the application tries to use that interface, it may suddenly and unexpectedly
+fail. With symbol versioning, the user will get a warning when they start
+their program if the libraries being used with the application are too old.
+.Pp
+There are several GNU extensions to Sun's versioning approach. The first of
+these is the ability to bind a symbol to a version node in the source file
+where the symbol is defined instead of in the versioning script. This was
+done mainly to reduce the burden on the library maintainer. You can do this
+by putting something like:
+.Bd -literal -offset indent
+__asm__(".symver original_foo,foo@VERS_1.1");
+.Ed
+in the C source file. This renames the function
+.Li original_foo
+to be an alias for
+.Li foo
+bound to the version node
+.Li VERS_1.1 .
+The
+.Li local:
+directive can be used to prevent the symbol
+.Li original_foo
+from being exported. A
+.Li .symver
+directive takes precedence over a version script.
+.Pp
+The second GNU extension is to allow multiple versions of the same function
+to appear in a given shared library. In this way you can make an incompatible
+change to an interface without increasing the major version number of the
+shared library, while still allowing applications linked against the old interface
+to continue to function.
+.Pp
+To do this, you must use multiple
+.Li .symver
+directives in the source file. Here is an example:
+.Pp
+.Bd -literal -offset indent
+__asm__(".symver original_foo,foo@");
+__asm__(".symver old_foo,foo@VERS_1.1");
+__asm__(".symver old_foo1,foo@VERS_1.2");
+__asm__(".symver new_foo,foo@@VERS_2.0");
+.Ed
+.Pp
+In this example,
+.Li foo@
+represents the symbol
+.Li foo
+bound to the unspecified base version of the symbol. The source file that
+contains this example would define 4 C functions:
+.Li original_foo ,
+.Li old_foo ,
+.Li old_foo1 ,
+and
+.Li new_foo .
+.Pp
+When you have multiple definitions of a given symbol, there needs to be some
+way to specify a default version to which external references to this symbol
+will be bound. You can do this with the
+.Li foo@@VERS_2.0
+type of
+.Li .symver
+directive. You can only declare one version of a symbol as the default in
+this manner; otherwise you would effectively have multiple definitions of
+the same symbol.
+.Pp
+If you wish to bind a reference to a specific version of the symbol within
+the shared library, you can use the aliases of convenience (i.e.,
+.Li old_foo ) ,
+or you can use the
+.Li .symver
+directive to specifically bind to an external version of the function in question.
+.Pp
+You can also specify the language in the version script:
+.Pp
+.Bd -literal -offset indent
+VERSION extern "lang" { version-script-commands }
+.Ed
+.Pp
+The supported
+.Li lang
+s are
+.Li C ,
+.Li C++ ,
+and
+.Li Java .
+The linker will iterate over the list of symbols at the link time and demangle
+them according to
+.Li lang
+before matching them to the patterns specified in
+.Li version-script-commands .
+.Pp
+Demangled names may contains spaces and other special characters. As described
+above, you can use a glob pattern to match demangled names, or you can use
+a double-quoted string to match the string exactly. In the latter case, be
+aware that minor differences (such as differing whitespace) between the version
+script and the demangler output will cause a mismatch. As the exact string
+generated by the demangler might change in the future, even if the mangled
+name does not, you should check that all of your version directives are behaving
+as you expect when you upgrade.
+.Pp
+.Ss  Expressions in Linker Scripts
+The syntax for expressions in the linker script language is identical to that
+of C expressions. All expressions are evaluated as integers. All expressions
+are evaluated in the same size, which is 32 bits if both the host and target
+are 32 bits, and is otherwise 64 bits.
+.Pp
+You can use and set symbol values in expressions.
+.Pp
+The linker defines several special purpose builtin functions for use in expressions.
+.Pp
+.Em  Constants
+.Pp
+All constants are integers.
+.Pp
+As in C, the linker considers an integer beginning with
+.Li 0
+to be octal, and an integer beginning with
+.Li 0x
+or
+.Li 0X
+to be hexadecimal. The linker considers other integers to be decimal.
+.Pp
+In addition, you can use the suffixes
+.Li K
+and
+.Li M
+to scale a constant by
+.Li 1024
+or
+.Li 1024*1024
+respectively. For example, the following all refer to the same quantity:
+.Bd -literal -offset indent
+_fourk_1 = 4K;
+_fourk_2 = 4096;
+_fourk_3 = 0x1000;
+.Ed
+.Pp
+.Em  Symbol Names
+.Pp
+Unless quoted, symbol names start with a letter, underscore, or period and
+may include letters, digits, underscores, periods, and hyphens. Unquoted symbol
+names must not conflict with any keywords. You can specify a symbol which
+contains odd characters or has the same name as a keyword by surrounding the
+symbol name in double quotes:
+.Bd -literal -offset indent
+"SECTION" = 9;
+"with a space" = "also with a space" + 10;
+.Ed
+.Pp
+Since symbols can contain many non-alphabetic characters, it is safest to
+delimit symbols with spaces. For example,
+.Li A-B
+is one symbol, whereas
+.Li A - B
+is an expression involving subtraction.
+.Pp
+.Em  Orphan Sections
+.Pp
+Orphan sections are sections present in the input files which are not explicitly
+placed into the output file by the linker script. The linker will still copy
+these sections into the output file, but it has to guess as to where they
+should be placed. The linker uses a simple heuristic to do this. It attempts
+to place orphan sections after non-orphan sections of the same attribute,
+such as code vs data, loadable vs non-loadable, etc. If there is not enough
+room to do this then it places at the end of the file.
+.Pp
+For ELF targets, the attribute of the section includes section type as well
+as section flag.
+.Pp
+.Em  The Location Counter
+.Pp
+The special linker variable
+.Em dot
+.Li .
+always contains the current output location counter. Since the
+.Li .
+always refers to a location in an output section, it may only appear in an
+expression within a
+.Li SECTIONS
+command. The
+.Li .
+symbol may appear anywhere that an ordinary symbol is allowed in an expression.
+.Pp
+Assigning a value to
+.Li .
+will cause the location counter to be moved. This may be used to create holes
+in the output section. The location counter may not be moved backwards inside
+an output section, and may not be moved backwards outside of an output section
+if so doing creates areas with overlapping LMAs.
+.Pp
+.Bd -literal -offset indent
+SECTIONS
+{
+  output :
+    {
+      file1(.text)
+      . = . + 1000;
+      file2(.text)
+      . += 1000;
+      file3(.text)
+    } = 0x12345678;
+}
+.Ed
+In the previous example, the
+.Li .text
+section from
+.Pa file1
+is located at the beginning of the output section
+.Li output .
+It is followed by a 1000 byte gap. Then the
+.Li .text
+section from
+.Pa file2
+appears, also with a 1000 byte gap following before the
+.Li .text
+section from
+.Pa file3 .
+The notation
+.Li = 0x12345678
+specifies what data to write in the gaps (see Section
+.Dq Output Section Fill ) .
+.Pp
+Note:
+.Li .
+actually refers to the byte offset from the start of the current containing
+object. Normally this is the
+.Li SECTIONS
+statement, whose start address is 0, hence
+.Li .
+can be used as an absolute address. If
+.Li .
+is used inside a section description however, it refers to the byte offset
+from the start of that section, not an absolute address. Thus in a script
+like this:
+.Pp
+.Bd -literal -offset indent
+SECTIONS
+{
+    . = 0x100
+    .text: {
+      *(.text)
+      . = 0x200
+    }
+    . = 0x500
+    .data: {
+      *(.data)
+      . += 0x600
+    }
+}
+.Ed
+.Pp
+The
+.Li .text
+section will be assigned a starting address of 0x100 and a size of exactly
+0x200 bytes, even if there is not enough data in the
+.Li .text
+input sections to fill this area. (If there is too much data, an error will
+be produced because this would be an attempt to move
+.Li .
+backwards). The
+.Li .data
+section will start at 0x500 and it will have an extra 0x600 bytes worth of
+space after the end of the values from the
+.Li .data
+input sections and before the end of the
+.Li .data
+output section itself.
+.Pp
+Setting symbols to the value of the location counter outside of an output
+section statement can result in unexpected values if the linker needs to place
+orphan sections. For example, given the following:
+.Pp
+.Bd -literal -offset indent
+SECTIONS
+{
+    start_of_text = . ;
+    .text: { *(.text) }
+    end_of_text = . ;
+
+    start_of_data = . ;
+    .data: { *(.data) }
+    end_of_data = . ;
+}
+.Ed
+.Pp
+If the linker needs to place some input section, e.g.
+.Li .rodata ,
+not mentioned in the script, it might choose to place that section between
+.Li .text
+and
+.Li .data .
+You might think the linker should place
+.Li .rodata
+on the blank line in the above script, but blank lines are of no particular
+significance to the linker. As well, the linker doesn't associate the above
+symbol names with their sections. Instead, it assumes that all assignments
+or other statements belong to the previous output section, except for the
+special case of an assignment to
+.Li . .
+I.e., the linker will place the orphan
+.Li .rodata
+section as if the script was written as follows:
+.Pp
+.Bd -literal -offset indent
+SECTIONS
+{
+    start_of_text = . ;
+    .text: { *(.text) }
+    end_of_text = . ;
+
+    start_of_data = . ;
+    .rodata: { *(.rodata) }
+    .data: { *(.data) }
+    end_of_data = . ;
+}
+.Ed
+.Pp
+This may or may not be the script author's intention for the value of
+.Li start_of_data .
+One way to influence the orphan section placement is to assign the location
+counter to itself, as the linker assumes that an assignment to
+.Li .
+is setting the start address of a following output section and thus should
+be grouped with that section. So you could write:
+.Pp
+.Bd -literal -offset indent
+SECTIONS
+{
+    start_of_text = . ;
+    .text: { *(.text) }
+    end_of_text = . ;
+
+    . = . ;
+    start_of_data = . ;
+    .data: { *(.data) }
+    end_of_data = . ;
+}
+.Ed
+.Pp
+Now, the orphan
+.Li .rodata
+section will be placed between
+.Li end_of_text
+and
+.Li start_of_data .
+.Pp
+.Em  Operators
+.Pp
+The linker recognizes the standard C set of arithmetic operators, with the
+standard bindings and precedence levels:
+.Bd -literal -offset indent
+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)
+.Ed
+Notes: (1) Prefix operators (2)See Section
+.Dq Assignments .
+.Pp
+.Em  Evaluation
+.Pp
+The linker evaluates expressions lazily. It only computes the value of an
+expression when absolutely necessary.
+.Pp
+The linker needs some information, such as the value of the start address
+of the first section, and the origins and lengths of memory regions, in order
+to do any linking at all. These values are computed as soon as possible when
+the linker reads in the linker script.
+.Pp
+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.
+.Pp
+The sizes of sections cannot be known until after allocation, so assignments
+dependent upon these are not performed until after allocation.
+.Pp
+Some expressions, such as those depending upon the location counter
+.Li . ,
+must be evaluated during section allocation.
+.Pp
+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
+.Bd -literal -offset indent
+
+SECTIONS
+  {
+    .text 9+this_isnt_constant :
+      { *(.text) }
+  }
+
+.Ed
+will cause the error message
+.Li non constant expression for initial address .
+.Pp
+.Em  The Section of an Expression
+.Pp
+When the linker evaluates an expression, the result is either absolute or
+relative to some section. A relative expression is expressed as a fixed offset
+from the base of a section.
+.Pp
+The position of the expression within the linker script determines whether
+it is absolute or relative. An expression which appears within an output section
+definition is relative to the base of the output section. An expression which
+appears elsewhere will be absolute.
+.Pp
+A symbol set to a relative expression will be relocatable if you request relocatable
+output using the
+.Li -r
+option. That means that a further link operation may change the value of the
+symbol. The symbol's section will be the section of the relative expression.
+.Pp
+A symbol set to an absolute expression will retain the same value through
+any further link operation. The symbol will be absolute, and will not have
+any particular associated section.
+.Pp
+You can use the builtin function
+.Li ABSOLUTE
+to force an expression to be absolute when it would otherwise be relative.
+For example, to create an absolute symbol set to the address of the end of
+the output section
+.Li .data :
+.Bd -literal -offset indent
+SECTIONS
+  {
+    .data : { *(.data) _edata = ABSOLUTE(.); }
+  }
+.Ed
+If
+.Li ABSOLUTE
+were not used,
+.Li _edata
+would be relative to the
+.Li .data
+section.
+.Pp
+.Em  Builtin Functions
+.Pp
+The linker script language includes a number of builtin functions for use
+in linker script expressions.
+.Pp
+.Bl -tag -width Ds
+.It  ABSOLUTE( Va exp)
+Return the absolute (non-relocatable, as opposed to non-negative) value of
+the expression
+.Va exp .
+Primarily useful to assign an absolute value to a symbol within a section
+definition, where symbol values are normally section relative.See Section
+.Dq Expression Section .
+.Pp
+.It  ADDR( Va section)
+Return the absolute address (the VMA) of the named
+.Va section .
+Your script must previously have defined the location of that section. In
+the following example,
+.Li symbol_1
+and
+.Li symbol_2
+are assigned identical values:
+.Bd -literal -offset indent
+
+SECTIONS { ...
+  .output1 :
+    {
+    start_of_output_1 = ABSOLUTE(.);
+    ...
+    }
+  .output :
+    {
+    symbol_1 = ADDR(.output1);
+    symbol_2 = start_of_output_1;
+    }
+\&... }
+
+.Ed
+.Pp
+.It  ALIGN( Va align)
+.It  ALIGN( Va exp, Va align)
+Return the location counter (
+.Li . )
+or arbitrary expression aligned to the next
+.Va align
+boundary. The single operand
+.Li ALIGN
+doesn't change the value of the location counter---it just does arithmetic
+on it. The two operand
+.Li ALIGN
+allows an arbitrary expression to be aligned upwards (
+.Li ALIGN( Va align)
+is equivalent to
+.Li ALIGN(., Va align) ) .
+.Pp
+Here is an example which aligns the output
+.Li .data
+section to the next
+.Li 0x2000
+byte boundary after the preceding section and sets a variable within the section
+to the next
+.Li 0x8000
+boundary after the input sections:
+.Bd -literal -offset indent
+
+SECTIONS { ...
+  .data ALIGN(0x2000): {
+    *(.data)
+    variable = ALIGN(0x8000);
+  }
+\&... }
+
+.Ed
+The first use of
+.Li ALIGN
+in this example specifies the location of a section because it is used as
+the optional
+.Va address
+attribute of a section definition (see Section
+.Dq Output Section Address ) .
+The second use of
+.Li ALIGN
+is used to defines the value of a symbol.
+.Pp
+The builtin function
+.Li NEXT
+is closely related to
+.Li ALIGN .
+.Pp
+.It  ALIGNOF( Va section)
+Return the alignment in bytes of the named
+.Va section ,
+if that section has been allocated. If the section has not been allocated
+when this is evaluated, the linker will report an error. In the following
+example, the alignment of the
+.Li .output
+section is stored as the first value in that section.
+.Bd -literal -offset indent
+
+SECTIONS{ ...
+  .output {
+    LONG (ALIGNOF (.output))
+    ...
+    }
+\&... }
+
+.Ed
+.Pp
+.It  BLOCK( Va exp)
+This is a synonym for
+.Li ALIGN ,
+for compatibility with older linker scripts. It is most often seen when setting
+the address of an output section.
+.Pp
+.It  DATA_SEGMENT_ALIGN( Va maxpagesize, Va commonpagesize)
+This is equivalent to either
+.Bd -literal -offset indent
+(ALIGN(maxpagesize) + (. & (maxpagesize - 1)))
+.Ed
+or
+.Bd -literal -offset indent
+(ALIGN(maxpagesize) + (. & (maxpagesize - commonpagesize)))
+.Ed
+depending on whether the latter uses fewer
+.Va commonpagesize
+sized pages for the data segment (area between the result of this expression
+and
+.Li DATA_SEGMENT_END )
+than the former or not. If the latter form is used, it means
+.Va commonpagesize
+bytes of runtime memory will be saved at the expense of up to
+.Va commonpagesize
+wasted bytes in the on-disk file.
+.Pp
+This expression can only be used directly in
+.Li SECTIONS
+commands, not in any output section descriptions and only once in the linker
+script.
+.Va commonpagesize
+should be less or equal to
+.Va maxpagesize
+and should be the system page size the object wants to be optimized for (while
+still working on system page sizes up to
+.Va maxpagesize ) .
+.Pp
+Example:
+.Bd -literal -offset indent
+  . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
+.Ed
+.Pp
+.It  DATA_SEGMENT_END( Va exp)
+This defines the end of data segment for
+.Li DATA_SEGMENT_ALIGN
+evaluation purposes.
+.Pp
+.Bd -literal -offset indent
+  . = DATA_SEGMENT_END(.);
+.Ed
+.Pp
+.It  DATA_SEGMENT_RELRO_END( Va offset, Va exp)
+This defines the end of the
+.Li PT_GNU_RELRO
+segment when
+.Li -z relro
+option is used. Second argument is returned. When
+.Li -z relro
+option is not present,
+.Li DATA_SEGMENT_RELRO_END
+does nothing, otherwise
+.Li DATA_SEGMENT_ALIGN
+is padded so that
+.Va exp
++
+.Va offset
+is aligned to the most commonly used page boundary for particular target.
+If present in the linker script, it must always come in between
+.Li DATA_SEGMENT_ALIGN
+and
+.Li DATA_SEGMENT_END .
+.Pp
+.Bd -literal -offset indent
+  . = DATA_SEGMENT_RELRO_END(24, .);
+.Ed
+.Pp
+.It  DEFINED( Va symbol)
+Return 1 if
+.Va symbol
+is in the linker global symbol table and is defined before the statement using
+DEFINED in the script, otherwise return 0. You can use this function to provide
+default values for symbols. For example, the following script fragment shows
+how to set a global symbol
+.Li begin
+to the first location in the
+.Li .text
+section---but if a symbol called
+.Li begin
+already existed, its value is preserved:
+.Pp
+.Bd -literal -offset indent
+
+SECTIONS { ...
+  .text : {
+    begin = DEFINED(begin) ? begin : . ;
+    ...
+  }
+  ...
+}
+
+.Ed
+.Pp
+.It  LENGTH( Va memory)
+Return the length of the memory region named
+.Va memory .
+.Pp
+.It  LOADADDR( Va section)
+Return the absolute LMA of the named
+.Va section .
+This is normally the same as
+.Li ADDR ,
+but it may be different if the
+.Li AT
+attribute is used in the output section definition (see Section
+.Dq Output Section LMA ) .
+.Pp
+.It  MAX( Va exp1, Va exp2)
+Returns the maximum of
+.Va exp1
+and
+.Va exp2 .
+.Pp
+.It  MIN( Va exp1, Va exp2)
+Returns the minimum of
+.Va exp1
+and
+.Va exp2 .
+.Pp
+.It  NEXT( Va exp)
+Return the next unallocated address that is a multiple of
+.Va exp .
+This function is closely related to
+.Li ALIGN( Va exp) ;
+unless you use the
+.Li MEMORY
+command to define discontinuous memory for the output file, the two functions
+are equivalent.
+.Pp
+.It  ORIGIN( Va memory)
+Return the origin of the memory region named
+.Va memory .
+.Pp
+.It  SEGMENT_START( Va segment, Va default)
+Return the base address of the named
+.Va segment .
+If an explicit value has been given for this segment (with a command-line
+.Li -T
+option) that value will be returned; otherwise the value will be
+.Va default .
+At present, the
+.Li -T
+command-line option can only be used to set the base address for the \(lqtext\(rq,
+\(lqdata\(rq, and \(lqbss\(rq sections, but you use
+.Li SEGMENT_START
+with any segment name.
+.Pp
+.It  SIZEOF( Va section)
+Return the size in bytes of the named
+.Va section ,
+if that section has been allocated. If the section has not been allocated
+when this is evaluated, the linker will report an error. In the following
+example,
+.Li symbol_1
+and
+.Li symbol_2
+are assigned identical values:
+.Bd -literal -offset indent
+
+SECTIONS{ ...
+  .output {
+    .start = . ;
+    ...
+    .end = . ;
+    }
+  symbol_1 = .end - .start ;
+  symbol_2 = SIZEOF(.output);
+\&... }
+
+.Ed
+.Pp
+.It  SIZEOF_HEADERS
+.It  sizeof_headers
+Return the size in bytes of the output file's headers. This is information
+which appears at the start of the output file. You can use this number when
+setting the start address of the first section, if you choose, to facilitate
+paging.
+.Pp
+When producing an ELF output file, if the linker script uses the
+.Li SIZEOF_HEADERS
+builtin function, the linker must compute the number of program headers before
+it has determined all the section addresses and sizes. If the linker later
+discovers that it needs additional program headers, it will report an error
+.Li not enough room for program headers .
+To avoid this error, you must avoid using the
+.Li SIZEOF_HEADERS
+function, or you must rework your linker script to avoid forcing the linker
+to use additional program headers, or you must define the program headers
+yourself using the
+.Li PHDRS
+command (see Section
+.Dq PHDRS ) .
+.El
+.Pp
+.Ss  Implicit Linker Scripts
+If you specify a linker input file which the linker can not recognize as an
+object file or an archive file, it will try to read the file as a linker script.
+If the file can not be parsed as a linker script, the linker will report an
+error.
+.Pp
+An implicit linker script will not replace the default linker script.
+.Pp
+Typically an implicit linker script would contain only symbol assignments,
+or the
+.Li INPUT ,
+.Li GROUP ,
+or
+.Li VERSION
+commands.
+.Pp
+Any input files read because of an implicit linker script will be read at
+the position in the command line where the implicit linker script was read.
+This can affect archive searching.
+.Pp
+.Sh  Machine Dependent Features
+.Xr ld
+has additional features on some platforms; the following sections describe
+them. Machines where
+.Xr ld
+has no additional functionality are not listed.
+.Pp
+.Ss  Xr ld and the H8/300
+For the H8/300,
+.Xr ld
+can perform these global optimizations when you specify the
+.Li --relax
+command-line option.
+.Pp
+.Bl -tag -width Ds
+.It  relaxing address modes
+.Xr ld
+finds all
+.Li jsr
+and
+.Li jmp
+instructions whose targets are within eight bits, and turns them into eight-bit
+program-counter relative
+.Li bsr
+and
+.Li bra
+instructions, respectively.
+.Pp
+.It  synthesizing instructions
+.Xr ld
+finds all
+.Li 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
+.Li mov.b Li @ Va aa:16
+into
+.Li mov.b Li @ Va aa:8
+whenever the address
+.Va aa
+is in the top page of memory).
+.Pp
+.It  bit manipulation instructions
+.Xr ld
+finds all bit manipulation instructions like
+.Li band, bclr, biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor
+which use 32 bit and 16 bit absolute address form, but refer to the top page
+of memory, and changes them to use the 8 bit address form. (That is: the linker
+turns
+.Li bset #xx:3, Li @ Va aa:32
+into
+.Li bset #xx:3, Li @ Va aa:8
+whenever the address
+.Va aa
+is in the top page of memory).
+.Pp
+.It  system control instructions
+.Xr ld
+finds all
+.Li ldc.w, stc.w
+instructions which use the 32 bit absolute address form, but refer to the
+top page of memory, and changes them to use 16 bit address form. (That is:
+the linker turns
+.Li ldc.w Li @ Va aa:32,ccr
+into
+.Li ldc.w Li @ Va aa:16,ccr
+whenever the address
+.Va aa
+is in the top page of memory).
+.El
+.Pp
+.Ss  Xr ld and the Intel 960 Family
+You can use the
+.Li -A Va 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.
+.Pp
+For example, if your
+.Xr ld
+command line included
+.Li -ACA
+as well as
+.Li -ltry
+, the linker would look (in its built-in search paths, and in any paths you
+specify with
+.Li -L )
+for a library with the names
+.Pp
+.Bd -literal -offset indent
+
+try
+libtry.a
+tryca
+libtryca.a
+
+.Ed
+.Pp
+The first two possibilities would be considered in any event; the last two
+are due to the use of
+.Li -ACA
+\&.
+.Pp
+You can meaningfully use
+.Li -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
+.Li -l
+specifies a library.
+.Pp
+.Xr ld
+supports the
+.Li --relax
+option for the i960 family. If you specify
+.Li --relax ,
+.Xr ld
+finds all
+.Li balx
+and
+.Li calx
+instructions whose targets are within 24 bits, and turns them into 24-bit
+program-counter relative
+.Li bal
+and
+.Li cal
+instructions, respectively.
+.Xr ld
+also turns
+.Li cal
+instructions into
+.Li bal
+instructions when it determines that the target subroutine is a leaf routine
+(that is, the target subroutine does not itself call any subroutines).
+.Pp
+.Ss  Xr ld and the Motorola 68HC11 and 68HC12 families
+.Em  Linker Relaxation
+.Pp
+For the Motorola 68HC11,
+.Xr ld
+can perform these global optimizations when you specify the
+.Li --relax
+command-line option.
+.Pp
+.Bl -tag -width Ds
+.It  relaxing address modes
+.Xr ld
+finds all
+.Li jsr
+and
+.Li jmp
+instructions whose targets are within eight bits, and turns them into eight-bit
+program-counter relative
+.Li bsr
+and
+.Li bra
+instructions, respectively.
+.Pp
+.Xr ld
+also looks at all 16-bit extended addressing modes and transforms them in
+a direct addressing mode when the address is in page 0 (between 0 and 0x0ff).
+.Pp
+.It  relaxing gcc instruction group
+When
+.Xr gcc
+is called with
+.Op -mrelax ,
+it can emit group of instructions that the linker can optimize to use a 68HC11
+direct addressing mode. These instructions consists of
+.Li bclr
+or
+.Li bset
+instructions.
+.Pp
+.El
+.Em  Trampoline Generation
+.Pp
+For 68HC11 and 68HC12,
+.Xr ld
+can generate trampoline code to call a far function using a normal
+.Li jsr
+instruction. The linker will also change the relocation to some far function
+to use the trampoline address instead of the function address. This is typically
+the case when a pointer to a function is taken. The pointer will in fact point
+to the function trampoline.
+.Pp
+The
+.Li --pic-veneer
+switch makes the linker use PIC sequences for ARM/Thumb interworking veneers,
+even if the rest of the binary is not PIC. This avoids problems on uClinux
+targets where
+.Li --emit-relocs
+is used to generate relocatable binaries.
+.Pp
+.Ss  Xr ld and the ARM family
+For the ARM,
+.Xr ld
+will generate code stubs to allow functions calls between ARM and Thumb code.
+These stubs only work with code that has been compiled and assembled with
+the
+.Li -mthumb-interwork
+command line option. If it is necessary to link with old ARM object files
+or libraries, which have not been compiled with the -mthumb-interwork option
+then the
+.Li --support-old-code
+command line switch should be given to the linker. This will make it generate
+larger stub functions which will work with non-interworking aware ARM code.
+Note, however, the linker does not support generating stubs for function calls
+to non-interworking aware Thumb code.
+.Pp
+The
+.Li --thumb-entry
+switch is a duplicate of the generic
+.Li --entry
+switch, in that it sets the program's starting address. But it also sets the
+bottom bit of the address, so that it can be branched to using a BX instruction,
+and the program will start executing in Thumb mode straight away.
+.Pp
+The
+.Li --be8
+switch instructs
+.Xr ld
+to generate BE8 format executables. This option is only valid when linking
+big-endian objects. The resulting image will contain big-endian data and little-endian
+code.
+.Pp
+The
+.Li R_ARM_TARGET1
+relocation is typically used for entries in the
+.Li .init_array
+section. It is interpreted as either
+.Li R_ARM_REL32
+or
+.Li R_ARM_ABS32 ,
+depending on the target. The
+.Li --target1-rel
+and
+.Li --target1-abs
+switches override the default.
+.Pp
+The
+.Li --target2=type
+switch overrides the default definition of the
+.Li R_ARM_TARGET2
+relocation. Valid values for
+.Li type ,
+their meanings, and target defaults are as follows:
+.Bl -tag -width Ds
+.It  rel
+.Li R_ARM_REL32
+(arm*-*-elf, arm*-*-eabi)
+.It  abs
+.Li R_ARM_ABS32
+(arm*-*-symbianelf)
+.It  got-rel
+.Li R_ARM_GOT_PREL
+(arm*-*-linux, arm*-*-*bsd)
+.El
+.Pp
+The
+.Li R_ARM_V4BX
+relocation (defined by the ARM AAELF specification) enables objects compiled
+for the ARMv4 architecture to be interworking-safe when linked with other
+objects compiled for ARMv4t, but also allows pure ARMv4 binaries to be built
+from the same ARMv4 objects.
+.Pp
+In the latter case, the switch
+.Op --fix-v4bx
+must be passed to the linker, which causes v4t
+.Li BX rM
+instructions to be rewritten as
+.Li MOV PC,rM ,
+since v4 processors do not have a
+.Li BX
+instruction.
+.Pp
+In the former case, the switch should not be used, and
+.Li R_ARM_V4BX
+relocations are ignored.
+.Pp
+The
+.Li --use-blx
+switch enables the linker to use ARM/Thumb BLX instructions (available on
+ARMv5t and above) in various situations. Currently it is used to perform calls
+via the PLT from Thumb code using BLX rather than using BX and a mode-switching
+stub before each PLT entry. This should lead to such calls executing slightly
+faster.
+.Pp
+This option is enabled implicitly for SymbianOS, so there is no need to specify
+it if you are using that target.
+.Pp
+The
+.Li --vfp11-denorm-fix
+switch enables a link-time workaround for a bug in certain VFP11 coprocessor
+hardware, which sometimes allows instructions with denorm operands (which
+must be handled by support code) to have those operands overwritten by subsequent
+instructions before the support code can read the intended values.
+.Pp
+The bug may be avoided in scalar mode if you allow at least one intervening
+instruction between a VFP11 instruction which uses a register and another
+instruction which writes to the same register, or at least two intervening
+instructions if vector mode is in use. The bug only affects full-compliance
+floating-point mode: you do not need this workaround if you are using "runfast"
+mode. Please contact ARM for further details.
+.Pp
+If you know you are using buggy VFP11 hardware, you can enable this workaround
+by specifying the linker option
+.Li --vfp-denorm-fix=scalar
+if you are using the VFP11 scalar mode only, or
+.Li --vfp-denorm-fix=vector
+if you are using vector mode (the latter also works for scalar code). The
+default is
+.Li --vfp-denorm-fix=none .
+.Pp
+If the workaround is enabled, instructions are scanned for potentially-troublesome
+sequences, and a veneer is created for each such sequence which may trigger
+the erratum. The veneer consists of the first instruction of the sequence
+and a branch back to the subsequent instruction. The original instruction
+is then replaced with a branch to the veneer. The extra cycles required to
+call and return from the veneer are sufficient to avoid the erratum in both
+the scalar and vector cases.
+.Pp
+The
+.Li --no-enum-size-warning
+switch prevents the linker from warning when linking object files that specify
+incompatible EABI enumeration size attributes. For example, with this switch
+enabled, linking of an object file using 32-bit enumeration values with another
+using enumeration values fitted into the smallest possible space will not
+be diagnosed.
+.Pp
+.Ss  Xr ld and HPPA 32-bit ELF Support
+When generating a shared library,
+.Xr ld
+will by default generate import stubs suitable for use with a single sub-space
+application. The
+.Li --multi-subspace
+switch causes
+.Xr ld
+to generate export stubs, and different (larger) import stubs suitable for
+use with multiple sub-spaces.
+.Pp
+Long branch stubs and import/export stubs are placed by
+.Xr ld
+in stub sections located between groups of input sections.
+.Li --stub-group-size
+specifies the maximum size of a group of input sections handled by one stub
+section. Since branch offsets are signed, a stub section may serve two groups
+of input sections, one group before the stub section, and one group after
+it. However, when using conditional branches that require stubs, it may be
+better (for branch prediction) that stub sections only serve one group of
+input sections. A negative value for
+.Li N
+chooses this scheme, ensuring that branches to stubs always use a negative
+offset. Two special values of
+.Li N
+are recognized,
+.Li 1
+and
+.Li -1 .
+These both instruct
+.Xr ld
+to automatically size input section groups for the branch types detected,
+with the same behaviour regarding stub placement as other positive or negative
+values of
+.Li N
+respectively.
+.Pp
+Note that
+.Li --stub-group-size
+does not split input sections. A single input section larger than the group
+size specified will of course create a larger group (of one section). If input
+sections are too large, it may not be possible for a branch to reach its stub.
+.Pp
+.Ss  Li ld and MMIX
+For MMIX, there is a choice of generating
+.Li ELF
+object files or
+.Li mmo
+object files when linking. The simulator
+.Li mmix
+understands the
+.Li mmo
+format. The binutils
+.Li objcopy
+utility can translate between the two formats.
+.Pp
+There is one special section, the
+.Li .MMIX.reg_contents
+section. Contents in this section is assumed to correspond to that of global
+registers, and symbols referring to it are translated to special symbols,
+equal to registers. In a final link, the start address of the
+.Li .MMIX.reg_contents
+section corresponds to the first allocated global register multiplied by 8.
+Register
+.Li $255
+is not included in this section; it is always set to the program entry, which
+is at the symbol
+.Li Main
+for
+.Li mmo
+files.
+.Pp
+Symbols with the prefix
+.Li __.MMIX.start. ,
+for example
+.Li __.MMIX.start..text
+and
+.Li __.MMIX.start..data
+are special; there must be only one each, even if they are local. The default
+linker script uses these to set the default start address of a section.
+.Pp
+Initial and trailing multiples of zero-valued 32-bit words in a section, are
+left out from an mmo file.
+.Pp
+.Ss  Li ld and MSP430
+For the MSP430 it is possible to select the MPU architecture. The flag
+.Li -m [mpu type]
+will select an appropriate linker script for selected MPU type. (To get a
+list of known MPUs just pass
+.Li -m help
+option to the linker).
+.Pp
+The linker will recognize some extra sections which are MSP430 specific:
+.Pp
+.Bl -tag -width Ds
+.It  Li .vectors
+Defines a portion of ROM where interrupt vectors located.
+.Pp
+.It  Li .bootloader
+Defines the bootloader portion of the ROM (if applicable). Any code in this
+section will be uploaded to the MPU.
+.Pp
+.It  Li .infomem
+Defines an information memory section (if applicable). Any code in this section
+will be uploaded to the MPU.
+.Pp
+.It  Li .infomemnobits 
+This is the same as the
+.Li .infomem
+section except that any code in this section will not be uploaded to the MPU.
+.Pp
+.It  Li .noinit
+Denotes a portion of RAM located above
+.Li .bss
+section.
+.Pp
+The last two sections are used by gcc.
+.El
+.Pp
+.Ss  Xr ld and PowerPC 32-bit ELF Support
+Branches on PowerPC processors are limited to a signed 26-bit displacement,
+which may result in
+.Xr ld
+giving
+.Li relocation truncated to fit
+errors with very large programs.
+.Li --relax
+enables the generation of trampolines that can access the entire 32-bit address
+space. These trampolines are inserted at section boundaries, so may not themselves
+be reachable if an input section exceeds 33M in size.
+.Pp
+.Bl -tag -width Ds
+.It  --bss-plt
+Current PowerPC GCC accepts a
+.Li -msecure-plt
+option that generates code capable of using a newer PLT and GOT layout that
+has the security advantage of no executable section ever needing to be writable
+and no writable section ever being executable. PowerPC
+.Xr ld
+will generate this layout, including stubs to access the PLT, if all input
+files (including startup and static libraries) were compiled with
+.Li -msecure-plt .
+.Li --bss-plt
+forces the old BSS PLT (and GOT layout) which can give slightly better performance.
+.Pp
+.It  --secure-plt
+.Xr ld
+will use the new PLT and GOT layout if it is linking new
+.Li -fpic
+or
+.Li -fPIC
+code, but does not do so automatically when linking non-PIC code. This option
+requests the new PLT and GOT layout. A warning will be given if some object
+file requires the old style BSS PLT.
+.Pp
+.It  --sdata-got
+The new secure PLT and GOT are placed differently relative to other sections
+compared to older BSS PLT and GOT placement. The location of
+.Li .plt
+must change because the new secure PLT is an initialized section while the
+old PLT is uninitialized. The reason for the
+.Li .got
+change is more subtle: The new placement allows
+.Li .got
+to be read-only in applications linked with
+.Li -z relro -z now .
+However, this placement means that
+.Li .sdata
+cannot always be used in shared libraries, because the PowerPC ABI accesses
+.Li .sdata
+in shared libraries from the GOT pointer.
+.Li --sdata-got
+forces the old GOT placement. PowerPC GCC doesn't use
+.Li .sdata
+in shared libraries, so this option is really only useful for other compilers
+that may do so.
+.Pp
+.It  --emit-stub-syms
+This option causes
+.Xr ld
+to label linker stubs with a local symbol that encodes the stub type and destination.
+.Pp
+.It  --no-tls-optimize
+PowerPC
+.Xr ld
+normally performs some optimization of code sequences used to access Thread-Local
+Storage. Use this option to disable the optimization.
+.El
+.Pp
+.Ss  Xr ld and PowerPC64 64-bit ELF Support
+.Bl -tag -width Ds
+.It  --stub-group-size
+Long branch stubs, PLT call stubs and TOC adjusting stubs are placed by
+.Xr ld
+in stub sections located between groups of input sections.
+.Li --stub-group-size
+specifies the maximum size of a group of input sections handled by one stub
+section. Since branch offsets are signed, a stub section may serve two groups
+of input sections, one group before the stub section, and one group after
+it. However, when using conditional branches that require stubs, it may be
+better (for branch prediction) that stub sections only serve one group of
+input sections. A negative value for
+.Li N
+chooses this scheme, ensuring that branches to stubs always use a negative
+offset. Two special values of
+.Li N
+are recognized,
+.Li 1
+and
+.Li -1 .
+These both instruct
+.Xr ld
+to automatically size input section groups for the branch types detected,
+with the same behaviour regarding stub placement as other positive or negative
+values of
+.Li N
+respectively.
+.Pp
+Note that
+.Li --stub-group-size
+does not split input sections. A single input section larger than the group
+size specified will of course create a larger group (of one section). If input
+sections are too large, it may not be possible for a branch to reach its stub.
+.Pp
+.It  --emit-stub-syms
+This option causes
+.Xr ld
+to label linker stubs with a local symbol that encodes the stub type and destination.
+.Pp
+.It  --dotsyms, --no-dotsyms
+These two options control how
+.Xr ld
+interprets version patterns in a version script. Older PowerPC64 compilers
+emitted both a function descriptor symbol with the same name as the function,
+and a code entry symbol with the name prefixed by a dot (
+.Li . ) .
+To properly version a function
+.Li foo ,
+the version script thus needs to control both
+.Li foo
+and
+.Li .foo .
+The option
+.Li --dotsyms ,
+on by default, automatically adds the required dot-prefixed patterns. Use
+.Li --no-dotsyms
+to disable this feature.
+.Pp
+.It  --no-tls-optimize
+PowerPC64
+.Xr ld
+normally performs some optimization of code sequences used to access Thread-Local
+Storage. Use this option to disable the optimization.
+.Pp
+.It  --no-opd-optimize
+PowerPC64
+.Xr ld
+normally removes
+.Li .opd
+section entries corresponding to deleted link-once functions, or functions
+removed by the action of
+.Li --gc-sections
+or linker scrip
+.Li /DISCARD/ .
+Use this option to disable
+.Li .opd
+optimization.
+.Pp
+.It  --non-overlapping-opd
+Some PowerPC64 compilers have an option to generate compressed
+.Li .opd
+entries spaced 16 bytes apart, overlapping the third word, the static chain
+pointer (unused in C) with the first word of the next entry. This option expands
+such entries to the full 24 bytes.
+.Pp
+.It  --no-toc-optimize
+PowerPC64
+.Xr ld
+normally removes unused
+.Li .toc
+section entries. Such entries are detected by examining relocations that reference
+the TOC in code sections. A reloc in a deleted code section marks a TOC word
+as unneeded, while a reloc in a kept code section marks a TOC word as needed.
+Since the TOC may reference itself, TOC relocs are also examined. TOC words
+marked as both needed and unneeded will of course be kept. TOC words without
+any referencing reloc are assumed to be part of a multi-word entry, and are
+kept or discarded as per the nearest marked preceding word. This works reliably
+for compiler generated code, but may be incorrect if assembly code is used
+to insert TOC entries. Use this option to disable the optimization.
+.Pp
+.It  --no-multi-toc
+By default, PowerPC64 GCC generates code for a TOC model where TOC entries
+are accessed with a 16-bit offset from r2. This limits the total TOC size
+to 64K. PowerPC64
+.Xr ld
+extends this limit by grouping code sections such that each group uses less
+than 64K for its TOC entries, then inserts r2 adjusting stubs between inter-group
+calls.
+.Xr ld
+does not split apart input sections, so cannot help if a single input file
+has a
+.Li .toc
+section that exceeds 64K, most likely from linking multiple files with
+.Xr ld -r .
+Use this option to turn off this feature.
+.El
+.Pp
+.Ss  Xr ld and SPU ELF Support
+.Bl -tag -width Ds
+.It  --plugin
+This option marks an executable as a PIC plugin module.
+.Pp
+.It  --no-overlays
+Normally,
+.Xr ld
+recognizes calls to functions within overlay regions, and redirects such calls
+to an overlay manager via a stub.
+.Xr ld
+also provides a built-in overlay manager. This option turns off all this special
+overlay handling.
+.Pp
+.It  --emit-stub-syms
+This option causes
+.Xr ld
+to label overlay stubs with a local symbol that encodes the stub type and
+destination.
+.Pp
+.It  --extra-overlay-stubs
+This option causes
+.Xr ld
+to add overlay call stubs on all function calls out of overlay regions. Normally
+stubs are not added on calls to non-overlay regions.
+.Pp
+.It  --local-store=lo:hi
+.Xr ld
+usually checks that a final executable for SPU fits in the address range 0
+to 256k. This option may be used to change the range. Disable the check entirely
+with
+.Op --local-store=0:0 .
+.Pp
+.It  --stack-analysis
+SPU local store space is limited. Over-allocation of stack space unnecessarily
+limits space available for code and data, while under-allocation results in
+runtime failures. If given this option,
+.Xr ld
+will provide an estimate of maximum stack usage.
+.Xr ld
+does this by examining symbols in code sections to determine the extents of
+functions, and looking at function prologues for stack adjusting instructions.
+A call-graph is created by looking for relocations on branch instructions.
+The graph is then searched for the maximum stack usage path. Note that this
+analysis does not find calls made via function pointers, and does not handle
+recursion and other cycles in the call graph. Stack usage may be under-estimated
+if your code makes such calls. Also, stack usage for dynamic allocation, e.g.
+alloca, will not be detected. If a link map is requested, detailed information
+about each function's stack usage and calls will be given.
+.Pp
+.It  --emit-stack-syms
+This option, if given along with
+.Op --stack-analysis
+will result in
+.Xr ld
+emitting stack sizing symbols for each function. These take the form
+.Li __stack_<function_name>
+for global functions, and
+.Li __stack_<number>_<function_name>
+for static functions.
+.Li <number>
+is the section id in hex. The value of such symbols is the stack requirement
+for the corresponding function. The symbol size will be zero, type
+.Li STT_NOTYPE ,
+binding
+.Li STB_LOCAL ,
+and section
+.Li SHN_ABS .
+.El
+.Pp
+.Ss  Xr ld's Support for Various TI COFF Versions
+The
+.Li --format
+switch allows selection of one of the various TI COFF versions. The latest
+of this writing is 2; versions 0 and 1 are also supported. The TI COFF versions
+also vary in header byte-order format;
+.Xr ld
+will read any version or byte order, but the output header format depends
+on the default specified by the specific target.
+.Pp
+.Ss  Xr ld and WIN32 (cygwin/mingw)
+This section describes some of the win32 specific
+.Xr ld
+issues. See Options,,Command Line Options for detailed description of the
+command line options mentioned here.
+.Pp
+.Bl -tag -width Ds
+.It  import libraries 
+The standard Windows linker creates and uses so-called import libraries, which
+contains information for linking to dll's. They are regular static archives
+and are handled as any other static archive. The cygwin and mingw ports of
+.Xr ld
+have specific support for creating such libraries provided with the
+.Li --out-implib
+command line option.
+.Pp
+.It  exporting DLL symbols 
+The cygwin/mingw
+.Xr ld
+has several ways to export symbols for dll's.
+.Pp
+.Bl -tag -width Ds
+.It  using auto-export functionality
+By default
+.Xr ld
+exports symbols with the auto-export functionality, which is controlled by
+the following command line options:
+.Pp
+.Bl -bullet
+.It
+--export-all-symbols [This is the default]
+.It
+--exclude-symbols
+.It
+--exclude-libs
+.El
+.Pp
+If, however,
+.Li --export-all-symbols
+is not given explicitly on the command line, then the default auto-export
+behavior will be
+.Em disabled
+if either of the following are true:
+.Pp
+.Bl -bullet
+.It
+A DEF file is used.
+.It
+Any symbol in any object file was marked with the __declspec(dllexport) attribute.
+.El
+.Pp
+.It  using a DEF file 
+Another way of exporting symbols is using a DEF file. A DEF file is an ASCII
+file containing definitions of symbols which should be exported when a dll
+is created. Usually it is named
+.Li <dll name>.def
+and is added as any other object file to the linker's command line. The file's
+name must end in
+.Li .def
+or
+.Li .DEF .
+.Pp
+.Bd -literal -offset indent
+gcc -o <output> <objectfiles> <dll name>.def
+.Ed
+.Pp
+Using a DEF file turns off the normal auto-export behavior, unless the
+.Li --export-all-symbols
+option is also used.
+.Pp
+Here is an example of a DEF file for a shared library called
+.Li xyz.dll :
+.Pp
+.Bd -literal -offset indent
+LIBRARY "xyz.dll" BASE=0x20000000
+
+EXPORTS
+foo
+bar
+_bar = bar
+another_foo = abc.dll.afoo
+var1 DATA
+.Ed
+.Pp
+This example defines a DLL with a non-default base address and five symbols
+in the export table. The third exported symbol
+.Li _bar
+is an alias for the second. The fourth symbol,
+.Li another_foo
+is resolved by "forwarding" to another module and treating it as an alias
+for
+.Li afoo
+exported from the DLL
+.Li abc.dll .
+The final symbol
+.Li var1
+is declared to be a data object.
+.Pp
+The optional
+.Li LIBRARY <name>
+command indicates the
+.Em internal
+name of the output DLL. If
+.Li <name>
+does not include a suffix, the default library suffix,
+.Li .DLL
+is appended.
+.Pp
+When the .DEF file is used to build an application, rather than a library,
+the
+.Li NAME <name>
+command should be used instead of
+.Li LIBRARY .
+If
+.Li <name>
+does not include a suffix, the default executable suffix,
+.Li .EXE
+is appended.
+.Pp
+With either
+.Li LIBRARY <name>
+or
+.Li NAME <name>
+the optional specification
+.Li BASE = <number>
+may be used to specify a non-default base address for the image.
+.Pp
+If neither
+.Li LIBRARY <name>
+nor
+.Li NAME <name>
+is specified, or they specify an empty string, the internal name is the same
+as the filename specified on the command line.
+.Pp
+The complete specification of an export symbol is:
+.Pp
+.Bd -literal -offset indent
+EXPORTS
+  ( (  ( <name1> [ = <name2> ] )
+     | ( <name1> = <module-name> . <external-name>))
+  [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) *
+.Ed
+.Pp
+Declares
+.Li <name1>
+as an exported symbol from the DLL, or declares
+.Li <name1>
+as an exported alias for
+.Li <name2> ;
+or declares
+.Li <name1>
+as a "forward" alias for the symbol
+.Li <external-name>
+in the DLL
+.Li <module-name> .
+Optionally, the symbol may be exported by the specified ordinal
+.Li <integer>
+alias.
+.Pp
+The optional keywords that follow the declaration indicate:
+.Pp
+.Li NONAME :
+Do not put the symbol name in the DLL's export table. It will still be exported
+by its ordinal alias (either the value specified by the .def specification
+or, otherwise, the value assigned by the linker). The symbol name, however,
+does remain visible in the import library (if any), unless
+.Li PRIVATE
+is also specified.
+.Pp
+.Li DATA :
+The symbol is a variable or object, rather than a function. The import lib
+will export only an indirect reference to
+.Li foo
+as the symbol
+.Li _imp__foo
+(ie,
+.Li foo
+must be resolved as
+.Li *_imp__foo ) .
+.Pp
+.Li CONSTANT :
+Like
+.Li DATA ,
+but put the undecorated
+.Li foo
+as well as
+.Li _imp__foo
+into the import library. Both refer to the read-only import address table's
+pointer to the variable, not to the variable itself. This can be dangerous.
+If the user code fails to add the
+.Li dllimport
+attribute and also fails to explicitly add the extra indirection that the
+use of the attribute enforces, the application will behave unexpectedly.
+.Pp
+.Li PRIVATE :
+Put the symbol in the DLL's export table, but do not put it into the static
+import library used to resolve imports at link time. The symbol can still
+be imported using the
+.Li LoadLibrary/GetProcAddress
+API at runtime or by by using the GNU ld extension of linking directly to
+the DLL without an import library. See ld/deffilep.y in the binutils sources
+for the full specification of other DEF file statements
+.Pp
+While linking a shared dll,
+.Xr ld
+is able to create a DEF file with the
+.Li --output-def <file>
+command line option.
+.Pp
+.It  Using decorations
+Another way of marking symbols for export is to modify the source code itself,
+so that when building the DLL each symbol to be exported is declared as:
+.Pp
+.Bd -literal -offset indent
+__declspec(dllexport) int a_variable
+__declspec(dllexport) void a_function(int with_args)
+.Ed
+.Pp
+All such symbols will be exported from the DLL. If, however, any of the object
+files in the DLL contain symbols decorated in this way, then the normal auto-export
+behavior is disabled, unless the
+.Li --export-all-symbols
+option is also used.
+.Pp
+Note that object files that wish to access these symbols must
+.Em not
+decorate them with dllexport. Instead, they should use dllimport, instead:
+.Pp
+.Bd -literal -offset indent
+__declspec(dllimport) int a_variable
+__declspec(dllimport) void a_function(int with_args)
+.Ed
+.Pp
+This complicates the structure of library header files, because when included
+by the library itself the header must declare the variables and functions
+as dllexport, but when included by client code the header must declare them
+as dllimport. There are a number of idioms that are typically used to do this;
+often client code can omit the __declspec() declaration completely. See
+.Li --enable-auto-import
+and
+.Li automatic data imports
+for more information.
+.El
+.Pp
+.It  automatic data imports
+The standard Windows dll format supports data imports from dlls only by adding
+special decorations (dllimport/dllexport), which let the compiler produce
+specific assembler instructions to deal with this issue. This increases the
+effort necessary to port existing Un*x code to these platforms, especially
+for large c++ libraries and applications. The auto-import feature, which was
+initially provided by Paul Sokolovsky, allows one to omit the decorations
+to achieve a behavior that conforms to that on POSIX/Un*x platforms. This
+feature is enabled with the
+.Li --enable-auto-import
+command-line option, although it is enabled by default on cygwin/mingw. The
+.Li --enable-auto-import
+option itself now serves mainly to suppress any warnings that are ordinarily
+emitted when linked objects trigger the feature's use.
+.Pp
+auto-import of variables does not always work flawlessly without additional
+assistance. Sometimes, you will see this message
+.Pp
+"variable '<var>' can't be auto-imported. Please read the documentation for
+ld's
+.Li --enable-auto-import
+for details."
+.Pp
+The
+.Li --enable-auto-import
+documentation explains why this error occurs, and several methods that can
+be used to overcome this difficulty. One of these methods is the
+.Em runtime pseudo-relocs
+feature, described below.
+.Pp
+For complex variables imported from DLLs (such as structs or classes), object
+files typically contain a base address for the variable and an offset (
+.Em addend )
+within the variable--to specify a particular field or public member, for instance.
+Unfortunately, the runtime loader used in win32 environments is incapable
+of fixing these references at runtime without the additional information supplied
+by dllimport/dllexport decorations. The standard auto-import feature described
+above is unable to resolve these references.
+.Pp
+The
+.Li --enable-runtime-pseudo-relocs
+switch allows these references to be resolved without error, while leaving
+the task of adjusting the references themselves (with their non-zero addends)
+to specialized code provided by the runtime environment. Recent versions of
+the cygwin and mingw environments and compilers provide this runtime support;
+older versions do not. However, the support is only necessary on the developer's
+platform; the compiled result will run without error on an older system.
+.Pp
+.Li --enable-runtime-pseudo-relocs
+is not the default; it must be explicitly enabled as needed.
+.Pp
+.It  direct linking to a dll
+The cygwin/mingw ports of
+.Xr ld
+support the direct linking, including data symbols, to a dll without the usage
+of any import libraries. This is much faster and uses much less memory than
+does the traditional import library method, especially when linking large
+libraries or applications. When
+.Xr ld
+creates an import lib, each function or variable exported from the dll is
+stored in its own bfd, even though a single bfd could contain many exports.
+The overhead involved in storing, loading, and processing so many bfd's is
+quite large, and explains the tremendous time, memory, and storage needed
+to link against particularly large or complex libraries when using import
+libs.
+.Pp
+Linking directly to a dll uses no extra command-line switches other than
+.Li -L
+and
+.Li -l ,
+because
+.Xr ld
+already searches for a number of names to match each library. All that is
+needed from the developer's perspective is an understanding of this search,
+in order to force ld to select the dll instead of an import library.
+.Pp
+For instance, when ld is called with the argument
+.Li -lxxx
+it will attempt to find, in the first directory of its search path,
+.Pp
+.Bd -literal -offset indent
+libxxx.dll.a
+xxx.dll.a
+libxxx.a
+xxx.lib
+cygxxx.dll (*)
+libxxx.dll
+xxx.dll
+.Ed
+.Pp
+before moving on to the next directory in the search path.
+.Pp
+(*) Actually, this is not
+.Li cygxxx.dll
+but in fact is
+.Li <prefix>xxx.dll ,
+where
+.Li <prefix>
+is set by the
+.Xr ld
+option
+.Li --dll-search-prefix=<prefix> .
+In the case of cygwin, the standard gcc spec file includes
+.Li --dll-search-prefix=cyg ,
+so in effect we actually search for
+.Li cygxxx.dll .
+.Pp
+Other win32-based unix environments, such as mingw or pw32, may use other
+.Li <prefix>
+es, although at present only cygwin makes use of this feature. It was originally
+intended to help avoid name conflicts among dll's built for the various win32/un*x
+environments, so that (for example) two versions of a zlib dll could coexist
+on the same machine.
+.Pp
+The generic cygwin/mingw path layout uses a
+.Li bin
+directory for applications and dll's and a
+.Li lib
+directory for the import libraries (using cygwin nomenclature):
+.Pp
+.Bd -literal -offset indent
+bin/
+	cygxxx.dll
+lib/
+	libxxx.dll.a   (in case of dll's)
+	libxxx.a       (in case of static archive) 
+.Ed
+.Pp
+Linking directly to a dll without using the import library can be done two
+ways:
+.Pp
+1. Use the dll directly by adding the
+.Li bin
+path to the link line
+.Bd -literal -offset indent
+gcc -Wl,-verbose  -o a.exe -L../bin/ -lxxx
+.Ed
+.Pp
+However, as the dll's often have version numbers appended to their names (
+.Li cygncurses-5.dll )
+this will often fail, unless one specifies
+.Li -L../bin -lncurses-5
+to include the version. Import libs are generally not versioned, and do not
+have this difficulty.
+.Pp
+2. Create a symbolic link from the dll to a file in the
+.Li lib
+directory according to the above mentioned search pattern. This should be
+used to avoid unwanted changes in the tools needed for making the app/dll.
+.Pp
+.Bd -literal -offset indent
+ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
+.Ed
+.Pp
+Then you can link without any make environment changes.
+.Pp
+.Bd -literal -offset indent
+gcc -Wl,-verbose  -o a.exe -L../lib/ -lxxx
+.Ed
+.Pp
+This technique also avoids the version number problems, because the following
+is perfectly legal
+.Pp
+.Bd -literal -offset indent
+bin/
+	cygxxx-5.dll
+lib/
+	libxxx.dll.a -> ../bin/cygxxx-5.dll 
+.Ed
+.Pp
+Linking directly to a dll without using an import lib will work even when
+auto-import features are exercised, and even when
+.Li --enable-runtime-pseudo-relocs
+is used.
+.Pp
+Given the improvements in speed and memory usage, one might justifiably wonder
+why import libraries are used at all. There are three reasons:
+.Pp
+1. Until recently, the link-directly-to-dll functionality did
+.Em not
+work with auto-imported data.
+.Pp
+2. Sometimes it is necessary to include pure static objects within the import
+library (which otherwise contains only bfd's for indirection symbols that
+point to the exports of a dll). Again, the import lib for the cygwin kernel
+makes use of this ability, and it is not possible to do this without an import
+lib.
+.Pp
+3. Symbol aliases can only be resolved using an import lib. This is critical
+when linking against OS-supplied dll's (eg, the win32 API) in which symbols
+are usually exported as undecorated aliases of their stdcall-decorated assembly
+names.
+.Pp
+So, import libs are not going away. But the ability to replace true import
+libs with a simple symbolic link to (or a copy of) a dll, in many cases, is
+a useful addition to the suite of tools binutils makes available to the win32
+developer. Given the massive improvements in memory requirements during linking,
+storage requirements, and linking speed, we expect that many developers will
+soon begin to use this feature whenever possible.
+.Pp
+.It  symbol aliasing 
+.Bl -tag -width Ds
+.It  adding additional names 
+Sometimes, it is useful to export symbols with additional names. A symbol
+.Li foo
+will be exported as
+.Li foo ,
+but it can also be exported as
+.Li _foo
+by using special directives in the DEF file when creating the dll. This will
+affect also the optional created import library. Consider the following DEF
+file:
+.Pp
+.Bd -literal -offset indent
+LIBRARY "xyz.dll" BASE=0x61000000
+
+EXPORTS
+foo 
+_foo = foo
+.Ed
+.Pp
+The line
+.Li _foo = foo
+maps the symbol
+.Li foo
+to
+.Li _foo .
+.Pp
+Another method for creating a symbol alias is to create it in the source code
+using the "weak" attribute:
+.Pp
+.Bd -literal -offset indent
+void foo () { /* Do something.  */; } 
+void _foo () __attribute__ ((weak, alias ("foo")));
+.Ed
+.Pp
+See the gcc manual for more information about attributes and weak symbols.
+.Pp
+.It  renaming symbols
+Sometimes it is useful to rename exports. For instance, the cygwin kernel
+does this regularly. A symbol
+.Li _foo
+can be exported as
+.Li foo
+but not as
+.Li _foo
+by using special directives in the DEF file. (This will also affect the import
+library, if it is created). In the following example:
+.Pp
+.Bd -literal -offset indent
+LIBRARY "xyz.dll" BASE=0x61000000
+
+EXPORTS
+_foo = foo
+.Ed
+.Pp
+The line
+.Li _foo = foo
+maps the exported symbol
+.Li foo
+to
+.Li _foo .
+.El
+.Pp
+Note: using a DEF file disables the default auto-export behavior, unless the
+.Li --export-all-symbols
+command line option is used. If, however, you are trying to rename symbols,
+then you should list
+.Em all
+desired exports in the DEF file, including the symbols that are not being
+renamed, and do
+.Em not
+use the
+.Li --export-all-symbols
+option. If you list only the renamed symbols in the DEF file, and use
+.Li --export-all-symbols
+to handle the other symbols, then the both the new names
+.Em and
+the original names for the renamed symbols will be exported. In effect, you'd
+be aliasing those symbols, not renaming them, which is probably not what you
+wanted.
+.Pp
+.It  weak externals
+The Windows object format, PE, specifies a form of weak symbols called weak
+externals. When a weak symbol is linked and the symbol is not defined, the
+weak symbol becomes an alias for some other symbol. There are three variants
+of weak externals:
+.Bl -bullet
+.It
+Definition is searched for in objects and libraries, historically
+called lazy externals.
+.It
+Definition is searched for only in other objects, not in libraries.
+This form is not presently implemented.
+.It
+No search; the symbol is an alias. This form is not presently
+implemented.
+.El
+As a GNU extension, weak symbols that do not specify an alternate symbol are
+supported. If the symbol is undefined when linking, the symbol uses a default
+value.
+.El
+.Pp
+.Ss  Li ld and Xtensa Processors
+The default
+.Xr ld
+behavior for Xtensa processors is to interpret
+.Li SECTIONS
+commands so that lists of explicitly named sections in a specification with
+a wildcard file will be interleaved when necessary to keep literal pools within
+the range of PC-relative load offsets. For example, with the command:
+.Pp
+.Bd -literal -offset indent
+SECTIONS
+{
+  .text : {
+    *(.literal .text)
+  }
+}
+.Ed
+.Pp
+.Xr ld
+may interleave some of the
+.Li .literal
+and
+.Li .text
+sections from different object files to ensure that the literal pools are
+within the range of PC-relative load offsets. A valid interleaving might place
+the
+.Li .literal
+sections from an initial group of files followed by the
+.Li .text
+sections of that group of files. Then, the
+.Li .literal
+sections from the rest of the files and the
+.Li .text
+sections from the rest of the files would follow.
+.Pp
+Relaxation is enabled by default for the Xtensa version of
+.Xr ld
+and provides two important link-time optimizations. The first optimization
+is to combine identical literal values to reduce code size. A redundant literal
+will be removed and all the
+.Li L32R
+instructions that use it will be changed to reference an identical literal,
+as long as the location of the replacement literal is within the offset range
+of all the
+.Li L32R
+instructions. The second optimization is to remove unnecessary overhead from
+assembler-generated \(lqlongcall\(rq sequences of
+.Li L32R
+/
+.Li CALLX Va n
+when the target functions are within range of direct
+.Li CALL Va n
+instructions.
+.Pp
+For each of these cases where an indirect call sequence can be optimized to
+a direct call, the linker will change the
+.Li CALLX Va n
+instruction to a
+.Li CALL Va n
+instruction, remove the
+.Li L32R
+instruction, and remove the literal referenced by the
+.Li L32R
+instruction if it is not used for anything else. Removing the
+.Li L32R
+instruction always reduces code size but can potentially hurt performance
+by changing the alignment of subsequent branch targets. By default, the linker
+will always preserve alignments, either by switching some instructions between
+24-bit encodings and the equivalent density instructions or by inserting a
+no-op in place of the
+.Li L32R
+instruction that was removed. If code size is more important than performance,
+the
+.Op --size-opt
+option can be used to prevent the linker from widening density instructions
+or inserting no-ops, except in a few cases where no-ops are required for correctness.
+.Pp
+The following Xtensa-specific command-line options can be used to control
+the linker:
+.Pp
+.Bl -tag -width Ds
+.It  --no-relax
+Since the Xtensa version of
+.Li ld
+enables the
+.Op --relax
+option by default, the
+.Op --no-relax
+option is provided to disable relaxation.
+.Pp
+.It  --size-opt
+When optimizing indirect calls to direct calls, optimize for code size more
+than performance. With this option, the linker will not insert no-ops or widen
+density instructions to preserve branch target alignment. There may still
+be some cases where no-ops are required to preserve the correctness of the
+code.
+.El
+.Pp
+.Sh  BFD
+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
+.Li objdump -i
+(see Section
+.Dq objdump )
+to list all the formats available for your configuration.
+.Pp
+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.
+.Pp
+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.See Section
+.Dq BFD information loss .
+.Pp
+.Ss  How It Works: An Outline of BFD
+When an object file is opened, BFD subroutines automatically determine the
+format of the input object file. They then build a descriptor in memory with
+pointers to routines that will be used to access elements of the object file's
+data structures.
+.Pp
+As different information from the object files is required, 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 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 a memory pointer to the routine from the
+relevant BFD back end which reads and converts the table into a canonical
+form. The linker then operates upon the canonical form. When the link is finished
+and the linker writes the output file's symbol table, another BFD back end
+routine is called to take the newly created symbol table and convert it into
+the chosen output format.
+.Pp
+.Em  Information Loss
+.Pp
+.Em Information can be lost during output.
+The output formats supported by BFD do not provide identical facilities, and
+information which can be described in one form has nowhere to go in another
+format. One example of this is alignment information in
+.Li b.out .
+There is nowhere in an
+.Li a.out
+format file to store alignment information on the contained data, so when
+a file is linked from
+.Li b.out
+and an
+.Li 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).
+.Pp
+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 (e.g.,
+.Li a.out )
+or has sections without names (e.g., 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 linker command language.
+.Pp
+.Em Information can be lost during canonicalization.
+The 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 BFD back ends cannot maintain all possible
+data richness through the transformation between external to internal and
+back to external formats.
+.Pp
+This limitation is only a problem when an application reads one format and
+writes another. Each BFD back end is responsible for maintaining as much data
+as possible, and the internal BFD canonical form has structures which are
+opaque to the BFD core, and exported only to the back ends. When a file is
+read in one format, the canonical form is generated for BFD and the application.
+At the same time, the back end saves away any information which may otherwise
+be lost. If the data is then written back in the same format, the back end
+routine will be able to use the canonical form provided by the BFD core as
+well as the information it prepared earlier. Since there is a great deal of
+commonality between back ends, there is no information lost when linking or
+copying big endian COFF to little endian COFF, or
+.Li a.out
+to
+.Li b.out .
+When a mixture of formats is linked, the information is only lost from the
+files whose format differs from the destination.
+.Pp
+.Em  The BFD canonical object-file format
+.Pp
+The greatest potential for loss of information occurs when there is the least
+overlap between the information provided by the source format, that stored
+by the canonical format, and that needed by the destination format. A brief
+description of the canonical form may help you understand which kinds of data
+you can count on preserving across conversions.
+.Pp
+.Bl -tag -width Ds
+.It  files
+Information stored on a per-file basis includes target machine architecture,
+particular implementation format type, a demand pageable bit, and a write
+protected bit. Information like Unix magic numbers is not stored here---only
+the magic numbers' meaning, so a
+.Li 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
+big- and little-endian object files may be used with one another.
+.Pp
+.It  sections
+Each section in the input file contains the name of the section, the section's
+original address in the object file, size and alignment information, various
+flags, and pointers into other BFD data structures.
+.Pp
+.It  symbols
+Each symbol contains a pointer to the information for the object file which
+originally defined it, its name, its value, and various flag bits. When a
+BFD back end reads in a symbol table, it relocates all symbols to make them
+relative to the base of the section where they were defined. Doing this ensures
+that each symbol points to its containing section. Each symbol also has a
+varying amount of hidden private data for the BFD back end. Since the symbol
+points to the original file, the private data format for that symbol is accessible.
+.Li ld
+can operate on a collection of symbols of wildly different formats without
+problems.
+.Pp
+Normal global and simple local symbols are maintained on output, so an 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
+.Li a.out ,
+type information is stored in the symbol table as long symbol names. This
+information would be useless to most COFF debuggers; the linker has command
+line switches to allow users to throw it away.
+.Pp
+There is one word of type information within the symbol, so if the format
+supports symbol type information within symbols (for example, COFF, IEEE,
+Oasys) and the type is simple enough to fit within one word (nearly everything
+but aggregates), the information will be preserved.
+.Pp
+.It  relocation level
+Each canonical BFD 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 performed by passing
+messages through the relocation type descriptor and the symbol pointer. Therefore,
+relocations can be performed on output data using a relocation method that
+is only available in one of the input formats. For instance, Oasys provides
+a byte relocation format. A relocation record requesting this relocation type
+would point indirectly to a routine to perform this, so the relocation may
+be performed on a byte being written to a 68k COFF file, even though 68k COFF
+has no such relocation type.
+.Pp
+.It  line numbers
+Object formats can contain, for debugging purposes, some form of mapping between
+symbols, source line numbers, and addresses in the output file. These addresses
+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 finding out 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).
+.El
+.Pp
+.Sh  Reporting Bugs
+Your bug reports play an essential role in making
+.Xr ld
+reliable.
+.Pp
+Reporting a bug may help you by bringing a solution to your problem, or it
+may not. But in any case the principal function of a bug report is to help
+the entire community by making the next version of
+.Xr ld
+work better. Bug reports are your contribution to the maintenance of
+.Xr ld .
+.Pp
+In order for a bug report to serve its purpose, you must include the information
+that enables us to fix the bug.
+.Pp
+.Ss  Have You Found a Bug?
+If you are not sure whether you have found a bug, here are some guidelines:
+.Pp
+.Bl -bullet
+.It
+If the linker gets a fatal signal, for any input whatever, that is a
+.Xr ld
+bug. Reliable linkers never crash.
+.Pp
+.It
+If
+.Xr ld
+produces an error message for valid input, that is a bug.
+.Pp
+.It
+If
+.Xr ld
+does not produce an error message for invalid input, that may be a bug. In
+the general case, the linker can not verify that object files are correct.
+.Pp
+.It
+If you are an experienced user of linkers, your suggestions for improvement
+of
+.Xr ld
+are welcome in any case.
+.El
+.Pp
+.Ss  How to Report Bugs
+A number of companies and individuals offer support for GNU products. If you
+obtained
+.Xr ld
+from a support organization, we recommend you contact that organization first.
+.Pp
+You can find contact information for many support companies and individuals
+in the file
+.Pa etc/SERVICE
+in the GNU Emacs distribution.
+.Pp
+The fundamental principle of reporting bugs usefully is this:
+.Sy report all the facts .
+If you are not sure whether to state a fact or leave it out, state it!
+.Pp
+Often people omit facts because they think they know what causes the problem
+and assume that some details do not matter. Thus, you might assume that the
+name of a symbol you use in an example does not matter. Well, probably it
+does not, but one cannot be sure. Perhaps the bug is a stray memory reference
+which happens to fetch from the location where that name is stored in memory;
+perhaps, if the name were different, the contents of that location would fool
+the linker into doing the right thing despite the bug. Play it safe and give
+a specific, complete example. That is the easiest thing for you to do, and
+the most helpful.
+.Pp
+Keep in mind that the purpose of a bug report is to enable us to fix the bug
+if it is new to us. Therefore, always write your bug reports on the assumption
+that the bug has not been reported previously.
+.Pp
+Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq
+This cannot help us fix a bug, so it is basically useless. We respond by asking
+for enough details to enable us to investigate. You might as well expedite
+matters by sending them to begin with.
+.Pp
+To enable us to fix the bug, you should include all these things:
+.Pp
+.Bl -bullet
+.It
+The version of
+.Xr ld .
+.Xr ld
+announces it if you start it with the
+.Li --version
+argument.
+.Pp
+Without this, we will not know whether there is any point in looking for the
+bug in the current version of
+.Xr ld .
+.Pp
+.It
+Any patches you may have applied to the
+.Xr ld
+source, including any patches made to the
+.Li BFD
+library.
+.Pp
+.It
+The type of machine you are using, and the operating system name and version
+number.
+.Pp
+.It
+What compiler (and its version) was used to compile
+.Xr ld
+---e.g. \(lq
+.Li gcc-2.7
+\(rq\&.
+.Pp
+.It
+The command arguments you gave the linker to link your example and observe
+the bug. To guarantee you will not omit something important, list them all.
+A copy of the Makefile (or the output from make) is sufficient.
+.Pp
+If we were to try to guess the arguments, we would probably guess wrong and
+then we might not encounter the bug.
+.Pp
+.It
+A complete input file, or set of input files, that will reproduce the bug.
+It is generally most helpful to send the actual object files provided that
+they are reasonably small. Say no more than 10K. For bigger files you can
+either make them available by FTP or HTTP or else state that you are willing
+to send the object file(s) to whomever requests them. (Note - your email will
+be going to a mailing list, so we do not want to clog it up with large attachments).
+But small attachments are best.
+.Pp
+If the source files were assembled using
+.Li gas
+or compiled using
+.Li gcc ,
+then it may be OK to send the source files rather than the object files. In
+this case, be sure to say exactly what version of
+.Li gas
+or
+.Li gcc
+was used to produce the object files. Also say how
+.Li gas
+or
+.Li gcc
+were configured.
+.Pp
+.It
+A description of what behavior you observe that you believe is incorrect.
+For example, \(lqIt gets a fatal signal.\(rq
+.Pp
+Of course, if the bug is that
+.Xr ld
+gets a fatal signal, then we will certainly notice it. But if the bug is incorrect
+output, we might not notice unless it is glaringly wrong. You might as well
+not give us a chance to make a mistake.
+.Pp
+Even if the problem you experience is a fatal signal, you should still say
+so explicitly. Suppose something strange is going on, such as, your copy of
+.Xr ld
+is out of sync, or you have encountered a bug in the C library on your system.
+(This has happened!) Your copy might crash and ours would not. If you told
+us to expect a crash, then when ours fails to crash, we would know that the
+bug was not happening for us. If you had not told us to expect a crash, then
+we would not be able to draw any conclusion from our observations.
+.Pp
+.It
+If you wish to suggest changes to the
+.Xr ld
+source, send us context diffs, as generated by
+.Li diff
+with the
+.Li -u ,
+.Li -c ,
+or
+.Li -p
+option. Always send diffs from the old file to the new file. If you even discuss
+something in the
+.Xr ld
+source, refer to it by context, not by line number.
+.Pp
+The line numbers in our development sources will not match those in your sources.
+Your line numbers would convey no useful information to us.
+.El
+.Pp
+Here are some things that are not necessary:
+.Pp
+.Bl -bullet
+.It
+A description of the envelope of the bug.
+.Pp
+Often people who encounter a bug spend a lot of time investigating which changes
+to the input file will make the bug go away and which changes will not affect
+it.
+.Pp
+This is often time consuming and not very useful, because the way we will
+find the bug is by running a single example under the debugger with breakpoints,
+not by pure deduction from a series of examples. We recommend that you save
+your time for something else.
+.Pp
+Of course, if you can find a simpler example to report
+.Em instead
+of the original one, that is a convenience for us. Errors in the output will
+be easier to spot, running under the debugger will take less time, and so
+on.
+.Pp
+However, simplification is not vital; if you do not want to do this, report
+the bug anyway and send us the entire test case you used.
+.Pp
+.It
+A patch for the bug.
+.Pp
+A patch for the bug does help us if it is a good one. But do not omit the
+necessary information, such as the test case, on the assumption that a patch
+is all we need. We might see problems with your patch and decide to fix the
+problem another way, or we might not understand it at all.
+.Pp
+Sometimes with a program as complicated as
+.Xr ld
+it is very hard to construct an example that will make the program follow
+a certain path through the code. If you do not send us the example, we will
+not be able to construct one, so we will not be able to verify that the bug
+is fixed.
+.Pp
+And if we cannot understand what bug you are trying to fix, or why your patch
+should be an improvement, we will not install it. A test case will help us
+to understand.
+.Pp
+.It
+A guess about what the bug is or what it depends on.
+.Pp
+Such guesses are usually wrong. Even we cannot guess right about such things
+without first using the debugger to find the facts.
+.El
+.Pp
+.Sh  MRI Compatible Script Files
+To aid users making the transition to GNU
+.Xr ld
+from the MRI linker,
+.Xr ld
+can use MRI compatible linker scripts as an alternative to the more general-purpose
+linker scripting language described in Scripts. MRI compatible linker scripts
+have a much simpler command set than the scripting language otherwise used
+with
+.Xr ld .
+GNU
+.Xr ld
+supports the most commonly used MRI linker commands; these commands are described
+here.
+.Pp
+In general, MRI scripts aren't of much use with the
+.Li a.out
+object file format, since it only has three sections and MRI scripts lack
+some features to make use of them.
+.Pp
+You can specify a file containing an MRI-compatible script using the
+.Li -c
+command-line option.
+.Pp
+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,
+.Xr ld
+issues a warning message, but continues processing the script.
+.Pp
+Lines beginning with
+.Li *
+are comments.
+.Pp
+You can write these commands using all upper-case letters, or all lower case;
+for example,
+.Li chip
+is the same as
+.Li CHIP .
+The following list shows only the upper-case form of each command.
+.Pp
+.Bl -tag -width Ds
+.It  ABSOLUTE Va secname
+.It  ABSOLUTE Va secname, Va secname, ... Va secname
+Normally,
+.Xr ld
+includes in the output file all sections from all the input files. However,
+in an MRI-compatible script, you can use the
+.Li ABSOLUTE
+command to restrict the sections that will be present in your output program.
+If the
+.Li ABSOLUTE
+command is used at all in a script, then only the sections named explicitly
+in
+.Li ABSOLUTE
+commands will appear in the linker output. You can still use other input sections
+(whatever you select on the command line, or using
+.Li LOAD )
+to resolve addresses in the output file.
+.Pp
+.It  ALIAS Va out-secname, Va in-secname
+Use this command to place the data from input section
+.Va in-secname
+in a section called
+.Va out-secname
+in the linker output file.
+.Pp
+.Va in-secname
+may be an integer.
+.Pp
+.It  ALIGN Va secname = Va expression
+Align the section called
+.Va secname
+to
+.Va expression .
+The
+.Va expression
+should be a power of two.
+.Pp
+.It  BASE Va expression
+Use the value of
+.Va expression
+as the lowest address (other than absolute addresses) in the output file.
+.Pp
+.It  CHIP Va expression
+.It  CHIP Va expression, Va expression
+This command does nothing; it is accepted only for compatibility.
+.Pp
+.It  END
+This command does nothing whatever; it's only accepted for compatibility.
+.Pp
+.It  FORMAT Va output-format
+Similar to the
+.Li OUTPUT_FORMAT
+command in the more general linker language, but restricted to one of these
+output formats:
+.Pp
+.Bl -enum
+.It
+S-records, if
+.Va output-format
+is
+.Li S
+.Pp
+.It
+IEEE, if
+.Va output-format
+is
+.Li IEEE
+.Pp
+.It
+COFF (the
+.Li coff-m68k
+variant in BFD), if
+.Va output-format
+is
+.Li COFF
+.El
+.Pp
+.It  LIST Va anything...
+Print (to the standard output file) a link map, as produced by the
+.Xr ld
+command-line option
+.Li -M .
+.Pp
+The keyword
+.Li LIST
+may be followed by anything on the same line, with no change in its effect.
+.Pp
+.It  LOAD Va filename
+.It  LOAD Va filename, Va filename, ... Va filename
+Include one or more object file
+.Va filename
+in the link; this has the same effect as specifying
+.Va filename
+directly on the
+.Xr ld
+command line.
+.Pp
+.It  NAME Va output-name
+.Va output-name
+is the name for the program produced by
+.Xr ld ;
+the MRI-compatible command
+.Li NAME
+is equivalent to the command-line option
+.Li -o
+or the general script language command
+.Li OUTPUT .
+.Pp
+.It  ORDER Va secname, Va secname, ... Va secname
+.It  ORDER Va secname Va secname Va secname
+Normally,
+.Xr 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
+.Li ORDER
+command. The sections you list with
+.Li ORDER
+will appear first in your output file, in the order specified.
+.Pp
+.It  PUBLIC Va name= Va expression
+.It  PUBLIC Va name, Va expression
+.It  PUBLIC Va name Va expression
+Supply a value (
+.Va expression )
+for external symbol
+.Va name
+used in the linker input files.
+.Pp
+.It  SECT Va secname, Va expression
+.It  SECT Va secname= Va expression
+.It  SECT Va secname Va expression
+You can use any of these three forms of the
+.Li SECT
+command to specify the start address (
+.Va expression )
+for section
+.Va secname .
+If you have more than one
+.Li SECT
+statement for the same
+.Va secname ,
+only the
+.Em first
+sets the start address.
+.El
+.Pp
+.Sh  GNU Free Documentation License
+.Bd -filled -offset indent
+Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street,
+Fifth Floor, Boston, MA 02110-1301 USA
+.Pp
+Everyone is permitted to copy and distribute verbatim copies of this license
+document, but changing it is not allowed.
+.Ed
+.Pp
+.Bl -enum
+.It
+PREAMBLE
+.Pp
+The purpose of this License is to make a manual, textbook, or other written
+document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom
+to copy and redistribute it, with or without modifying it, either commercially
+or noncommercially. Secondarily, this License preserves for the author and
+publisher a way to get credit for their work, while not being considered responsible
+for modifications made by others.
+.Pp
+This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the
+document must themselves be free in the same sense. It complements the GNU
+General Public License, which is a copyleft license designed for free software.
+.Pp
+We have designed this License in order to use it for manuals for free software,
+because free software needs free documentation: a free program should come
+with manuals providing the same freedoms that the software does. But this
+License is not limited to software manuals; it can be used for any textual
+work, regardless of subject matter or whether it is published as a printed
+book. We recommend this License principally for works whose purpose is instruction
+or reference.
+.Pp
+.It
+APPLICABILITY AND DEFINITIONS
+.Pp
+This License applies to any manual or other work that contains a notice placed
+by the copyright holder saying it can be distributed under the terms of this
+License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member
+of the public is a licensee, and is addressed as \(lqyou.\(rq
+.Pp
+A \(lqModified Version\(rq of the Document means any work containing the Document
+or a portion of it, either copied verbatim, or with modifications and/or translated
+into another language.
+.Pp
+A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document
+that deals exclusively with the relationship of the publishers or authors
+of the Document to the Document's overall subject (or to related matters)
+and contains nothing that could fall directly within that overall subject.
+(For example, if the Document is in part a textbook of mathematics, a Secondary
+Section may not explain any mathematics.) The relationship could be a matter
+of historical connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding them.
+.Pp
+The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated,
+as being those of Invariant Sections, in the notice that says that the Document
+is released under this License.
+.Pp
+The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover
+Texts or Back-Cover Texts, in the notice that says that the Document is released
+under this License.
+.Pp
+A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented
+in a format whose specification is available to the general public, whose
+contents can be viewed and edited directly and straightforwardly with generic
+text editors or (for images composed of pixels) generic paint programs or
+(for drawings) some widely available drawing editor, and that is suitable
+for input to text formatters or for automatic translation to a variety of
+formats suitable for input to text formatters. A copy made in an otherwise
+Transparent file format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is not
+\(lqTransparent\(rq is called \(lqOpaque.\(rq
+.Pp
+Examples of suitable formats for Transparent copies include plain ASCII without
+markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly
+available DTD, and standard-conforming simple HTML designed for human modification.
+Opaque formats include PostScript, PDF, proprietary formats that can be read
+and edited only by proprietary word processors, SGML or XML for which the
+DTD and/or processing tools are not generally available, and the machine-generated
+HTML produced by some word processors for output purposes only.
+.Pp
+The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such
+following pages as are needed to hold, legibly, the material this License
+requires to appear in the title page. For works in formats which do not have
+any title page as such, \(lqTitle Page\(rq means the text near the most prominent
+appearance of the work's title, preceding the beginning of the body of the
+text.
+.Pp
+.It
+VERBATIM COPYING
+.Pp
+You may copy and distribute the Document in any medium, either commercially
+or noncommercially, provided that this License, the copyright notices, and
+the license notice saying this License applies to the Document are reproduced
+in all copies, and that you add no other conditions whatsoever to those of
+this License. You may not use technical measures to obstruct or control the
+reading or further copying of the copies you make or distribute. However,
+you may accept compensation in exchange for copies. If you distribute a large
+enough number of copies you must also follow the conditions in section 3.
+.Pp
+You may also lend copies, under the same conditions stated above, and you
+may publicly display copies.
+.Pp
+.It
+COPYING IN QUANTITY
+.Pp
+If you publish printed copies of the Document numbering more than 100, and
+the Document's license notice requires Cover Texts, you must enclose the copies
+in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover
+Texts on the front cover, and Back-Cover Texts on the back cover. Both covers
+must also clearly and legibly identify you as the publisher of these copies.
+The front cover must present the full title with all words of the title equally
+prominent and visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve the title
+of the Document and satisfy these conditions, can be treated as verbatim copying
+in other respects.
+.Pp
+If the required texts for either cover are too voluminous to fit legibly,
+you should put the first ones listed (as many as fit reasonably) on the actual
+cover, and continue the rest onto adjacent pages.
+.Pp
+If you publish or distribute Opaque copies of the Document numbering more
+than 100, you must either include a machine-readable Transparent copy along
+with each Opaque copy, or state in or with each Opaque copy a publicly-accessible
+computer-network location containing a complete Transparent copy of the Document,
+free of added material, which the general network-using public has access
+to download anonymously at no charge using public-standard network protocols.
+If you use the latter option, you must take reasonably prudent steps, when
+you begin distribution of Opaque copies in quantity, to ensure that this Transparent
+copy will remain thus accessible at the stated location until at least one
+year after the last time you distribute an Opaque copy (directly or through
+your agents or retailers) of that edition to the public.
+.Pp
+It is requested, but not required, that you contact the authors of the Document
+well before redistributing any large number of copies, to give them a chance
+to provide you with an updated version of the Document.
+.Pp
+.It
+MODIFICATIONS
+.Pp
+You may copy and distribute a Modified Version of the Document under the conditions
+of sections 2 and 3 above, provided that you release the Modified Version
+under precisely this License, with the Modified Version filling the role of
+the Document, thus licensing distribution and modification of the Modified
+Version to whoever possesses a copy of it. In addition, you must do these
+things in the Modified Version:
+.Pp
+A. Use in the Title Page (and on the covers, if any) a title distinct from
+that of the Document, and from those of previous versions (which should, if
+there were any, be listed in the History section of the Document). You may
+use the same title as a previous version if the original publisher of that
+version gives permission.  B. List on the Title Page, as authors, one or more
+persons or entities responsible for authorship of the modifications in the
+Modified Version, together with at least five of the principal authors of
+the Document (all of its principal authors, if it has less than five).  C.
+State on the Title page the name of the publisher of the Modified Version,
+as the publisher.  D. Preserve all the copyright notices of the Document. 
+E. Add an appropriate copyright notice for your modifications adjacent to
+the other copyright notices.  F. Include, immediately after the copyright
+notices, a license notice giving the public permission to use the Modified
+Version under the terms of this License, in the form shown in the Addendum
+below.  G. Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.  H. Include
+an unaltered copy of this License.  I. Preserve the section entitled \(lqHistory\(rq,
+and its title, and add to it an item stating at least the title, year, new
+authors, and publisher of the Modified Version as given on the Title Page.
+If there is no section entitled \(lqHistory\(rq in the Document, create one stating
+the title, year, authors, and publisher of the Document as given on its Title
+Page, then add an item describing the Modified Version as stated in the previous
+sentence.  J. Preserve the network location, if any, given in the Document
+for public access to a Transparent copy of the Document, and likewise the
+network locations given in the Document for previous versions it was based
+on. These may be placed in the \(lqHistory\(rq section. You may omit a network location
+for a work that was published at least four years before the Document itself,
+or if the original publisher of the version it refers to gives permission. 
+K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's
+title, and preserve in the section all the substance and tone of each of the
+contributor acknowledgements and/or dedications given therein.  L. Preserve
+all the Invariant Sections of the Document, unaltered in their text and in
+their titles. Section numbers or the equivalent are not considered part of
+the section titles.  M. Delete any section entitled \(lqEndorsements.\(rq Such a section
+may not be included in the Modified Version.  N. Do not retitle any existing
+section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. 
+.Pp
+If the Modified Version includes new front-matter sections or appendices that
+qualify as Secondary Sections and contain no material copied from the Document,
+you may at your option designate some or all of these sections as invariant.
+To do this, add their titles to the list of Invariant Sections in the Modified
+Version's license notice. These titles must be distinct from any other section
+titles.
+.Pp
+You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing
+but endorsements of your Modified Version by various parties--for example,
+statements of peer review or that the text has been approved by an organization
+as the authoritative definition of a standard.
+.Pp
+You may add a passage of up to five words as a Front-Cover Text, and a passage
+of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts
+in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover
+Text may be added by (or through arrangements made by) any one entity. If
+the Document already includes a cover text for the same cover, previously
+added by you or by arrangement made by the same entity you are acting on behalf
+of, you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+.Pp
+The author(s) and publisher(s) of the Document do not by this License give
+permission to use their names for publicity for or to assert or imply endorsement
+of any Modified Version.
+.Pp
+.It
+COMBINING DOCUMENTS
+.Pp
+You may combine the Document with other documents released under this License,
+under the terms defined in section 4 above for modified versions, provided
+that you include in the combination all of the Invariant Sections of all of
+the original documents, unmodified, and list them all as Invariant Sections
+of your combined work in its license notice.
+.Pp
+The combined work need only contain one copy of this License, and multiple
+identical Invariant Sections may be replaced with a single copy. If there
+are multiple Invariant Sections with the same name but different contents,
+make the title of each such section unique by adding at the end of it, in
+parentheses, the name of the original author or publisher of that section
+if known, or else a unique number. Make the same adjustment to the section
+titles in the list of Invariant Sections in the license notice of the combined
+work.
+.Pp
+In the combination, you must combine any sections entitled \(lqHistory\(rq in the
+various original documents, forming one section entitled \(lqHistory\(rq; likewise
+combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled
+\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq
+.Pp
+.It
+COLLECTIONS OF DOCUMENTS
+.Pp
+You may make a collection consisting of the Document and other documents released
+under this License, and replace the individual copies of this License in the
+various documents with a single copy that is included in the collection, provided
+that you follow the rules of this License for verbatim copying of each of
+the documents in all other respects.
+.Pp
+You may extract a single document from such a collection, and distribute it
+individually under this License, provided you insert a copy of this License
+into the extracted document, and follow this License in all other respects
+regarding verbatim copying of that document.
+.Pp
+.It
+AGGREGATION WITH INDEPENDENT WORKS
+.Pp
+A compilation of the Document or its derivatives with other separate and independent
+documents or works, in or on a volume of a storage or distribution medium,
+does not as a whole count as a Modified Version of the Document, provided
+no compilation copyright is claimed for the compilation. Such a compilation
+is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained
+works thus compiled with the Document, on account of their being thus compiled,
+if they are not themselves derivative works of the Document.
+.Pp
+If the Cover Text requirement of section 3 is applicable to these copies of
+the Document, then if the Document is less than one quarter of the entire
+aggregate, the Document's Cover Texts may be placed on covers that surround
+only the Document within the aggregate. Otherwise they must appear on covers
+around the whole aggregate.
+.Pp
+.It
+TRANSLATION
+.Pp
+Translation is considered a kind of modification, so you may distribute translations
+of the Document under the terms of section 4. Replacing Invariant Sections
+with translations requires special permission from their copyright holders,
+but you may include translations of some or all Invariant Sections in addition
+to the original versions of these Invariant Sections. You may include a translation
+of this License provided that you also include the original English version
+of this License. In case of a disagreement between the translation and the
+original English version of this License, the original English version will
+prevail.
+.Pp
+.It
+TERMINATION
+.Pp
+You may not copy, modify, sublicense, or distribute the Document except as
+expressly provided for under this License. Any other attempt to copy, modify,
+sublicense or distribute the Document is void, and will automatically terminate
+your rights under this License. However, parties who have received copies,
+or rights, from you under this License will not have their licenses terminated
+so long as such parties remain in full compliance.
+.Pp
+.It
+FUTURE REVISIONS OF THIS LICENSE
+.Pp
+The Free Software Foundation may publish new, revised versions of the GNU
+Free Documentation License from time to time. Such new versions will be similar
+in spirit to the present version, but may differ in detail to address new
+problems or concerns. See http://www.gnu.org/copyleft/.
+.Pp
+Each version of the License is given a distinguishing version number. If the
+Document specifies that a particular numbered version of this License \(lqor any
+later version\(rq applies to it, you have the option of following the terms and
+conditions either of that specified version or of any later version that has
+been published (not as a draft) by the Free Software Foundation. If the Document
+does not specify a version number of this License, you may choose any version
+ever published (not as a draft) by the Free Software Foundation.
+.Pp
+.El
+.Ss  ADDENDUM: How to use this License for your documents
+To use this License in a document you have written, include a copy of the
+License in the document and put the following copyright and license notices
+just after the title page:
+.Pp
+.Bd -literal -offset indent
+
+Copyright (C)  year  your name.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with the Invariant Sections being list their titles, with the
+Front-Cover Texts being list, and with the Back-Cover Texts being list.
+A copy of the license is included in the section entitled "GNU
+Free Documentation License."
+
+.Ed
+.Pp
+If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead
+of saying which ones are invariant. If you have no Front-Cover Texts, write
+\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being
+.Va list
+\(rq; likewise for Back-Cover Texts.
+.Pp
+If your document contains nontrivial examples of program code, we recommend
+releasing these examples in parallel under your choice of free software license,
+such as the GNU General Public License, to permit their use in free software.
+.Pp
+.Sh  LD Index
diff --git a/contrib/binutils/ld/ldint.7 b/contrib/binutils/ld/ldint.7
new file mode 100644
index 0000000..6c17af4
--- /dev/null
+++ b/contrib/binutils/ld/ldint.7
@@ -0,0 +1,1277 @@
+.Dd 2015-03-02
+.Dt LDINT 7
+.Os
+.Sh NAME
+.Nm ldint
+.Nd GNU Linker Internals
+.Sh 
+This file documents the internals of the GNU linker
+.Li ld .
+It is a collection of miscellaneous information with little form at this point.
+Mostly, it is a repository into which you can put information about GNU
+.Li ld
+as you discover it (or as you design changes to
+.Li ld ) .
+.Pp
+This document is distributed under the terms of the GNU Free Documentation
+License. A copy of the license is included in the section entitled "GNU Free
+Documentation License".
+.Pp
+.Sh  The Pa README File
+Check the
+.Pa README
+file; it often has useful information that does not appear anywhere else in
+the directory.
+.Pp
+.Sh  How linker emulations are generated
+Each linker target has an
+.Em emulation .
+The emulation includes the default linker script, and certain emulations also
+modify certain types of linker behaviour.
+.Pp
+Emulations are created during the build process by the shell script
+.Pa genscripts.sh .
+.Pp
+The
+.Pa genscripts.sh
+script starts by reading a file in the
+.Pa emulparams
+directory. This is a shell script which sets various shell variables used
+by
+.Pa genscripts.sh
+and the other shell scripts it invokes.
+.Pp
+The
+.Pa genscripts.sh
+script will invoke a shell script in the
+.Pa scripttempl
+directory in order to create default linker scripts written in the linker
+command language. The
+.Pa scripttempl
+script will be invoked 5 (or, in some cases, 6) times, with different assignments
+to shell variables, to create different default scripts. The choice of script
+is made based on the command line options.
+.Pp
+After creating the scripts,
+.Pa genscripts.sh
+will invoke yet another shell script, this time in the
+.Pa emultempl
+directory. That shell script will create the emulation source file, which
+contains C code. This C code permits the linker emulation to override various
+linker behaviours. Most targets use the generic emulation code, which is in
+.Pa emultempl/generic.em .
+.Pp
+To summarize,
+.Pa genscripts.sh
+reads three shell scripts: an emulation parameters script in the
+.Pa emulparams
+directory, a linker script generation script in the
+.Pa scripttempl
+directory, and an emulation source file generation script in the
+.Pa emultempl
+directory.
+.Pp
+For example, the Sun 4 linker sets up variables in
+.Pa emulparams/sun4.sh ,
+creates linker scripts using
+.Pa scripttempl/aout.sc ,
+and creates the emulation code using
+.Pa emultempl/sunos.em .
+.Pp
+Note that the linker can support several emulations simultaneously, depending
+upon how it is configured. An emulation can be selected with the
+.Li -m
+option. The
+.Li -V
+option will list all supported emulations.
+.Pp
+.Ss  Pa emulparams scripts
+Each target selects a particular file in the
+.Pa emulparams
+directory by setting the shell variable
+.Li targ_emul
+in
+.Pa configure.tgt .
+This shell variable is used by the
+.Pa configure
+script to control building an emulation source file.
+.Pp
+Certain conventions are enforced. Suppose the
+.Li targ_emul
+variable is set to
+.Va emul
+in
+.Pa configure.tgt .
+The name of the emulation shell script will be
+.Pa emulparams/ Va emul.sh .
+The
+.Pa Makefile
+must have a target named
+.Pa e Va emul.c ;
+this target must depend upon
+.Pa emulparams/ Va emul.sh ,
+as well as the appropriate scripts in the
+.Pa scripttempl
+and
+.Pa emultempl
+directories. The
+.Pa Makefile
+target must invoke
+.Li GENSCRIPTS
+with two arguments:
+.Va emul ,
+and the value of the make variable
+.Li tdir_ Va emul .
+The value of the latter variable will be set by the
+.Pa configure
+script, and is used to set the default target directory to search.
+.Pp
+By convention, the
+.Pa emulparams/ Va emul.sh
+shell script should only set shell variables. It may set shell variables which
+are to be interpreted by the
+.Pa scripttempl
+and the
+.Pa emultempl
+scripts. Certain shell variables are interpreted directly by the
+.Pa genscripts.sh
+script.
+.Pp
+Here is a list of shell variables interpreted by
+.Pa genscripts.sh ,
+as well as some conventional shell variables interpreted by the
+.Pa scripttempl
+and
+.Pa emultempl
+scripts.
+.Pp
+.Bl -tag -width Ds
+.It  SCRIPT_NAME
+This is the name of the
+.Pa scripttempl
+script to use. If
+.Li SCRIPT_NAME
+is set to
+.Va script ,
+.Pa genscripts.sh
+will use the script
+.Pa scripttempl/ Va script.sc .
+.Pp
+.It  TEMPLATE_NAME
+This is the name of the
+.Pa emultempl
+script to use. If
+.Li TEMPLATE_NAME
+is set to
+.Va template ,
+.Pa genscripts.sh
+will use the script
+.Pa emultempl/ Va template.em .
+If this variable is not set, the default value is
+.Li generic .
+.Pp
+.It  GENERATE_SHLIB_SCRIPT
+If this is set to a nonempty string,
+.Pa genscripts.sh
+will invoke the
+.Pa scripttempl
+script an extra time to create a shared library script. linker scripts.
+.Pp
+.It  OUTPUT_FORMAT
+This is normally set to indicate the BFD output format use (e.g.,
+.Li "a.out-sunos-big" .
+The
+.Pa scripttempl
+script will normally use it in an
+.Li OUTPUT_FORMAT
+expression in the linker script.
+.Pp
+.It  ARCH
+This is normally set to indicate the architecture to use (e.g.,
+.Li sparc ) .
+The
+.Pa scripttempl
+script will normally use it in an
+.Li OUTPUT_ARCH
+expression in the linker script.
+.Pp
+.It  ENTRY
+Some
+.Pa scripttempl
+scripts use this to set the entry address, in an
+.Li ENTRY
+expression in the linker script.
+.Pp
+.It  TEXT_START_ADDR
+Some
+.Pa scripttempl
+scripts use this to set the start address of the
+.Li .text
+section.
+.Pp
+.It  NONPAGED_TEXT_START_ADDR
+If this is defined, the
+.Pa genscripts.sh
+script sets
+.Li TEXT_START_ADDR
+to its value before running the
+.Pa scripttempl
+script for the
+.Li -n
+and
+.Li -N
+options (see Section
+.Dq linker scripts ) .
+.Pp
+.It  SEGMENT_SIZE
+The
+.Pa genscripts.sh
+script uses this to set the default value of
+.Li DATA_ALIGNMENT
+when running the
+.Pa scripttempl
+script.
+.Pp
+.It  TARGET_PAGE_SIZE
+If
+.Li SEGMENT_SIZE
+is not defined, the
+.Pa genscripts.sh
+script uses this to define it.
+.Pp
+.It  ALIGNMENT
+Some
+.Pa scripttempl
+scripts set this to a number to pass to
+.Li ALIGN
+to set the required alignment for the
+.Li end
+symbol.
+.El
+.Pp
+.Ss  Pa scripttempl scripts
+Each linker target uses a
+.Pa scripttempl
+script to generate the default linker scripts. The name of the
+.Pa scripttempl
+script is set by the
+.Li SCRIPT_NAME
+variable in the
+.Pa emulparams
+script. If
+.Li SCRIPT_NAME
+is set to
+.Va script ,
+.Li genscripts.sh
+will invoke
+.Pa scripttempl/ Va script.sc .
+.Pp
+The
+.Pa genscripts.sh
+script will invoke the
+.Pa scripttempl
+script 5 to 8 times. Each time it will set the shell variable
+.Li LD_FLAG
+to a different value. When the linker is run, the options used will direct
+it to select a particular script. (Script selection is controlled by the
+.Li get_script
+emulation entry point; this describes the conventional behaviour).
+.Pp
+The
+.Pa scripttempl
+script should just write a linker script, written in the linker command language,
+to standard output. If the emulation name--the name of the
+.Pa emulparams
+file without the
+.Pa .sc
+extension--is
+.Va emul ,
+then the output will be directed to
+.Pa ldscripts/ Va emul. Va extension
+in the build directory, where
+.Va extension
+changes each time the
+.Pa scripttempl
+script is invoked.
+.Pp
+Here is the list of values assigned to
+.Li LD_FLAG .
+.Pp
+.Bl -tag -width Ds
+.It  (empty)
+The script generated is used by default (when none of the following cases
+apply). The output has an extension of
+.Pa .x .
+.It  n
+The script generated is used when the linker is invoked with the
+.Li -n
+option. The output has an extension of
+.Pa .xn .
+.It  N
+The script generated is used when the linker is invoked with the
+.Li -N
+option. The output has an extension of
+.Pa .xbn .
+.It  r
+The script generated is used when the linker is invoked with the
+.Li -r
+option. The output has an extension of
+.Pa .xr .
+.It  u
+The script generated is used when the linker is invoked with the
+.Li -Ur
+option. The output has an extension of
+.Pa .xu .
+.It  shared
+The
+.Pa scripttempl
+script is only invoked with
+.Li LD_FLAG
+set to this value if
+.Li GENERATE_SHLIB_SCRIPT
+is defined in the
+.Pa emulparams
+file. The
+.Pa emultempl
+script must arrange to use this script at the appropriate time, normally when
+the linker is invoked with the
+.Li -shared
+option. The output has an extension of
+.Pa .xs .
+.It  c
+The
+.Pa scripttempl
+script is only invoked with
+.Li LD_FLAG
+set to this value if
+.Li GENERATE_COMBRELOC_SCRIPT
+is defined in the
+.Pa emulparams
+file or if
+.Li SCRIPT_NAME
+is
+.Li elf .
+The
+.Pa emultempl
+script must arrange to use this script at the appropriate time, normally when
+the linker is invoked with the
+.Li -z combreloc
+option. The output has an extension of
+.Pa .xc .
+.It  cshared
+The
+.Pa scripttempl
+script is only invoked with
+.Li LD_FLAG
+set to this value if
+.Li GENERATE_COMBRELOC_SCRIPT
+is defined in the
+.Pa emulparams
+file or if
+.Li SCRIPT_NAME
+is
+.Li elf
+and
+.Li GENERATE_SHLIB_SCRIPT
+is defined in the
+.Pa emulparams
+file. The
+.Pa emultempl
+script must arrange to use this script at the appropriate time, normally when
+the linker is invoked with the
+.Li -shared -z combreloc
+option. The output has an extension of
+.Pa .xsc .
+.El
+.Pp
+Besides the shell variables set by the
+.Pa emulparams
+script, and the
+.Li LD_FLAG
+variable, the
+.Pa genscripts.sh
+script will set certain variables for each run of the
+.Pa scripttempl
+script.
+.Pp
+.Bl -tag -width Ds
+.It  RELOCATING
+This will be set to a non-empty string when the linker is doing a final relocation
+(e.g., all scripts other than
+.Li -r
+and
+.Li -Ur ) .
+.Pp
+.It  CONSTRUCTING
+This will be set to a non-empty string when the linker is building global
+constructor and destructor tables (e.g., all scripts other than
+.Li -r ) .
+.Pp
+.It  DATA_ALIGNMENT
+This will be set to an
+.Li ALIGN
+expression when the output should be page aligned, or to
+.Li .
+when generating the
+.Li -N
+script.
+.Pp
+.It  CREATE_SHLIB
+This will be set to a non-empty string when generating a
+.Li -shared
+script.
+.Pp
+.It  COMBRELOC
+This will be set to a non-empty string when generating
+.Li -z combreloc
+scripts to a temporary file name which can be used during script generation.
+.El
+.Pp
+The conventional way to write a
+.Pa scripttempl
+script is to first set a few shell variables, and then write out a linker
+script using
+.Li cat
+with a here document. The linker script will use variable substitutions, based
+on the above variables and those set in the
+.Pa emulparams
+script, to control its behaviour.
+.Pp
+When there are parts of the
+.Pa scripttempl
+script which should only be run when doing a final relocation, they should
+be enclosed within a variable substitution based on
+.Li RELOCATING .
+For example, on many targets special symbols such as
+.Li _end
+should be defined when doing a final link. Naturally, those symbols should
+not be defined when doing a relocatable link using
+.Li -r .
+The
+.Pa scripttempl
+script could use a construct like this to define those symbols:
+.Bd -literal -offset indent
+  ${RELOCATING+ _end = .;}
+.Ed
+This will do the symbol assignment only if the
+.Li RELOCATING
+variable is defined.
+.Pp
+The basic job of the linker script is to put the sections in the correct order,
+and at the correct memory addresses. For some targets, the linker script may
+have to do some other operations.
+.Pp
+For example, on most MIPS platforms, the linker is responsible for defining
+the special symbol
+.Li _gp ,
+used to initialize the
+.Li $gp
+register. It must be set to the start of the small data section plus
+.Li 0x8000 .
+Naturally, it should only be defined when doing a final relocation. This will
+typically be done like this:
+.Bd -literal -offset indent
+  ${RELOCATING+ _gp = ALIGN(16) + 0x8000;}
+.Ed
+This line would appear just before the sections which compose the small data
+section (
+.Li .sdata ,
+.Li .sbss ) .
+All those sections would be contiguous in memory.
+.Pp
+Many COFF systems build constructor tables in the linker script. The compiler
+will arrange to output the address of each global constructor in a
+.Li .ctor
+section, and the address of each global destructor in a
+.Li .dtor
+section (this is done by defining
+.Li ASM_OUTPUT_CONSTRUCTOR
+and
+.Li ASM_OUTPUT_DESTRUCTOR
+in the
+.Li gcc
+configuration files). The
+.Li gcc
+runtime support routines expect the constructor table to be named
+.Li __CTOR_LIST__ .
+They expect it to be a list of words, with the first word being the count
+of the number of entries. There should be a trailing zero word. (Actually,
+the count may be -1 if the trailing word is present, and the trailing word
+may be omitted if the count is correct, but, as the
+.Li gcc
+behaviour has changed slightly over the years, it is safest to provide both).
+Here is a typical way that might be handled in a
+.Pa scripttempl
+file.
+.Bd -literal -offset indent
+    ${CONSTRUCTING+ __CTOR_LIST__ = .;}
+    ${CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)}
+    ${CONSTRUCTING+ *(.ctors)}
+    ${CONSTRUCTING+ LONG(0)}
+    ${CONSTRUCTING+ __CTOR_END__ = .;}
+    ${CONSTRUCTING+ __DTOR_LIST__ = .;}
+    ${CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)}
+    ${CONSTRUCTING+ *(.dtors)}
+    ${CONSTRUCTING+ LONG(0)}
+    ${CONSTRUCTING+ __DTOR_END__ = .;}
+.Ed
+The use of
+.Li CONSTRUCTING
+ensures that these linker script commands will only appear when the linker
+is supposed to be building the constructor and destructor tables. This example
+is written for a target which uses 4 byte pointers.
+.Pp
+Embedded systems often need to set a stack address. This is normally best
+done by using the
+.Li PROVIDE
+construct with a default stack address. This permits the user to easily override
+the stack address using the
+.Li --defsym
+option. Here is an example:
+.Bd -literal -offset indent
+  ${RELOCATING+ PROVIDE (__stack = 0x80000000);}
+.Ed
+The value of the symbol
+.Li __stack
+would then be used in the startup code to initialize the stack pointer.
+.Pp
+.Ss  Pa emultempl scripts
+Each linker target uses an
+.Pa emultempl
+script to generate the emulation code. The name of the
+.Pa emultempl
+script is set by the
+.Li TEMPLATE_NAME
+variable in the
+.Pa emulparams
+script. If the
+.Li TEMPLATE_NAME
+variable is not set, the default is
+.Li generic .
+If the value of
+.Li TEMPLATE_NAME
+is
+.Va template ,
+.Pa genscripts.sh
+will use
+.Pa emultempl/ Va template.em .
+.Pp
+Most targets use the generic
+.Pa emultempl
+script,
+.Pa emultempl/generic.em .
+A different
+.Pa emultempl
+script is only needed if the linker must support unusual actions, such as
+linking against shared libraries.
+.Pp
+The
+.Pa emultempl
+script is normally written as a simple invocation of
+.Li cat
+with a here document. The document will use a few variable substitutions.
+Typically each function names uses a substitution involving
+.Li EMULATION_NAME ,
+for ease of debugging when the linker supports multiple emulations.
+.Pp
+Every function and variable in the emitted file should be static. The only
+globally visible object must be named
+.Li ld_ Va EMULATION_NAME_emulation ,
+where
+.Va EMULATION_NAME
+is the name of the emulation set in
+.Pa configure.tgt
+(this is also the name of the
+.Pa emulparams
+file without the
+.Pa .sh
+extension). The
+.Pa genscripts.sh
+script will set the shell variable
+.Li EMULATION_NAME
+before invoking the
+.Pa emultempl
+script.
+.Pp
+The
+.Li ld_ Va EMULATION_NAME_emulation
+variable must be a
+.Li struct ld_emulation_xfer_struct ,
+as defined in
+.Pa ldemul.h .
+It defines a set of function pointers which are invoked by the linker, as
+well as strings for the emulation name (normally set from the shell variable
+.Li EMULATION_NAME
+and the default BFD target name (normally set from the shell variable
+.Li OUTPUT_FORMAT
+which is normally set by the
+.Pa emulparams
+file).
+.Pp
+The
+.Pa genscripts.sh
+script will set the shell variable
+.Li COMPILE_IN
+when it invokes the
+.Pa emultempl
+script for the default emulation. In this case, the
+.Pa emultempl
+script should include the linker scripts directly, and return them from the
+.Li get_scripts
+entry point. When the emulation is not the default, the
+.Li get_scripts
+entry point should just return a file name. See
+.Pa emultempl/generic.em
+for an example of how this is done.
+.Pp
+At some point, the linker emulation entry points should be documented.
+.Pp
+.Sh  A Walkthrough of a Typical Emulation
+This chapter is to help people who are new to the way emulations interact
+with the linker, or who are suddenly thrust into the position of having to
+work with existing emulations. It will discuss the files you need to be aware
+of. It will tell you when the given "hooks" in the emulation will be called.
+It will, hopefully, give you enough information about when and how things
+happen that you'll be able to get by. As always, the source is the definitive
+reference to this.
+.Pp
+The starting point for the linker is in
+.Pa ldmain.c
+where
+.Li main
+is defined. The bulk of the code that's emulation specific will initially
+be in
+.Li emultempl/ Va emulation.em
+but will end up in
+.Li e Va emulation.c
+when the build is done. Most of the work to select and interface with emulations
+is in
+.Li ldemul.h
+and
+.Li ldemul.c .
+Specifically,
+.Li ldemul.h
+defines the
+.Li ld_emulation_xfer_struct
+structure your emulation exports.
+.Pp
+Your emulation file exports a symbol
+.Li ld_ Va EMULATION_NAME_emulation .
+If your emulation is selected (it usually is, since usually there's only one),
+.Li ldemul.c
+sets the variable
+.Va ld_emulation
+to point to it.
+.Li ldemul.c
+also defines a number of API functions that interface to your emulation, like
+.Li ldemul_after_parse
+which simply calls your
+.Li ld_ Va EMULATION_emulation.after_parse
+function. For the rest of this section, the functions will be mentioned, but
+you should assume the indirect reference to your emulation also.
+.Pp
+We will also skip or gloss over parts of the link process that don't relate
+to emulations, like setting up internationalization.
+.Pp
+After initialization,
+.Li main
+selects an emulation by pre-scanning the command line arguments. It calls
+.Li ldemul_choose_target
+to choose a target. If you set
+.Li choose_target
+to
+.Li ldemul_default_target ,
+it picks your
+.Li target_name
+by default.
+.Pp
+.Li main
+calls
+.Li ldemul_before_parse ,
+then
+.Li parse_args .
+.Li parse_args
+calls
+.Li ldemul_parse_args
+for each arg, which must update the
+.Li getopt
+globals if it recognizes the argument. If the emulation doesn't recognize
+it, then parse_args checks to see if it recognizes it.
+.Pp
+Now that the emulation has had access to all its command-line options,
+.Li main
+calls
+.Li ldemul_set_symbols .
+This can be used for any initialization that may be affected by options. It
+is also supposed to set up any variables needed by the emulation script.
+.Pp
+.Li main
+now calls
+.Li ldemul_get_script
+to get the emulation script to use (based on arguments, no doubt,see Section
+.Dq Emulations )
+and runs it. While parsing,
+.Li ldgram.y
+may call
+.Li ldemul_hll
+or
+.Li ldemul_syslib
+to handle the
+.Li HLL
+or
+.Li SYSLIB
+commands. It may call
+.Li ldemul_unrecognized_file
+if you asked the linker to link a file it doesn't recognize. It will call
+.Li ldemul_recognized_file
+for each file it does recognize, in case the emulation wants to handle some
+files specially. All the while, it's loading the files (possibly calling
+.Li ldemul_open_dynamic_archive )
+and symbols and stuff. After it's done reading the script,
+.Li main
+calls
+.Li ldemul_after_parse .
+Use the after-parse hook to set up anything that depends on stuff the script
+might have set up, like the entry point.
+.Pp
+.Li main
+next calls
+.Li lang_process
+in
+.Li ldlang.c .
+This appears to be the main core of the linking itself, as far as emulation
+hooks are concerned(*). It first opens the output file's BFD, calling
+.Li ldemul_set_output_arch ,
+and calls
+.Li ldemul_create_output_section_statements
+in case you need to use other means to find or create object files (i.e. shared
+libraries found on a path, or fake stub objects). Despite the name, nobody
+creates output sections here.
+.Pp
+(*) In most cases, the BFD library does the bulk of the actual linking, handling
+symbol tables, symbol resolution, relocations, and building the final output
+file. See the BFD reference for all the details. Your emulation is usually
+concerned more with managing things at the file and section level, like "put
+this here, add this section", etc.
+.Pp
+Next, the objects to be linked are opened and BFDs created for them, and
+.Li ldemul_after_open
+is called. At this point, you have all the objects and symbols loaded, but
+none of the data has been placed yet.
+.Pp
+Next comes the Big Linking Thingy (except for the parts BFD does). All input
+sections are mapped to output sections according to the script. If a section
+doesn't get mapped by default,
+.Li ldemul_place_orphan
+will get called to figure out where it goes. Next it figures out the offsets
+for each section, calling
+.Li ldemul_before_allocation
+before and
+.Li ldemul_after_allocation
+after deciding where each input section ends up in the output sections.
+.Pp
+The last part of
+.Li lang_process
+is to figure out all the symbols' values. After assigning final values to
+the symbols,
+.Li ldemul_finish
+is called, and after that, any undefined symbols are turned into fatal errors.
+.Pp
+OK, back to
+.Li main ,
+which calls
+.Li ldwrite
+in
+.Pa ldwrite.c .
+.Li ldwrite
+calls BFD's final_link, which does all the relocation fixups and writes the
+output bfd to disk, and we're done.
+.Pp
+In summary,
+.Pp
+.Bl -bullet
+.It
+.Li main()
+in
+.Pa ldmain.c
+.It
+.Pa emultempl/ Va EMULATION.em
+has your code
+.It
+.Li ldemul_choose_target
+(defaults to your
+.Li target_name )
+.It
+.Li ldemul_before_parse
+.It
+Parse argv, calls
+.Li ldemul_parse_args
+for each
+.It
+.Li ldemul_set_symbols
+.It
+.Li ldemul_get_script
+.It
+parse script
+.Pp
+.Bl -bullet
+.It
+may call
+.Li ldemul_hll
+or
+.Li ldemul_syslib
+.It
+may call
+.Li ldemul_open_dynamic_archive
+.El
+.Pp
+.It
+.Li ldemul_after_parse
+.It
+.Li lang_process()
+in
+.Pa ldlang.c
+.Pp
+.Bl -bullet
+.It
+create
+.Li output_bfd
+.It
+.Li ldemul_set_output_arch
+.It
+.Li ldemul_create_output_section_statements
+.It
+read objects, create input bfds - all symbols exist, but have no values
+.It
+may call
+.Li ldemul_unrecognized_file
+.It
+will call
+.Li ldemul_recognized_file
+.It
+.Li ldemul_after_open
+.It
+map input sections to output sections
+.It
+may call
+.Li ldemul_place_orphan
+for remaining sections
+.It
+.Li ldemul_before_allocation
+.It
+gives input sections offsets into output sections, places output sections
+.It
+.Li ldemul_after_allocation
+- section addresses valid
+.It
+assigns values to symbols
+.It
+.Li ldemul_finish
+- symbol values valid
+.El
+.Pp
+.It
+output bfd is written to disk
+.Pp
+.El
+.Sh  Some Architecture Specific Notes
+This is the place for notes on the behavior of
+.Li ld
+on specific platforms. Currently, only Intel x86 is documented (and of that,
+only the auto-import behavior for DLLs).
+.Pp
+.Ss  Intel x86
+.Bl -tag -width Ds
+.Li ld
+can create DLLs that operate with various runtimes available on a common x86
+operating system. These runtimes include native (using the mingw "platform"),
+cygwin, and pw.
+.Pp
+.It  auto-import from DLLs 
+.Bl -enum
+.It
+With this feature on, DLL clients can import variables from DLL without any
+concern from their side (for example, without any source code modifications).
+Auto-import can be enabled using the
+.Li --enable-auto-import
+flag, or disabled via the
+.Li --disable-auto-import
+flag. Auto-import is disabled by default.
+.Pp
+.It
+This is done completely in bounds of the PE specification (to be fair, there's
+a minor violation of the spec at one point, but in practice auto-import works
+on all known variants of that common x86 operating system) So, the resulting
+DLL can be used with any other PE compiler/linker.
+.Pp
+.It
+Auto-import is fully compatible with standard import method, in which variables
+are decorated using attribute modifiers. Libraries of either type may be mixed
+together.
+.Pp
+.It
+Overhead (space): 8 bytes per imported symbol, plus 20 for each reference
+to it; Overhead (load time): negligible; Overhead (virtual/physical memory):
+should be less than effect of DLL relocation.
+.El
+.Pp
+Motivation
+.Pp
+The obvious and only way to get rid of dllimport insanity is to make client
+access variable directly in the DLL, bypassing the extra dereference imposed
+by ordinary DLL runtime linking. I.e., whenever client contains something
+like
+.Pp
+.Li mov dll_var,%eax,
+.Pp
+address of dll_var in the command should be relocated to point into loaded
+DLL. The aim is to make OS loader do so, and than make ld help with that.
+Import section of PE made following way: there's a vector of structures each
+describing imports from particular DLL. Each such structure points to two
+other parallel vectors: one holding imported names, and one which will hold
+address of corresponding imported name. So, the solution is de-vectorize these
+structures, making import locations be sparse and pointing directly into code.
+.Pp
+Implementation
+.Pp
+For each reference of data symbol to be imported from DLL (to set of which
+belong symbols with name <sym>, if __imp_<sym> is found in implib), the import
+fixup entry is generated. That entry is of type IMAGE_IMPORT_DESCRIPTOR and
+stored in .idata$3 subsection. Each fixup entry contains pointer to symbol's
+address within .text section (marked with __fuN_<sym> symbol, where N is integer),
+pointer to DLL name (so, DLL name is referenced by multiple entries), and
+pointer to symbol name thunk. Symbol name thunk is singleton vector (__nm_th_<symbol>)
+pointing to IMAGE_IMPORT_BY_NAME structure (__nm_<symbol>) directly containing
+imported name. Here comes that "om the edge" problem mentioned above: PE specification
+rambles that name vector (OriginalFirstThunk) should run in parallel with
+addresses vector (FirstThunk), i.e. that they should have same number of elements
+and terminated with zero. We violate this, since FirstThunk points directly
+into machine code. But in practice, OS loader implemented the sane way: it
+goes thru OriginalFirstThunk and puts addresses to FirstThunk, not something
+else. It once again should be noted that dll and symbol name structures are
+reused across fixup entries and should be there anyway to support standard
+import stuff, so sustained overhead is 20 bytes per reference. Other question
+is whether having several IMAGE_IMPORT_DESCRIPTORS for the same DLL is possible.
+Answer is yes, it is done even by native compiler/linker (libth32's functions
+are in fact resident in windows9x kernel32.dll, so if you use it, you have
+two IMAGE_IMPORT_DESCRIPTORS for kernel32.dll). Yet other question is whether
+referencing the same PE structures several times is valid. The answer is why
+not, prohibiting that (detecting violation) would require more work on behalf
+of loader than not doing it.
+.Pp
+.El
+.Sh  GNU Free Documentation License
+GNU Free Documentation License Version 1.1, March 2000
+.Pp
+Copyright (C) 2000 Free Software Foundation, Inc. 51 Franklin Street, Fifth
+Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute
+verbatim copies of this license document, but changing it is not allowed.
+.Pp
+0. PREAMBLE
+.Pp
+The purpose of this License is to make a manual, textbook, or other written
+document "free" in the sense of freedom: to assure everyone the effective
+freedom to copy and redistribute it, with or without modifying it, either
+commercially or noncommercially. Secondarily, this License preserves for the
+author and publisher a way to get credit for their work, while not being considered
+responsible for modifications made by others.
+.Pp
+This License is a kind of "copyleft", which means that derivative works of
+the document must themselves be free in the same sense. It complements the
+GNU General Public License, which is a copyleft license designed for free
+software.
+.Pp
+We have designed this License in order to use it for manuals for free software,
+because free software needs free documentation: a free program should come
+with manuals providing the same freedoms that the software does. But this
+License is not limited to software manuals; it can be used for any textual
+work, regardless of subject matter or whether it is published as a printed
+book. We recommend this License principally for works whose purpose is instruction
+or reference.
+.Pp
+1. APPLICABILITY AND DEFINITIONS
+.Pp
+This License applies to any manual or other work that contains a notice placed
+by the copyright holder saying it can be distributed under the terms of this
+License. The "Document", below, refers to any such manual or work. Any member
+of the public is a licensee, and is addressed as "you".
+.Pp
+A "Modified Version" of the Document means any work containing the Document
+or a portion of it, either copied verbatim, or with modifications and/or translated
+into another language.
+.Pp
+A "Secondary Section" is a named appendix or a front-matter section of the
+Document that deals exclusively with the relationship of the publishers or
+authors of the Document to the Document's overall subject (or to related matters)
+and contains nothing that could fall directly within that overall subject.
+(For example, if the Document is in part a textbook of mathematics, a Secondary
+Section may not explain any mathematics.) The relationship could be a matter
+of historical connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding them.
+.Pp
+The "Invariant Sections" are certain Secondary Sections whose titles are designated,
+as being those of Invariant Sections, in the notice that says that the Document
+is released under this License.
+.Pp
+The "Cover Texts" are certain short passages of text that are listed, as Front-Cover
+Texts or Back-Cover Texts, in the notice that says that the Document is released
+under this License.
+.Pp
+A "Transparent" copy of the Document means a machine-readable copy, represented
+in a format whose specification is available to the general public, whose
+contents can be viewed and edited directly and straightforwardly with generic
+text editors or (for images composed of pixels) generic paint programs or
+(for drawings) some widely available drawing editor, and that is suitable
+for input to text formatters or for automatic translation to a variety of
+formats suitable for input to text formatters. A copy made in an otherwise
+Transparent file format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is not
+"Transparent" is called "Opaque".
+.Pp
+Examples of suitable formats for Transparent copies include plain ASCII without
+markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly
+available DTD, and standard-conforming simple HTML designed for human modification.
+Opaque formats include PostScript, PDF, proprietary formats that can be read
+and edited only by proprietary word processors, SGML or XML for which the
+DTD and/or processing tools are not generally available, and the machine-generated
+HTML produced by some word processors for output purposes only.
+.Pp
+The "Title Page" means, for a printed book, the title page itself, plus such
+following pages as are needed to hold, legibly, the material this License
+requires to appear in the title page. For works in formats which do not have
+any title page as such, "Title Page" means the text near the most prominent
+appearance of the work's title, preceding the beginning of the body of the
+text.
+.Pp
+2. VERBATIM COPYING
+.Pp
+You may copy and distribute the Document in any medium, either commercially
+or noncommercially, provided that this License, the copyright notices, and
+the license notice saying this License applies to the Document are reproduced
+in all copies, and that you add no other conditions whatsoever to those of
+this License. You may not use technical measures to obstruct or control the
+reading or further copying of the copies you make or distribute. However,
+you may accept compensation in exchange for copies. If you distribute a large
+enough number of copies you must also follow the conditions in section 3.
+.Pp
+You may also lend copies, under the same conditions stated above, and you
+may publicly display copies.
+.Pp
+3. COPYING IN QUANTITY
+.Pp
+If you publish printed copies of the Document numbering more than 100, and
+the Document's license notice requires Cover Texts, you must enclose the copies
+in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover
+Texts on the front cover, and Back-Cover Texts on the back cover. Both covers
+must also clearly and legibly identify you as the publisher of these copies.
+The front cover must present the full title with all words of the title equally
+prominent and visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve the title
+of the Document and satisfy these conditions, can be treated as verbatim copying
+in other respects.
+.Pp
+If the required texts for either cover are too voluminous to fit legibly,
+you should put the first ones listed (as many as fit reasonably) on the actual
+cover, and continue the rest onto adjacent pages.
+.Pp
+If you publish or distribute Opaque copies of the Document numbering more
+than 100, you must either include a machine-readable Transparent copy along
+with each Opaque copy, or state in or with each Opaque copy a publicly-accessible
+computer-network location containing a complete Transparent copy of the Document,
+free of added material, which the general network-using public has access
+to download anonymously at no charge using public-standard network protocols.
+If you use the latter option, you must take reasonably prudent steps, when
+you begin distribution of Opaque copies in quantity, to ensure that this Transparent
+copy will remain thus accessible at the stated location until at least one
+year after the last time you distribute an Opaque copy (directly or through
+your agents or retailers) of that edition to the public.
+.Pp
+It is requested, but not required, that you contact the authors of the Document
+well before redistributing any large number of copies, to give them a chance
+to provide you with an updated version of the Document.
+.Pp
+4. MODIFICATIONS
+.Pp
+You may copy and distribute a Modified Version of the Document under the conditions
+of sections 2 and 3 above, provided that you release the Modified Version
+under precisely this License, with the Modified Version filling the role of
+the Document, thus licensing distribution and modification of the Modified
+Version to whoever possesses a copy of it. In addition, you must do these
+things in the Modified Version:
+.Pp
+A. Use in the Title Page (and on the covers, if any) a title distinct from
+that of the Document, and from those of previous versions (which should, if
+there were any, be listed in the History section of the Document). You may
+use the same title as a previous version if the original publisher of that
+version gives permission. B. List on the Title Page, as authors, one or more
+persons or entities responsible for authorship of the modifications in the
+Modified Version, together with at least five of the principal authors of
+the Document (all of its principal authors, if it has less than five). C.
+State on the Title page the name of the publisher of the Modified Version,
+as the publisher. D. Preserve all the copyright notices of the Document. E.
+Add an appropriate copyright notice for your modifications adjacent to the
+other copyright notices. F. Include, immediately after the copyright notices,
+a license notice giving the public permission to use the Modified Version
+under the terms of this License, in the form shown in the Addendum below.
+G. Preserve in that license notice the full lists of Invariant Sections and
+required Cover Texts given in the Document's license notice. H. Include an
+unaltered copy of this License. I. Preserve the section entitled "History",
+and its title, and add to it an item stating at least the title, year, new
+authors, and publisher of the Modified Version as given on the Title Page.
+If there is no section entitled "History" in the Document, create one stating
+the title, year, authors, and publisher of the Document as given on its Title
+Page, then add an item describing the Modified Version as stated in the previous
+sentence. J. Preserve the network location, if any, given in the Document
+for public access to a Transparent copy of the Document, and likewise the
+network locations given in the Document for previous versions it was based
+on. These may be placed in the "History" section. You may omit a network location
+for a work that was published at least four years before the Document itself,
+or if the original publisher of the version it refers to gives permission.
+K. In any section entitled "Acknowledgements" or "Dedications", preserve the
+section's title, and preserve in the section all the substance and tone of
+each of the contributor acknowledgements and/or dedications given therein.
+L. Preserve all the Invariant Sections of the Document, unaltered in their
+text and in their titles. Section numbers or the equivalent are not considered
+part of the section titles. M. Delete any section entitled "Endorsements".
+Such a section may not be included in the Modified Version. N. Do not retitle
+any existing section as "Endorsements" or to conflict in title with any Invariant
+Section.
+.Pp
+If the Modified Version includes new front-matter sections or appendices that
+qualify as Secondary Sections and contain no material copied from the Document,
+you may at your option designate some or all of these sections as invariant.
+To do this, add their titles to the list of Invariant Sections in the Modified
+Version's license notice. These titles must be distinct from any other section
+titles.
+.Pp
+You may add a section entitled "Endorsements", provided it contains nothing
+but endorsements of your Modified Version by various parties--for example,
+statements of peer review or that the text has been approved by an organization
+as the authoritative definition of a standard.
+.Pp
+You may add a passage of up to five words as a Front-Cover Text, and a passage
+of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts
+in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover
+Text may be added by (or through arrangements made by) any one entity. If
+the Document already includes a cover text for the same cover, previously
+added by you or by arrangement made by the same entity you are acting on behalf
+of, you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+.Pp
+The author(s) and publisher(s) of the Document do not by this License give
+permission to use their names for publicity for or to assert or imply endorsement
+of any Modified Version.
+.Pp
+5. COMBINING DOCUMENTS
+.Pp
+You may combine the Document with other documents released under this License,
+under the terms defined in section 4 above for modified versions, provided
+that you include in the combination all of the Invariant Sections of all of
+the original documents, unmodified, and list them all as Invariant Sections
+of your combined work in its license notice.
+.Pp
+The combined work need only contain one copy of this License, and multiple
+identical Invariant Sections may be replaced with a single copy. If there
+are multiple Invariant Sections with the same name but different contents,
+make the title of each such section unique by adding at the end of it, in
+parentheses, the name of the original author or publisher of that section
+if known, or else a unique number. Make the same adjustment to the section
+titles in the list of Invariant Sections in the license notice of the combined
+work.
+.Pp
+In the combination, you must combine any sections entitled "History" in the
+various original documents, forming one section entitled "History"; likewise
+combine any sections entitled "Acknowledgements", and any sections entitled
+"Dedications". You must delete all sections entitled "Endorsements."
+.Pp
+6. COLLECTIONS OF DOCUMENTS
+.Pp
+You may make a collection consisting of the Document and other documents released
+under this License, and replace the individual copies of this License in the
+various documents with a single copy that is included in the collection, provided
+that you follow the rules of this License for verbatim copying of each of
+the documents in all other respects.
+.Pp
+You may extract a single document from such a collection, and distribute it
+individually under this License, provided you insert a copy of this License
+into the extracted document, and follow this License in all other respects
+regarding verbatim copying of that document.
+.Pp
+7. AGGREGATION WITH INDEPENDENT WORKS
+.Pp
+A compilation of the Document or its derivatives with other separate and independent
+documents or works, in or on a volume of a storage or distribution medium,
+does not as a whole count as a Modified Version of the Document, provided
+no compilation copyright is claimed for the compilation. Such a compilation
+is called an "aggregate", and this License does not apply to the other self-contained
+works thus compiled with the Document, on account of their being thus compiled,
+if they are not themselves derivative works of the Document.
+.Pp
+If the Cover Text requirement of section 3 is applicable to these copies of
+the Document, then if the Document is less than one quarter of the entire
+aggregate, the Document's Cover Texts may be placed on covers that surround
+only the Document within the aggregate. Otherwise they must appear on covers
+around the whole aggregate.
+.Pp
+8. TRANSLATION
+.Pp
+Translation is considered a kind of modification, so you may distribute translations
+of the Document under the terms of section 4. Replacing Invariant Sections
+with translations requires special permission from their copyright holders,
+but you may include translations of some or all Invariant Sections in addition
+to the original versions of these Invariant Sections. You may include a translation
+of this License provided that you also include the original English version
+of this License. In case of a disagreement between the translation and the
+original English version of this License, the original English version will
+prevail.
+.Pp
+9. TERMINATION
+.Pp
+You may not copy, modify, sublicense, or distribute the Document except as
+expressly provided for under this License. Any other attempt to copy, modify,
+sublicense or distribute the Document is void, and will automatically terminate
+your rights under this License. However, parties who have received copies,
+or rights, from you under this License will not have their licenses terminated
+so long as such parties remain in full compliance.
+.Pp
+10. FUTURE REVISIONS OF THIS LICENSE
+.Pp
+The Free Software Foundation may publish new, revised versions of the GNU
+Free Documentation License from time to time. Such new versions will be similar
+in spirit to the present version, but may differ in detail to address new
+problems or concerns. See http://www.gnu.org/copyleft/.
+.Pp
+Each version of the License is given a distinguishing version number. If the
+Document specifies that a particular numbered version of this License "or
+any later version" applies to it, you have the option of following the terms
+and conditions either of that specified version or of any later version that
+has been published (not as a draft) by the Free Software Foundation. If the
+Document does not specify a version number of this License, you may choose
+any version ever published (not as a draft) by the Free Software Foundation.
+.Pp
+ADDENDUM: How to use this License for your documents
+.Pp
+To use this License in a document you have written, include a copy of the
+License in the document and put the following copyright and license notices
+just after the title page:
+.Pp
+.Bd -literal -offset indent
+    Copyright (c)  YEAR  YOUR NAME.
+    Permission is granted to copy, distribute and/or modify this document
+    under the terms of the GNU Free Documentation License, Version 1.1
+    or any later version published by the Free Software Foundation;
+    with the Invariant Sections being LIST THEIR TITLES, with the
+    Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+    A copy of the license is included in the section entitled "GNU
+    Free Documentation License".
+.Ed
+.Pp
+If you have no Invariant Sections, write "with no Invariant Sections" instead
+of saying which ones are invariant. If you have no Front-Cover Texts, write
+"no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise
+for Back-Cover Texts.
+.Pp
+If your document contains nontrivial examples of program code, we recommend
+releasing these examples in parallel under your choice of free software license,
+such as the GNU General Public License, to permit their use in free software.
+.Pp