\input texinfo @c -*-Texinfo-*-
-@c Copyright (c) 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
+@c Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 2000
+@c Free Software Foundation, Inc.
@c UPDATE!! On future updates--
@c (1) check for new machine-dep cmdline options in
@c md_parse_option definitions in config/tc-*.c
@set have-stabs
@c ---
@include asconfig.texi
+@include gasver.texi
@c ---
@c common OR combinations of conditions
@ifset AOUT
@set aout-bout
@end ifset
+@ifset ARM/Thumb
+@set ARM
+@end ifset
@ifset BOUT
@set aout-bout
@end ifset
@ifinfo
This file documents the GNU Assembler "@value{AS}".
-Copyright (C) 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
+Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc.
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, with no Front-Cover Texts, and with no
+ Back-Cover Texts. A copy of the license is included in the
+ section entitled "GNU Free Documentation License".
@ignore
Permission is granted to process this file through Tex and print the
(this paragraph not being relevant to the printed manual).
@end ignore
-Permission is granted to copy and distribute modified versions of this manual
-under the conditions for verbatim copying, provided that the entire resulting
-derived work is distributed under the terms of a permission notice identical to
-this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
@end ifinfo
@titlepage
@title Using @value{AS}
-@subtitle The GNU Assembler
+@subtitle The @sc{gnu} Assembler
@ifclear GENERIC
@subtitle for the @value{TARGET} family
@end ifclear
@sp 1
-@subtitle January 1994
+@subtitle Version @value{VERSION}
@sp 1
@sp 13
The Free Software Foundation Inc. thanks The Nice Computer
Company of Australia for loaning Dean Elsner to write the
-first (Vax) version of @code{as} for Project GNU.
+first (Vax) version of @code{as} for Project @sc{gnu}.
The proprietors, management and staff of TNCCA thank FSF for
distracting the boss while they got some work
done.
@tex
{\parskip=0pt
\hfill {\it Using {\tt @value{AS}}}\par
-\hfill Edited by Roland Pesch for Cygnus Support\par
+\hfill Edited by Cygnus Support\par
}
%"boxit" macro for figures:
%Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc.
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, with no Front-Cover Texts, and with no
+ Back-Cover Texts. A copy of the license is included in the
+ section entitled "GNU Free Documentation License".
-Permission is granted to copy and distribute modified versions of this manual
-under the conditions for verbatim copying, provided that the entire resulting
-derived work is distributed under the terms of a permission notice identical to
-this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
@end titlepage
@ifinfo
@node Top
@top Using @value{AS}
-This file is a user guide to the @sc{gnu} assembler @code{@value{AS}}.
+This file is a user guide to the @sc{gnu} assembler @code{@value{AS}} version
+@value{VERSION}.
@ifclear GENERIC
This version of the file describes @code{@value{AS}} configured to generate
code for @value{TARGET} architectures.
@end ifclear
+
+This document is distributed under the terms of the GNU Free
+Documentation License. A copy of the license is included in the
+section entitled "GNU Free Documentation License".
+
@menu
* Overview:: Overview
* Invoking:: Command-Line Options
* Expressions:: Expressions
* Pseudo Ops:: Assembler Directives
* Machine Dependencies:: Machine Dependent Features
+* Reporting Bugs:: Reporting Bugs
* Acknowledgements:: Who Did What
+* GNU Free Documentation License:: GNU Free Documentation License
* Index:: Index
@end menu
@end ifinfo
@c We don't use deffn and friends for the following because they seem
@c to be limited to one line for the header.
@smallexample
-@value{AS} [ -a[dhlns][=file] ] [ -D ] [ -f ] [ --help ]
- [ -I @var{dir} ] [ -J ] [ -K ] [ -L ] [ -o @var{objfile} ]
- [ -R ] [ --statistics ] [ -v ] [ -version ] [ --version ]
- [ -W ] [ -w ] [ -x ] [ -Z ]
+@value{AS} [ -a[cdhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ]
+ [ -f ] [ --gstabs ] [ --gdwarf2 ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ]
+ [ --keep-locals ] [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ]
+ [ -version ] [ --version ] [ -W ] [ --warn ] [ --fatal-warnings ]
+ [ -w ] [ -x ] [ -Z ] [ --target-help ]
@ifset A29K
@c am29k has no machine-dependent assembler options
@end ifset
-@c start-sanitize-arc
@ifset ARC
[ -mbig-endian | -mlittle-endian ]
@end ifset
-@c end-sanitize-arc
+@ifset ARM
+ [ -m[arm]1 | -m[arm]2 | -m[arm]250 | -m[arm]3 | -m[arm]6 | -m[arm]60 |
+ -m[arm]600 | -m[arm]610 | -m[arm]620 | -m[arm]7[t][[d]m[i]][fe] | -m[arm]70 |
+ -m[arm]700 | -m[arm]710[c] | -m[arm]7100 | -m[arm]7500 | -m[arm]8 |
+ -m[arm]810 | -m[arm]9 | -m[arm]920 | -m[arm]920t | -m[arm]9tdmi |
+ -mstrongarm | -mstrongarm110 | -mstrongarm1100 ]
+ [ -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m | -m[arm]v4 | -m[arm]v4t |
+ -m[arm]v5 | -[arm]v5t ]
+ [ -mthumb | -mall ]
+ [ -mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu ]
+ [ -EB | -EL ]
+ [ -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant ]
+ [ -mthumb-interwork ]
+ [ -moabi ]
+ [ -k ]
+@end ifset
+@ifset D10V
+ [ -O ]
+@end ifset
+@ifset D30V
+ [ -O | -n | -N ]
+@end ifset
@ifset H8
@c Hitachi family chips have no machine-dependent assembler options
@end ifset
@ifset HPPA
@c HPPA has no machine-dependent assembler options (yet).
@end ifset
+@ifset PJ
+ [ -mb | -me ]
+@end ifset
@ifset SPARC
- [ -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite | -bump ]
+@c The order here is important. See c-sparc.texi.
+ [ -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
+ -Av8plus | -Av8plusa | -Av9 | -Av9a ]
+ [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ] [ -32 | -64 ]
+@end ifset
+@ifset TIC54X
+ [ -mcpu=54[123589] | -mcpu=54[56]lp ] [ -mfar-mode | -mf ]
+ [ -merrors-to-file <filename> | -me <filename> ]
@end ifset
@ifset Z8000
@c Z8000 has no machine-dependent assembler options
[ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
[ -b ] [ -no-relax ]
@end ifset
+@ifset M32R
+ [ --m32rx | --[no-]warn-explicit-parallel-conflicts | --W[n]p ]
+@end ifset
@ifset M680X0
[ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
@end ifset
+@ifset MCORE
+ [ -jsri2bsr ] [ -sifilter ] [ -relax ]
+ [ -mcpu=[210|340] ]
+@end ifset
+@ifset M68HC11
+ [ -m68hc11 | -m68hc12 ]
+ [ --force-long-branchs ] [ --short-branchs ] [ --strict-direct-mode ]
+ [ --print-insn-syntax ] [ --print-opcodes ] [ --generate-example ]
+@end ifset
@ifset MIPS
[ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ]
- [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ]
+ [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ] [ -mips32 ] [ -no-mips32 ]
[ --trap ] [ --break ]
[ --emulation=@var{name} ]
@end ifset
@end smallexample
@table @code
-@item -a[dhlns]
+@item -a[cdhlmns]
Turn on listings, in any of a variety of ways:
@table @code
+@item -ac
+omit false conditionals
+
@item -ad
omit debugging directives
@item -al
include assembly
+@item -am
+include macro expansions
+
@item -an
omit forms processing
You may combine these options; for example, use @samp{-aln} for assembly
listing without forms processing. The @samp{=file} option, if used, must be
-the last one. By itself, @samp{-a} defaults to @samp{-ahls}---that is, all
-listings turned on.
+the last one. By itself, @samp{-a} defaults to @samp{-ahls}.
@item -D
Ignored. This option is accepted for script compatibility with calls to
other assemblers.
+@item --defsym @var{sym}=@var{value}
+Define the symbol @var{sym} to be @var{value} before assembling the input file.
+@var{value} must be an integer constant. As in C, a leading @samp{0x}
+indicates a hexadecimal value, and a leading @samp{0} indicates an octal value.
+
@item -f
``fast''---skip whitespace and comment preprocessing (assume source is
compiler output).
+@item --gstabs
+Generate stabs debugging information for each assembler line. This
+may help debugging assembler code, if the debugger can handle it.
+
+@item --gdwarf2
+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.
+
@item --help
Print a summary of the command line options and exit.
+@item --target-help
+Print a summary of all target specific options and exit.
+
@item -I @var{dir}
Add directory @var{dir} to the search list for @code{.include} directives.
@end ifset
@item -L
-Keep (in the symbol table) local symbols, starting with @samp{L}.
+@itemx --keep-locals
+Keep (in the symbol table) local symbols. On traditional a.out systems
+these start with @samp{L}, but different systems have different local
+label prefixes.
@item -o @var{objfile}
Name the object-file output from @code{@value{AS}} @var{objfile}.
Print the maximum space (in bytes) and total time (in seconds) used by
assembly.
+@item --strip-local-absolute
+Remove local absolute symbols from the outgoing symbol table.
+
@item -v
@itemx -version
Print the @code{as} version.
Print the @code{as} version and exit.
@item -W
+@itemx --no-warn
Suppress warning messages.
+@item --fatal-warnings
+Treat warnings as errors.
+
+@item --warn
+Don't suppress warning messages or treat them as errors.
+
@item -w
Ignored.
@end table
@end ifset
+@ifset ARM
+The following options are available when @value{AS} is configured for the ARM
+processor family.
+
+@table @code
+@item -m[arm][1|2|3|6|7|8|9][...]
+Specify which ARM processor variant is the target.
+@item -m[arm]v[2|2a|3|3m|4|4t|5|5t]
+Specify which ARM architecture variant is used by the target.
+@item -mthumb | -mall
+Enable or disable Thumb only instruction decoding.
+@item -mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu
+Select which Floating Point architcture is the target.
+@item -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant | -moabi
+Select which procedure calling convention is in use.
+@item -EB | -EL
+Select either big-endian (-EB) or little-endian (-EL) output.
+@item -mthumb-interwork
+Specify that the code has been generated with interworking between Thumb and
+ARM code in mind.
+@item -k
+Specify that PIC code has been generated.
+@end table
+@end ifset
+
+@ifset D10V
+The following options are available when @value{AS} is configured for
+a D10V processor.
+@table @code
+@cindex D10V optimization
+@cindex optimization, D10V
+@item -O
+Optimize output by parallelizing instructions.
+@end table
+@end ifset
+
+@ifset D30V
+The following options are available when @value{AS} is configured for a D30V
+processor.
+@table @code
+@cindex D30V optimization
+@cindex optimization, D30V
+@item -O
+Optimize output by parallelizing instructions.
+
+@cindex D30V nops
+@item -n
+Warn when nops are generated.
+
+@cindex D30V nops after 32-bit multiply
+@item -N
+Warn when a nop after a 32-bit multiply instruction is generated.
+@end table
+@end ifset
+
@ifset I960
The following options are available when @value{AS} is configured for the
Intel 80960 processor.
@end table
@end ifset
+@ifset M32R
+The following options are available when @value{AS} is configured for the
+Mitsubishi M32R series.
+
+@table @code
+
+@item --m32rx
+Specify which processor in the M32R family is the target. The default
+is normally the M32R, but this option changes it to the M32RX.
+
+@item --warn-explicit-parallel-conflicts or --Wp
+Produce warning messages when questionable parallel constructs are
+encountered.
+
+@item --no-warn-explicit-parallel-conflicts or --Wnp
+Do not produce warning messages when questionable parallel constructs are
+encountered.
+
+@end table
+@end ifset
+
@ifset M680X0
The following options are available when @value{AS} is configured for the
Motorola 68000 series.
@item -l
Shorten references to undefined symbols, to one word instead of two.
-@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040
-@itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32
+@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -m68060
+@itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 | -m5200
Specify what processor in the 68000 family is the target. The default
is normally the 68020, but this can be changed at configuration time.
@end table
@end ifset
+@ifset PJ
+The following options are available when @value{AS} is configured for
+a picoJava processor.
+
+@table @code
+
+@cindex PJ endianness
+@cindex endianness, PJ
+@cindex big endian output, PJ
+@item -mb
+Generate ``big endian'' format output.
+
+@cindex little endian output, PJ
+@item -ml
+Generate ``little endian'' format output.
+
+@end table
+@end ifset
+
+@ifset M68HC11
+The following options are available when @value{AS} is configured for the
+Motorola 68HC11 or 68HC12 series.
+
+@table @code
+
+@item -m68hc11 | -m68hc12
+Specify what processor is the target. The default is
+defined by the configuration option when building the assembler.
+
+@item --force-long-branchs
+Relative branches are turned into absolute ones. This concerns
+conditional branches, unconditional branches and branches to a
+sub routine.
+
+@item -S | --short-branchs
+Do not turn relative branchs into absolute ones
+when the offset is out of range.
+
+@item --strict-direct-mode
+Do not turn the direct addressing mode into extended addressing mode
+when the instruction does not support direct addressing mode.
+
+@item --print-insn-syntax
+Print the syntax of instruction in case of error.
+
+@item --print-opcodes
+print the list of instructions with syntax and then exit.
+
+@item --generate-example
+print an example of instruction for each possible instruction and then exit.
+This option is only useful for testing @code{@value{AS}}.
+
+@end table
+@end ifset
+
@ifset SPARC
The following options are available when @code{@value{AS}} is configured
for the SPARC architecture:
@table @code
-@item -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite
+@item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
+@itemx -Av8plus | -Av8plusa | -Av9 | -Av9a
Explicitly select a variant of the SPARC architecture.
+@samp{-Av8plus} and @samp{-Av8plusa} select a 32 bit environment.
+@samp{-Av9} and @samp{-Av9a} select a 64 bit environment.
+
+@samp{-Av8plusa} and @samp{-Av9a} enable the SPARC V9 instruction set with
+UltraSPARC extensions.
+
+@item -xarch=v8plus | -xarch=v8plusa
+For compatibility with the Solaris v9 assembler. These options are
+equivalent to -Av8plus and -Av8plusa, respectively.
+
@item -bump
Warn when the assembler switches to another architecture.
@end table
@end ifset
+@ifset TIC54X
+The following options are available when @value{AS} is configured for the 'c54x
+architecture.
+
+@table @code
+@item -mfar-mode
+Enable extended addressing mode. All addresses and relocations will assume
+extended addressing (usually 23 bits).
+@item -mcpu=@var{CPU_VERSION}
+Sets the CPU version being compiled for.
+@item -merrors-to-file @var{FILENAME}
+Redirect error output to a file, for broken systems which don't support such
+behaviour in the shell.
+@end table
+@end ifset
+
@ifset MIPS
The following options are available when @value{AS} is configured for
a MIPS processor.
processor.
@item -m4650
-@item -no-m4650
+@itemx -no-m4650
Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept
the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
instructions around accesses to the @samp{HI} and @samp{LO} registers.
@samp{-no-m4650} turns off this option.
+@item -mips32
+@itemx -no-mips32
+Generate code for the @sc{MIPS32} architecture. This tells the assembler to
+accept ISA level 2 instructions and MIPS32 extensions including some @sc{r4000}
+instructions.
+
@item -mcpu=@var{CPU}
Generate code for a particular MIPS cpu. This has little effect on the
assembler, but it is passed by @code{@value{GCC}}.
@cindex emulation
@item --emulation=@var{name}
-This option causes @code{@value{AS}} to emulated @code{@value{AS}} configured
+This option causes @code{@value{AS}} to emulate @code{@value{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
@code{@value{AS}} ignores this option. It is accepted for compatibility with
the native tools.
+@need 900
@item --trap
@itemx --no-trap
@itemx --break
@end table
@end ifset
+@ifset MCORE
+The following options are available when @value{AS} is configured for
+an MCore processor.
+
+@table @code
+@item -jsri2bsr
+@itemx -nojsri2bsr
+Enable or disable the JSRI to BSR transformation. By default this is enabled.
+The command line option @samp{-nojsri2bsr} can be used to disable it.
+
+@item -sifilter
+@itemx -nosifilter
+Enable or disable the silicon filter behaviour. By default this is disabled.
+The default can be overidden by the @samp{-sifilter} command line option.
+
+@item -relax
+Alter jump instructions for long displacements.
+
+@item -mcpu=[210|340]
+Select the cpu type on the target hardware. This controls which instructions
+can be assembled.
+
+@item -EB
+Assemble for a big endian target.
+
+@item -EL
+Assemble for a little endian target.
+
+@end table
+@end ifset
+
@menu
* Manual:: Structure of this Manual
-* GNU Assembler:: @value{AS}, the GNU Assembler
+* GNU Assembler:: The GNU Assembler
* Object Formats:: Object File Formats
* Command Line:: Command Line
* Input Files:: Input Files
@end ifset
@end ifclear
-@c I think this is premature---pesch@cygnus.com, 17jan1991
+@c I think this is premature---doc@cygnus.com, 17jan1991
@ignore
Throughout this manual, we assume that you are running @dfn{GNU},
the portable operating system from the @dfn{Free Software
@c directives).
@node GNU Assembler
-@section @value{AS}, the GNU Assembler
+@section The GNU Assembler
@sc{gnu} @code{as} is really a family of assemblers.
@ifclear GENERIC
including object file formats, most assembler directives (often called
@dfn{pseudo-ops}) and assembler syntax.@refill
-@cindex purpose of @sc{gnu} @code{@value{AS}}
+@cindex purpose of @sc{gnu} assembler
@code{@value{AS}} is primarily intended to assemble the output of the
@sc{gnu} C compiler @code{@value{GCC}} for use by the linker
@code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}}
doesn't change the meaning of the source.
@c I added "con" prefix to "catenation" just to prove I can overcome my
-@c APL training... pesch@cygnus.com
+@c APL training... doc@cygnus.com
The source program is a concatenation of the text in all the files, in the
order specified.
to @code{@value{AS}}.
@dfn{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 @code{@value{AS}}
-source is itself synthesized from other files.
-@xref{App-File,,@code{.app-file}}.
+directives; they bear no relation to physical files. Logical file names help
+error messages reflect the original source file, when @code{@value{AS}} source
+is itself synthesized from other files. @code{@value{AS}} understands the
+@samp{#} directives emitted by the @code{@value{GCC}} preprocessor. See also
+@ref{File,,@code{.file}}.
@node Object
@section Output (Object) File
information for the debugger.
@c link above to some info file(s) like the description of a.out.
-@c don't forget to describe GNU info as well as Unix lossage.
+@c don't forget to describe @sc{gnu} info as well as Unix lossage.
@node Errors
@section Error and Warning Messages
@cindex error messsages
@cindex warning messages
-@cindex messages from @code{@value{AS}}
+@cindex messages from assembler
@code{@value{AS}} may write warnings and error messages to the standard error
file (usually your terminal). This should not happen when a compiler
runs @code{@value{AS}} automatically. Warnings report an assumption made so
@noindent
@cindex line numbers, in warnings/errors
(where @b{NNN} is a line number). If a logical file name has been given
-(@pxref{App-File,,@code{.app-file}}) it is used for the filename,
-otherwise the name of the current input file is used. If a logical line
-number was given
+(@pxref{File,,@code{.file}}) it is used for the filename, otherwise the name of
+the current input file is used. If a logical line number was given
@ifset GENERIC
(@pxref{Line,,@code{.line}})
@end ifset
@node Invoking
@chapter Command-Line Options
-@cindex options, all versions of @code{@value{AS}}
+@cindex options, all versions of assembler
This chapter describes command-line options available in @emph{all}
versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific
@ifclear GENERIC
to particular machine architectures.
@end ifset
-If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2), you
-can use the @samp{-Wa} option to pass arguments through to the
-assembler. The assembler arguments must be separated from each other
-(and the @samp{-Wa}) by commas. For example:
+If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2),
+you can use the @samp{-Wa} option to pass arguments through to the assembler.
+The assembler arguments must be separated from each other (and the @samp{-Wa})
+by commas. For example:
@smallexample
gcc -c -g -O -Wa,-alh,-L file.c
@end smallexample
@noindent
-emits a listing to standard output with high-level
-and assembly source.
+This passes two options to the assembler: @samp{-alh} (emit a listing to
+standard output with with high-level and assembly source) and @samp{-L} (retain
+local symbols in the symbol table).
Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
command-line options are automatically passed to the assembler by the compiler.
assembler.)
@menu
-* a:: -a[dhlns] enable listings
+* a:: -a[cdhlns] enable listings
* D:: -D for compatibility
* f:: -f to work faster
* I:: -I for .include search path
* L:: -L to retain local labels
* M:: -M or --mri to assemble in MRI compatibility mode
+* MD:: --MD for dependency tracking
* o:: -o to name the object file
* R:: -R to join data and text sections
* statistics:: --statistics to see statistics about assembly
+* traditional-format:: --traditional-format for compatible output
* v:: -v to announce version
-* W:: -W to suppress warnings
+* W:: -W, --no-warn, --warn, --fatal-warnings to control warnings
* Z:: -Z to make object file even after errors
@end menu
@node a
-@section Enable Listings: @code{-a[dhlns]}
+@section Enable Listings: @code{-a[cdhlns]}
@kindex -a
+@kindex -ac
@kindex -ad
@kindex -ah
@kindex -al
@samp{-g} be used, and that assembly listings (@samp{-al}) be requested
also.
+Use the @samp{-ac} option to omit false conditionals from a listing. Any lines
+which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any
+other conditional), or a true @code{.if} followed by an @code{.else}, will be
+omitted from the listing.
+
Use the @samp{-ad} option to omit debugging directives from the
listing.
@ifset HPPA
On the HPPA local labels begin with @samp{L$}.
@end ifset
-@c start-sanitize-arc
-@ifset ARC
-On the ARC local labels begin with @samp{.L}.
-@end ifset
-@c end-sanitize-arc
@node M
@section Assemble in MRI Compatibility Mode: @code{-M}
@cindex MRI compatibility mode
The @code{-M} or @code{--mri} option selects MRI compatibility mode. This
changes the syntax and pseudo-op handling of @code{@value{AS}} to make it
-compatible with the @code{ASM68K} assembler from Microtec Research. The exact
-nature of the MRI syntax will not be documented here; see the MRI manuals for
-more information. The purpose of this option is to permit assembling existing
-MRI assembler code using @code{@value{AS}}.
+compatible with the @code{ASM68K} or the @code{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 @code{@value{AS}}.
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
@itemize @bullet
@item global symbols in common section
-The MRI assembler supports common sections which are merged by the linker.
+The m68k MRI assembler supports common sections which are merged by the linker.
Other object file formats do not support this. @code{@value{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
@item complex relocations
-The MRI assembler supports relocations against a negated section address, and
+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.
instead be specified using the @code{-e} option to the linker, or in a linker
script.
-@item @code{IDNT} and @code{NAME} pseudo-ops
+@item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops
-The MRI @code{IDNT} and @code{NAME} pseudo-ops assign a module name to the
-output file. This is not supported by other object file formats.
+The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module
+name to the output file. This is not supported by other object file formats.
@item @code{ORG} pseudo-op
-The MRI @code{ORG} pseudo-op begins an absolute section at a given address.
-This differs from the usual @code{@value{AS}} @code{.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
+The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given
+address. This differs from the usual @code{@value{AS}} @code{.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.
@end itemize
@item @code{FEQU} pseudo-op
-The @code{FEQU} pseudo-op is not supported.
+The m68k @code{FEQU} pseudo-op is not supported.
@item @code{NOOBJ} pseudo-op
-The @code{NOOBJ} pseudo-op is not supported.
+The m68k @code{NOOBJ} pseudo-op is not supported.
@item @code{OPT} branch control options
-The @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB},
+The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB},
@code{BRL}, and @code{BRW}---are ignored. @code{@value{AS}} automatically
relaxes all branches, whether forward or backward, to an appropriate size, so
these options serve no purpose.
@item @code{OPT} list control options
-The following @code{OPT} list control options are ignored: @code{C},
+The following m68k @code{OPT} list control options are ignored: @code{C},
@code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M},
@code{MEX}, @code{MC}, @code{MD}, @code{X}.
@item other @code{OPT} options
-The following @code{OPT} options are ignored: @code{NEST}, @code{O},
+The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O},
@code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}.
@item @code{OPT} @code{D} option is default
-The @code{OPT} @code{D} option is the default, unlike the MRI assembler.
+The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler.
@code{OPT NOD} may be used to turn it off.
@item @code{XREF} pseudo-op.
-The @code{XREF} pseudo-op is ignored.
+The m68k @code{XREF} pseudo-op is ignored.
+
+@item @code{.debug} pseudo-op
+
+The i960 @code{.debug} pseudo-op is not supported.
+
+@item @code{.extended} pseudo-op
+
+The i960 @code{.extended} pseudo-op is not supported.
+
+@item @code{.list} pseudo-op.
+
+The various options of the i960 @code{.list} pseudo-op are not supported.
+
+@item @code{.optimize} pseudo-op
+
+The i960 @code{.optimize} pseudo-op is not supported.
+
+@item @code{.output} pseudo-op
+
+The i960 @code{.output} pseudo-op is not supported.
+
+@item @code{.setreal} pseudo-op
+
+The i960 @code{.setreal} pseudo-op is not supported.
@end itemize
+@node MD
+@section Dependency tracking: @code{--MD}
+
+@kindex --MD
+@cindex dependency tracking
+@cindex make rules
+
+@code{@value{AS}} can generate a dependency file for the file it creates. This
+file consists of a single rule suitable for @code{make} describing the
+dependencies of the main source file.
+
+The rule is written to the file named in its argument.
+
+This feature is used in the automatic updating of makefiles.
+
@node o
@section Name the Object File: @code{-o}
(in bytes), and the total execution time taken for the assembly (in @sc{cpu}
seconds).
+@node traditional-format
+@section Compatible output: @code{--traditional-format}
+
+@kindex --traditional-format
+For some targets, the output of @code{@value{AS}} is different in some ways
+from the output of some existing assembler. This switch requests
+@code{@value{AS}} to use the traditional format instead.
+
+For example, it disables the exception frame optimizations which
+@code{@value{AS}} normally does by default on @code{@value{GCC}} output.
+
@node v
@section Announce Version: @code{-v}
@kindex -v
@kindex -version
-@cindex @code{@value{AS}} version
-@cindex version of @code{@value{AS}}
+@cindex assembler version
+@cindex version of assembler
You can find out what version of as is running by including the
option @samp{-v} (which you can also spell as @samp{-version}) on the
command line.
@node W
-@section Suppress Warnings: @code{-W}
+@section Control Warnings: @code{-W}, @code{--warn}, @code{--no-warn}, @code{--fatal-warnings}
-@kindex -W
-@cindex suppressing warnings
-@cindex warnings, suppressing
@code{@value{AS}} should never give a warning or error message when
assembling compiler output. But programs written by people often
cause @code{@value{AS}} to give a warning that a particular assumption was
made. All such warnings are directed to the standard error file.
-If you use this option, no warnings are issued. This option only
-affects the warning messages: it does not change any particular of how
-@code{@value{AS}} assembles your file. Errors, which stop the assembly, are
-still reported.
+
+@kindex @samp{-W}
+@kindex @samp{--no-warn}
+@cindex suppressing warnings
+@cindex warnings, suppressing
+If you use the @code{-W} and @code{--no-warn} options, no warnings are issued.
+This only affects the warning messages: it does not change any particular of
+how @code{@value{AS}} assembles your file. Errors, which stop the assembly,
+are still reported.
+
+@kindex @samp{--fatal-warnings}
+@cindex errors, caused by warnings
+@cindex warnings, causing error
+If you use the @code{--fatal-warnings} option, @code{@value{AS}} considers
+files that generate warnings to be in error.
+
+@kindex @samp{--warn}
+@cindex warnings, switching on
+You can switch these options off again by specifying @code{--warn}, which
+causes warnings to be output as usual.
@node Z
@section Generate Object File in Spite of Errors: @code{-Z}
@cindex line comment character
Anything from the @dfn{line comment} character to the next newline
is considered a comment and is ignored. The line comment character is
-@c start-sanitize-arc
+@ifset A29K
+@samp{;} for the AMD 29K family;
+@end ifset
@ifset ARC
@samp{;} on the ARC;
@end ifset
-@c end-sanitize-arc
-@ifset VAX
-@samp{#} on the Vax;
-@end ifset
-@ifset I960
-@samp{#} on the i960;
-@end ifset
-@ifset SPARC
-@samp{!} on the SPARC;
-@end ifset
-@ifset M680X0
-@samp{|} on the 680x0;
-@end ifset
-@ifset A29K
-@samp{;} for the AMD 29K family;
+@ifset ARM
+@samp{@@} on the ARM;
@end ifset
@ifset H8/300
@samp{;} for the H8/300 family;
@ifset HPPA
@samp{;} for the HPPA;
@end ifset
+@ifset I960
+@samp{#} on the i960;
+@end ifset
+@ifset PJ
+@samp{;} for picoJava;
+@end ifset
@ifset SH
@samp{!} for the Hitachi SH;
@end ifset
+@ifset SPARC
+@samp{!} on the SPARC;
+@end ifset
+@ifset M32R
+@samp{#} on the m32r;
+@end ifset
+@ifset M680X0
+@samp{|} on the 680x0;
+@end ifset
+@ifset M68HC11
+@samp{#} on the 68HC11 and 68HC12;
+@end ifset
+@ifset VAX
+@samp{#} on the Vax;
+@end ifset
@ifset Z8000
@samp{!} for the Z8000;
@end ifset
+@ifset V850
+@samp{#} on the V850;
+@end ifset
see @ref{Machine Dependencies}. @refill
@c FIXME What about i386, m88k, i860?
a line, while the other always begins a comment.
@end ifset
+@ifset V850
+The V850 assembler also supports a double dash as starting a comment that
+extends to the end of the line.
+
+@samp{--};
+@end ifset
+
@kindex #
@cindex lines starting with @code{#}
@cindex logical line numbers
It is an error to end any statement with end-of-file: the last
character of any input file should be a newline.@refill
-@cindex continuing statements
-@cindex multi-line statements
-@cindex statement on multiple lines
-You may write a statement on more than one line if you put a
-backslash (@kbd{\}) immediately in front of any newlines within the
-statement. When @code{@value{AS}} reads a backslashed newline both
-characters are ignored. You can even put backslashed newlines in
-the middle of symbol names without changing the meaning of your
-source program.
-
An empty statement is allowed, and may include whitespace. It is ignored.
@cindex instructions and directives
@cindex directives and instructions
@c "key symbol" is not used elsewhere in the document; seems pedantic to
-@c @defn{} it in that case, as was done previously... pesch@cygnus.com,
+@c @defn{} it in that case, as was done previously... doc@cygnus.com,
@c 13feb91.
A statement begins with zero or more labels, optionally followed by a
key symbol which determines what kind of statement it is. The key
@c @item \a
@c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
@c
-@item \b
@cindex @code{\b} (backspace character)
@cindex backspace (@code{\b})
+@item \b
Mnemonic for backspace; for ASCII this is octal code 010.
@c @item \e
@c Mnemonic for EOText; for ASCII this is octal code 004.
@c
-@item \f
@cindex @code{\f} (formfeed character)
@cindex formfeed (@code{\f})
+@item \f
Mnemonic for FormFeed; for ASCII this is octal code 014.
-@item \n
@cindex @code{\n} (newline character)
@cindex newline (@code{\n})
+@item \n
Mnemonic for newline; for ASCII this is octal code 012.
@c @item \p
@c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
@c
-@item \r
@cindex @code{\r} (carriage return character)
@cindex carriage return (@code{\r})
+@item \r
Mnemonic for carriage-Return; for ASCII this is octal code 015.
@c @item \s
@c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
@c other assemblers.
@c
-@item \t
@cindex @code{\t} (tab)
@cindex tab (@code{\t})
+@item \t
Mnemonic for horizontal Tab; for ASCII this is octal code 011.
@c @item \v
@c @item \x @var{digit} @var{digit} @var{digit}
@c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
@c
-@item \ @var{digit} @var{digit} @var{digit}
@cindex @code{\@var{ddd}} (octal character code)
@cindex octal character code (@code{\@var{ddd}})
+@item \ @var{digit} @var{digit} @var{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, @code{\008} has the value 010, and @code{\009} the value 011.
-@ifset HPPA
-@item \@code{x} @var{hex-digit} @var{hex-digit}
-@cindex @code{\@var{xdd}} (hex character code)
-@cindex hex character code (@code{\@var{xdd}})
-A hex character code. The numeric code is 2 hexadecimal digits. Either
-upper or lower case @code{x} works.
-@end ifset
+@cindex @code{\@var{xd...}} (hex character code)
+@cindex hex character code (@code{\@var{xd...}})
+@item \@code{x} @var{hex-digits...}
+A hex character code. All trailing hex digits are combined. Either upper or
+lower case @code{x} works.
-@item \\
@cindex @code{\\} (@samp{\} character)
@cindex backslash (@code{\\})
+@item \\
Represents one @samp{\} character.
@c @item \'
@c (@xref{Characters,,Character Constants}.) to represent
@c a @samp{'}.
@c
-@item \"
@cindex @code{\"} (doublequote character)
@cindex doublequote (@code{\"})
+@item \"
Represents one @samp{"} character. Needed in strings to represent
this character, because an unescaped @samp{"} would end the string.
and AMD 29K architectures, the letter must be
one of the letters @samp{DFPRSX} (in upper or lower case).
-@c start-sanitize-arc
-On the ARC, the letter one of the letters @samp{DFRS}
+On the ARC, the letter must be one of the letters @samp{DFRS}
(in upper or lower case).
-@c end-sanitize-arc
On the Intel 960 architecture, the letter must be
one of the letters @samp{DFT} (in upper or lower case).
@ifset A29K
One of the letters @samp{DFPRSX} (in upper or lower case).
@end ifset
-@c start-sanitize-arc
@ifset ARC
One of the letters @samp{DFRS} (in upper or lower case).
@end ifset
-@c end-sanitize-arc
@ifset H8
One of the letters @samp{DFPRSX} (in upper or lower case).
@end ifset
-@ifset I960
-One of the letters @samp{DFT} (in upper or lower case).
-@end ifset
@ifset HPPA
The letter @samp{E} (upper case only).
@end ifset
+@ifset I960
+One of the letters @samp{DFT} (in upper or lower case).
+@end ifset
@end ifclear
@item
@menu
* Secs Background:: Background
-* Ld Sections:: @value{LD} Sections
-* As Sections:: @value{AS} Internal Sections
+* Ld Sections:: Linker Sections
+* As Sections:: Assembler Internal Sections
* Sub-Sections:: Sub-Sections
* bss:: bss Section
@end menu
ensure they end on a word (sixteen bit) boundary.
@end ifset
-@cindex standard @code{@value{AS}} sections
+@cindex standard assembler sections
An object file written by @code{@value{AS}} has at least three sections, any
of which may be empty. These are named @dfn{text}, @dfn{data} and
@dfn{bss} sections.
use of @code{@value{AS}} and have no meaning except during assembly.
@node Ld Sections
-@section @value{LD} Sections
+@section Linker Sections
@code{@value{LD}} deals with just four kinds of sections, summarized below.
@table @strong
@c END TEXI2ROFF-KILL
@node As Sections
-@section @value{AS} Internal Sections
+@section Assembler Internal Sections
-@cindex internal @code{@value{AS}} sections
+@cindex internal assembler sections
@cindex sections in messages, internal
These sections are meant only for the internal use of @code{@value{AS}}. They
have no meaning at run-time. You do not really need to know about these
section-relative address.
@table @b
-@item ASSEMBLER-INTERNAL-LOGIC-ERROR!
@cindex assembler internal logic error
+@item ASSEMBLER-INTERNAL-LOGIC-ERROR!
An internal assembler logic error has been found. This means there is a
bug in the assembler.
-@item expr section
@cindex expr (internal section)
+@item 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.
your program starts running, all the contents of the bss
section are zeroed bytes.
-Addresses in the bss section are allocated with special directives; you
-may not assemble anything directly into the bss section. Hence there
-are no bss subsections. @xref{Comm,,@code{.comm}},
-@pxref{Lcomm,,@code{.lcomm}}.
+The @code{.lcomm} pseudo-op defines a symbol in the bss section; see
+@ref{Lcomm,,@code{.lcomm}}.
+
+The @code{.comm} pseudo-op may be used to declare a common symbol, which is
+another form of uninitialized symbol; see @xref{Comm,,@code{.comm}}.
+
+@ifset GENERIC
+When assembling for a target which supports multiple sections, such as ELF or
+COFF, you may switch into the @code{.bss} section and define symbols as usual;
+see @ref{Section,,@code{.section}}. You may only assemble zero values into the
+section. Typically the section will only contain symbol definitions and
+@code{.skip} directives (@pxref{Skip,,@code{.skip}}).
+@end ifset
@node Symbols
@chapter Symbols
If the label is written @samp{1:} then the digit is @samp{1}.
And so on up through @samp{9:}.
-@item @ctrl{A}
+@item @kbd{C-A}
This unusual character is included so you do not accidentally invent
a symbol of the same name. The character has ASCII value
@samp{\001}.
through @samp{9:}.
@end table
-For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
-@code{3:} is named @code{L3@ctrl{A}44}.
+For instance, the first @code{1:} is named @code{L1@kbd{C-A}1}, the 44th
+@code{3:} is named @code{L3@kbd{C-A}44}.
@node Dot
@section The Special Dot Symbol
Lowest Precedence
@table @code
-@item +
@cindex addition, permitted arguments
@cindex plus, permitted arguments
@cindex arguments for addition
+@item +
@dfn{Addition}. If either argument is absolute, the result has the section of
the other argument. You may not add together arguments from different
sections.
-@item -
@cindex subtraction, permitted arguments
@cindex minus, permitted arguments
@cindex arguments for subtraction
+@item -
@dfn{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.
@end ifset
* Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
-* App-File:: @code{.app-file @var{string}}
* Ascii:: @code{.ascii "@var{string}"}@dots{}
* Asciz:: @code{.asciz "@var{string}"}@dots{}
* Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}}
* Double:: @code{.double @var{flonums}}
* Eject:: @code{.eject}
* Else:: @code{.else}
+* Elseif:: @code{.elseif}
+* End:: @code{.end}
@ifset COFF
* Endef:: @code{.endef}
@end ifset
+* Endfunc:: @code{.endfunc}
* Endif:: @code{.endif}
* Equ:: @code{.equ @var{symbol}, @var{expression}}
+* Equiv:: @code{.equiv @var{symbol}, @var{expression}}
+* Err:: @code{.err}
+* Exitm:: @code{.exitm}
* Extern:: @code{.extern}
+* Fail:: @code{.fail}
@ifclear no-file-dir
* File:: @code{.file @var{string}}
@end ifclear
* Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
* Float:: @code{.float @var{flonums}}
+* Func:: @code{.func}
* Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
+@ifset ELF
+* Hidden:: @code{.hidden @var{names}}
+@end ifset
+
* hword:: @code{.hword @var{expressions}}
* Ident:: @code{.ident}
* If:: @code{.if @var{absolute expression}}
* Include:: @code{.include "@var{file}"}
* Int:: @code{.int @var{expressions}}
+@ifset ELF
+* Internal:: @code{.internal @var{names}}
+@end ifset
+
* Irp:: @code{.irp @var{symbol},@var{values}}@dots{}
* Irpc:: @code{.irpc @var{symbol},@var{values}}@dots{}
* Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
@end ifclear
* Ln:: @code{.ln @var{line-number}}
+* Linkonce:: @code{.linkonce [@var{type}]}
* List:: @code{.list}
* Long:: @code{.long @var{expressions}}
@ignore
@end ignore
* Macro:: @code{.macro @var{name} @var{args}}@dots{}
-
+* MRI:: @code{.mri @var{val}}
* Nolist:: @code{.nolist}
* Octa:: @code{.octa @var{bignums}}
* Org:: @code{.org @var{new-lc} , @var{fill}}
* P2align:: @code{.p2align @var{abs-expr} , @var{abs-expr}}
+@ifset ELF
+* PopSection:: @code{.popsection}
+* Previous:: @code{.previous}
+@end ifset
+
+* Print:: @code{.print @var{string}}
+@ifset ELF
+* Protected:: @code{.protected @var{names}}
+@end ifset
+
* Psize:: @code{.psize @var{lines}, @var{columns}}
+* Purgem:: @code{.purgem @var{name}}
+@ifset ELF
+* PushSection:: @code{.pushsection @var{name}}
+@end ifset
+
* Quad:: @code{.quad @var{bignums}}
* Rept:: @code{.rept @var{count}}
* Sbttl:: @code{.sbttl "@var{subheading}"}
@ifset COFF
* Scl:: @code{.scl @var{class}}
-@end ifset
-@ifset COFF
* Section:: @code{.section @var{name}, @var{subsection}}
@end ifset
* Set:: @code{.set @var{symbol}, @var{expression}}
* Short:: @code{.short @var{expressions}}
* Single:: @code{.single @var{flonums}}
-@ifset COFF
-* Size:: @code{.size}
-@end ifset
-
+* Size:: @code{.size [@var{name} , @var{expression}]}
+* Skip:: @code{.skip @var{size} , @var{fill}}
+* Sleb128:: @code{.sleb128 @var{expressions}}
* Space:: @code{.space @var{size} , @var{fill}}
@ifset have-stabs
* Stab:: @code{.stabd, .stabn, .stabs}
@end ifset
* String:: @code{.string "@var{str}"}
+* Struct:: @code{.struct @var{expression}}
+@ifset ELF
+* SubSection:: @code{.subsection}
+* Symver:: @code{.symver @var{name},@var{name2@@nodename}}
+@end ifset
+
@ifset COFF
* Tag:: @code{.tag @var{structname}}
@end ifset
* Text:: @code{.text @var{subsection}}
* Title:: @code{.title "@var{heading}"}
+* Type:: @code{.type <@var{int} | @var{name} , @var{type description}>}
+* Uleb128:: @code{.uleb128 @var{expressions}}
@ifset COFF
-* Type:: @code{.type @var{int}}
* Val:: @code{.val @var{addr}}
@end ifset
+@ifset ELF
+* Version:: @code{.version "@var{string}"}
+* VTableEntry:: @code{.vtable_entry @var{table}, @var{offset}}
+* VTableInherit:: @code{.vtable_inherit @var{child}, @var{parent}}
+* Weak:: @code{.weak @var{names}}
+@end ifset
+
* Word:: @code{.word @var{expressions}}
* Deprecated:: Deprecated Directives
@end menu
@end ifset
@node Align
-@section @code{.align @var{abs-expr} , @var{abs-expr}}
+@section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
@cindex padding the location counter
@cindex @code{align} directive
-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.
-The second expression (also absolute) gives the value to be stored in
-the padding bytes. It (and the comma) may be omitted. If it is
-omitted, the padding bytes are zero.
+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.
+
+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.
+
+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.
The way the required alignment is specified varies from system to system.
-For the a29k, HPPA, m86k, m88k, w65, sparc, and i386 using ELF format,
+For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF
+format,
the first expression is the
alignment request in bytes. For example @samp{.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 other systems, including the i386 using a.out format, it is the
+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 @samp{.align 3} advances the location
counter until it a multiple of 8. If the location counter is already a
described later, which have a consistent behavior across all
architectures (but are specific to GAS).
-@node App-File
-@section @code{.app-file @var{string}}
-
-@cindex logical file name
-@cindex file name, logical
-@cindex @code{app-file} directive
-@code{.app-file}
-@ifclear no-file-dir
-(which may also be spelled @samp{.file})
-@end ifclear
-tells @code{@value{AS}} that we are about to start a new
-logical file. @var{string} is the new file name. In general, the
-filename is recognized whether or not it is surrounded by quotes @samp{"};
-but if you wish to specify an empty file name is permitted,
-you must give the quotes--@code{""}. This statement may go away in
-future: it is only recognized to be compatible with old @code{@value{AS}}
-programs.@refill
-
@node Ascii
@section @code{.ascii "@var{string}"}@dots{}
a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
@node Balign
-@section @code{.balign @var{abs-expr} , @var{abs-expr}}
+@section @code{.balign[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
@cindex padding the location counter given number of bytes
@cindex @code{balign} directive
the location counter until it is a multiple of 8. If the location counter
is already a multiple of 8, no change is needed.
-The second expression (also absolute) gives the value to be stored in
-the padding bytes. It (and the comma) may be omitted. If it is
-omitted, the padding bytes are zero.
+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.
+
+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.
+
+@cindex @code{balignw} directive
+@cindex @code{balignl} directive
+The @code{.balignw} and @code{.balignl} directives are variants of the
+@code{.balign} directive. The @code{.balignw} directive treats the fill
+pattern as a two byte word value. The @code{.balignl} directives treats the
+fill pattern as a four byte longword value. For example, @code{.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.
@node Byte
@section @code{.byte @var{expressions}}
@cindex @code{comm} directive
@cindex symbol, common
-@code{.comm} declares a named common area in the bss section. Normally
-@code{@value{LD}} reserves memory addresses for it during linking, so no partial
-program defines the location of the symbol. Use @code{.comm} to tell
-@code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}}
-allocates space for each @code{.comm} symbol that is at least as
-long as the longest @code{.comm} request in any of the partial programs
-linked. @var{length} is an absolute expression.
+@code{.comm} declares a common symbol named @var{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 @code{@value{LD}} does not see a
+definition for the symbol--just one or more common symbols--then it will
+allocate @var{length} bytes of uninitialized memory. @var{length} must be an
+absolute expression. If @code{@value{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.
+
+@ifset ELF
+When using ELF, the @code{.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 @code{@value{LD}} allocates uninitialized memory
+for the common symbol, it will use the alignment when placing the symbol. If
+no alignment is specified, @code{@value{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.
+@end ifset
@ifset HPPA
The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
of code to be assembled if the condition for the preceding @code{.if}
was false.
-@ignore
-@node End, Endef, Else, Pseudo Ops
+@node Elseif
+@section @code{.elseif}
+
+@cindex @code{elseif} directive
+@code{.elseif} is part of the @code{@value{AS}} support for conditional
+assembly; @pxref{If,,@code{.if}}. It is shorthand for beginning a new
+@code{.if} block that would otherwise fill the entire @code{.else} section.
+
+@node End
@section @code{.end}
@cindex @code{end} directive
-This doesn't do anything---but isn't an s_ignore, so I suspect it's
-meant to do something eventually (which is why it isn't documented here
-as "for compatibility with blah").
-@end ignore
+@code{.end} marks the end of the assembly file. @code{@value{AS}} does not
+process anything in the file past the @code{.end} directive.
@ifset COFF
@node Endef
@end ifset
@end ifset
+@node Endfunc
+@section @code{.endfunc}
+@cindex @code{endfunc} directive
+@code{.endfunc} marks the end of a function specified with @code{.func}.
+
@node Endif
@section @code{.endif}
@samp{@var{symbol} .equ @var{expression}}.
@end ifset
+@node Equiv
+@section @code{.equiv @var{symbol}, @var{expression}}
+@cindex @code{equiv} directive
+The @code{.equiv} directive is like @code{.equ} and @code{.set}, except that
+the assembler will signal an error if @var{symbol} is already defined.
+
+Except for the contents of the error message, this is roughly equivalent to
+@smallexample
+.ifdef SYM
+.err
+.endif
+.equ SYM,VAL
+@end smallexample
+
+@node Err
+@section @code{.err}
+@cindex @code{err} directive
+If @code{@value{AS}} assembles a @code{.err} directive, it will print an error
+message and, unless the @code{-Z} option was used, it will not generate an
+object file. This can be used to signal error an conditionally compiled code.
+
+@node Exitm
+@section @code{.exitm}
+Exit early from the current macro definition. @xref{Macro}.
+
@node Extern
@section @code{.extern}
with other assemblers---but it is ignored. @code{@value{AS}} treats
all undefined symbols as external.
+@node Fail
+@section @code{.fail @var{expression}}
+
+@cindex @code{fail} directive
+Generates an error or a warning. If the value of the @var{expression} is 500
+or more, @code{@value{AS}} will print a warning message. If the value is less
+than 500, @code{@value{AS}} will print an error message. The message will
+include the value of @var{expression}. This can occasionally be useful inside
+complex nested macros or conditional assembly.
+
@ifclear no-file-dir
@node File
@section @code{.file @var{string}}
@cindex @code{file} directive
@cindex logical file name
@cindex file name, logical
-@code{.file} (which may also be spelled @samp{.app-file}) tells
-@code{@value{AS}} that we are about to start a new logical file.
-@var{string} is the new file name. In general, the filename is
-recognized whether or not it is surrounded by quotes @samp{"}; but if
-you wish to specify an empty file name, you must give the
-quotes--@code{""}. This statement may go away in future: it is only
-recognized to be compatible with old @code{@value{AS}} programs.
+@code{.file} tells @code{@value{AS}} that we are about to start a new logical
+file. @var{string} is the new file name. In general, the filename is
+recognized whether or not it is surrounded by quotes @samp{"}; but if you wish
+to specify an empty file name, you must give the quotes--@code{""}. This
+statement may go away in future: it is only recognized to be compatible with
+old @code{@value{AS}} programs.
@ifset A29K
In some configurations of @code{@value{AS}}, @code{.file} has already been
removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}.
@end ifset
@end ifclear
+@node Func
+@section @code{.func @var{name}[,@var{label}]}
+@cindex @code{func} directive
+@code{.func} emits debugging information to denote function @var{name}, and
+is ignored unless the file is assembled with debugging enabled.
+Only @samp{--gstabs} is currently supported.
+@var{label} is the entry point of the function and if omitted @var{name}
+prepended with the @samp{leading char} is used.
+@samp{leading char} is usually @code{_} or nothing, depending on the target.
+All functions are currently defined to have @code{void} return type.
+The function must be terminated with @code{.endfunc}.
+
@node Global
@section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
@xref{HPPA Directives,, HPPA Assembler Directives}.
@end ifset
+@ifset ELF
+@node Hidden
+@section @code{.hidden @var{names}}
+
+@cindex @code{.hidden} directive
+@cindex Visibility
+This one of the ELF visibility directives. The other two are
+@pxref{Internal,,@code{.internal}} and @pxref{Protected,,@code{.protected}}
+
+This directive overrides the named symbols default visibility (which is set by
+their binding: local, global or weak). The directive sets the visibility to
+@code{hidden} which means that the symbols are not visible to other components.
+Such symbols are always considered to be @code{protected} as well.
+@end ifset
+
@node hword
@section @code{.hword @var{expressions}}
(which must be an @var{absolute expression}) is non-zero. The end of
the conditional section of code must be marked by @code{.endif}
(@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
-alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
+alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}).
+If you have several conditions to check, @code{.elseif} may be used to avoid
+nesting blocks if/else within each subsequent @code{.else} block.
The following variants of @code{.if} are also supported:
@table @code
-@item .ifdef @var{symbol}
@cindex @code{ifdef} directive
+@item .ifdef @var{symbol}
Assembles the following section of code if the specified @var{symbol}
has been defined.
-@ignore
-@item .ifeqs
+@cindex @code{ifc} directive
+@item .ifc @var{string1},@var{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.
+
+@cindex @code{ifeq} directive
+@item .ifeq @var{absolute expression}
+Assembles the following section of code if the argument is zero.
+
@cindex @code{ifeqs} directive
-Not yet implemented.
-@end ignore
+@item .ifeqs @var{string1},@var{string2}
+Another form of @code{.ifc}. The strings must be quoted using double quotes.
+
+@cindex @code{ifge} directive
+@item .ifge @var{absolute expression}
+Assembles the following section of code if the argument is greater than or
+equal to zero.
+
+@cindex @code{ifgt} directive
+@item .ifgt @var{absolute expression}
+Assembles the following section of code if the argument is greater than zero.
+
+@cindex @code{ifle} directive
+@item .ifle @var{absolute expression}
+Assembles the following section of code if the argument is less than or equal
+to zero.
+
+@cindex @code{iflt} directive
+@item .iflt @var{absolute expression}
+Assembles the following section of code if the argument is less than zero.
+
+@cindex @code{ifnc} directive
+@item .ifnc @var{string1},@var{string2}.
+Like @code{.ifc}, but the sense of the test is reversed: this assembles the
+following section of code if the two strings are not the same.
-@item .ifndef @var{symbol}
-@itemx ifnotdef @var{symbol}
@cindex @code{ifndef} directive
@cindex @code{ifnotdef} directive
+@item .ifndef @var{symbol}
+@itemx .ifnotdef @var{symbol}
Assembles the following section of code if the specified @var{symbol}
has not been defined. Both spelling variants are equivalent.
-@ignore
-@item ifnes
-Not yet implemented.
-@end ignore
+@cindex @code{ifne} directive
+@item .ifne @var{absolute expression}
+Assembles the following section of code if the argument is not equal to zero
+(in other words, this is equivalent to @code{.if}).
+
+@cindex @code{ifnes} directive
+@item .ifnes @var{string1},@var{string2}
+Like @code{.ifeqs}, but the sense of the test is reversed: this assembles the
+following section of code if the two strings are not the same.
@end table
@node Include
@end ifset
@end ifclear
+@ifset ELF
+@node Internal
+@section @code{.internal @var{names}}
+
+@cindex @code{.internal} directive
+@cindex Visibility
+This one of the ELF visibility directives. The other two are
+@pxref{Hidden,,@code{.hidden}} and @pxref{Protected,,@code{.protected}}
+
+This directive overrides the named symbols default visibility (which is set by
+their binding: local, global or weak). The directive sets the visibility to
+@code{internal} which means that the symbols are considered to be @code{hidden}
+(ie not visible to other components), and that some extra, processor specific
+processing must also be performed upon the symbols as well.
+@end ifset
+
@node Irp
@section @code{.irp @var{symbol},@var{values}}@dots{}
is not declared global (@pxref{Global,,@code{.global}}), so is normally
not visible to @code{@value{LD}}.
+@ifset GENERIC
+Some targets permit a third argument to be used with @code{.lcomm}. This
+argument specifies the desired alignment of the symbol in the bss section.
+@end ifset
+
@ifset HPPA
The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
@samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
debugging.
@end ifclear
+@node Linkonce
+@section @code{.linkonce [@var{type}]}
+@cindex COMDAT
+@cindex @code{linkonce} directive
+@cindex common sections
+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 @code{.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.
+
+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.
+
+The @var{type} argument is optional. If specified, it must be one of the
+following strings. For example:
+@smallexample
+.linkonce same_size
+@end smallexample
+Not all types may be supported on all object file formats.
+
+@table @code
+@item discard
+Silently discard duplicate sections. This is the default.
+
+@item one_only
+Warn if there are duplicate sections, but still keep only one copy.
+
+@item same_size
+Warn if any of the duplicates have different sizes.
+
+@item same_contents
+Warn if any of the duplicates do not have exactly the same contents.
+@end table
+
@node Ln
@section @code{.ln @var{line-number}}
@end ifset
@end ifset
+@node MRI
+@section @code{.mri @var{val}}
+
+@cindex @code{mri} directive
+@cindex MRI mode, temporarily
+If @var{val} is non-zero, this tells @code{@value{AS}} to enter MRI mode. If
+@var{val} is zero, this tells @code{@value{AS}} to exit MRI mode. This change
+affects code assembled until the next @code{.mri} directive, or until the end
+of the file. @xref{M, MRI mode, MRI mode}.
+
@node List
@section @code{.list}
@c double negative used below "not undefined" because this is a specific
@c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
-@c section. pesch@cygnus.com 18feb91
+@c section. doc@cygnus.com 18feb91
Because @code{@value{AS}} tries to assemble programs in one pass, @var{new-lc}
may not be undefined. If you really detest this restriction we eagerly await
a chance to share your improved assembler.
@var{fill} defaults to zero.
@node P2align
-@section @code{.p2align @var{abs-expr} , @var{abs-expr}}
+@section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
@cindex padding the location counter given a power of two
@cindex @code{p2align} directive
counter until it a multiple of 8. If the location counter is already a
multiple of 8, no change is needed.
-The second expression (also absolute) gives the value to be stored in
-the padding bytes. It (and the comma) may be omitted. If it is
-omitted, the padding bytes are zero.
+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.
+
+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.
+
+@cindex @code{p2alignw} directive
+@cindex @code{p2alignl} directive
+The @code{.p2alignw} and @code{.p2alignl} directives are variants of the
+@code{.p2align} directive. The @code{.p2alignw} directive treats the fill
+pattern as a two byte word value. The @code{.p2alignl} directives treats the
+fill pattern as a four byte longword value. For example, @code{.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.
+
+@ifset ELF
+@node Previous
+@section @code{.previous}
+
+@cindex @code{.previous} directive
+@cindex Section Stack
+This is one of the ELF section stack manipulation directives. The others are
+@pxref{Section}, @xref{SubSection}, @pxref{PushSection}, and
+@pxref{PopSection}.
+
+This directive swaps the current section (and subsection) with most recently
+referenced section (and subsection) prior to this one. Multiple
+@code{.previous} directives in a row will flip between two sections (and their
+subsections).
+
+In terms of the section stack, this directive swaps the current section with
+the top section on the section stack.
+@end ifset
+
+@ifset ELF
+@node PopSection
+@section @code{.popsection}
+
+@cindex @code{.popsection} directive
+@cindex Section Stack
+This is one of the ELF section stack manipulation directives. The others are
+@pxref{Section}, @xref{SubSection}, @pxref{PushSection}, and
+@pxref{Previous}.
+
+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.
+@end ifset
+
+@node Print
+@section @code{.print @var{string}}
+
+@cindex @code{print} directive
+@code{@value{AS}} will print @var{string} on the standard output during
+assembly. You must put @var{string} in double quotes.
+
+@ifset ELF
+@node Protected
+@section @code{.protected @var{names}}
+
+@cindex @code{.protected} directive
+@cindex Visibility
+This one of the ELF visibility directives. The other two are
+@pxref{Hidden} and @pxref{Internal}
+
+This directive overrides the named symbols default visibility (which is set by
+their binding: local, global or weak). The directive sets the visibility to
+@code{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.
+@end ifset
@node Psize
@section @code{.psize @var{lines} , @var{columns}}
If you specify @var{lines} as @code{0}, no formfeeds are generated save
those explicitly specified with @code{.eject}.
+@node Purgem
+@section @code{.purgem @var{name}}
+
+@cindex @code{purgem} directive
+Undefine the macro @var{name}, so that later uses of the string will not be
+expanded. @xref{Macro}.
+
+@ifset ELF
+@node PushSection
+@section @code{.pushsection @var{name} , @var{subsection}}
+
+@cindex @code{.pushsection} directive
+@cindex Section Stack
+This is one of the ELF section stack manipulation directives. The others are
+@pxref{Section}, @xref{SubSection}, @pxref{PopSection}, and
+@pxref{Previous}.
+
+This directive is a synonym for @code{.section}. It psuhes the current section
+(and subsection) onto the top of the section stack, and then replaces the
+current section and subsection with @code{name} and @code{subsection}.
+@end ifset
+
@node Quad
@section @code{.quad @var{bignums}}
@end ifset
@end ifset
-@ifset COFF
@node Section
-@section @code{.section @var{name}, @var{subsection}}
+@section @code{.section @var{name}} (COFF version)
@cindex @code{section} directive
-@cindex named section (COFF)
-@cindex COFF named section
-Assemble the following code into end of subsection numbered
-@var{subsection} in the COFF named section @var{name}. If you omit
-@var{subsection}, @code{@value{AS}} uses subsection number zero.
-@samp{.section .text} is equivalent to the @code{.text} directive;
-@samp{.section .data} is equivalent to the @code{.data} directive.
-@ifset GENERIC
+@cindex named section
+Use the @code{.section} directive to assemble the following code into a section
+named @var{name}.
+
This directive is only supported for targets that actually support arbitrarily
named sections; on @code{a.out} targets, for example, it is not accepted, even
-with a standard @code{a.out} section name as its parameter.
-@end ifset
+with a standard @code{a.out} section name.
+
+For COFF targets, the @code{.section} directive is used in one of the following
+ways:
+
+@smallexample
+.section @var{name}[, "@var{flags}"]
+.section @var{name}[, @var{subsegment}]
+@end smallexample
+
+If the optional argument is quoted, it is taken as flags to use for the
+section. Each flag is a single character. The following flags are recognized:
+@table @code
+@item b
+bss section (uninitialized data)
+@item n
+section is not loaded
+@item w
+writable section
+@item d
+data section
+@item r
+read-only section
+@item x
+executable section
+@item s
+shared section (meaningful for PE targets)
+@end table
+
+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 be
+loaded and writable.
+
+If the optional argument to the @code{.section} directive is not quoted, it is
+taken as a subsegment number (@pxref{Sub-Sections}).
+
+
+@section @code{.section @var{name}} (ELF version)
+
+@cindex @code{section} directive
+@cindex named section
+@ifset ELF
+@cindex Section Stack
+This is one of the ELF section stack manipulation directives. The others are
+@xref{SubSection}, @pxref{PushSection}@pxref{PopSection}, and
+@pxref{Previous}.
@end ifset
+For ELF targets, the @code{.section} directive is used like this:
+
+@smallexample
+.section @var{name} [, "@var{flags}"[, @@@var{type}]]
+@end smallexample
+
+The optional @var{flags} argument is a quoted string which may contain any
+combintion of the following characters:
+@table @code
+@item a
+section is allocatable
+@item w
+section is writable
+@item x
+section is executable
+@end table
+
+The optional @var{type} argument may contain one of the following constants:
+@table @code
+@item @@progbits
+section contains data
+@item @@nobits
+section does not contain data (i.e., section only occupies space)
+@end table
+
+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.
+
+For ELF targets, the assembler supports another type of @code{.section}
+directive for compatibility with the Solaris assembler:
+
+@smallexample
+.section "@var{name}"[, @var{flags}...]
+@end smallexample
+
+Note that the section name is quoted. There may be a sequence of comma
+separated flags:
+@table @code
+@item #alloc
+section is allocatable
+@item #write
+section is writable
+@item #execinstr
+section is executable
+@end table
+
+This directive replaces the current section and subsection. The replaced
+section and subsection are pushed onto the section stack. See the contents of
+the gas testsuite directory @code{gas/testsuite/gas/elf} for some examples of
+how this directive and the other section stack directives work.
+
@node Set
@section @code{.set @var{symbol}, @var{expression}}
Set the value of @var{symbol} to @var{expression}. This
changes @var{symbol}'s value and type to conform to
@var{expression}. If @var{symbol} was flagged as external, it remains
-flagged. (@xref{Symbol Attributes}.)
+flagged (@pxref{Symbol Attributes}).
You may @code{.set} a symbol many times in the same assembly.
@end ifset
@end ifclear
-@ifset COFF
@node Size
-@section @code{.size}
+@section @code{.size} (COFF version)
@cindex @code{size} directive
This directive is generated by compilers to include auxiliary debugging
information in the symbol table. It is only permitted inside
@code{.def}/@code{.endef} pairs.
-@ifset BOUT
+@ifset BOUT
@samp{.size} is only meaningful when generating COFF format output; when
@code{@value{AS}} is generating @code{b.out}, it accepts this directive but
ignores it.
@end ifset
-@end ifset
+
+@section @code{.size @var{name} , @var{expression}} (ELF version)
+@cindex @code{size} directive
+
+This directive is used to set the size associated with a symbol @var{name}.
+The size in bytes is computed from @var{expression} which can make use of label
+arithmetic. This directive is typically used to set the size of function
+symbols.
+
+@node Sleb128
+@section @code{.sleb128 @var{expressions}}
+
+@cindex @code{sleb128} directive
+@var{sleb128} stands for ``signed little endian base 128.'' This is a
+compact, variable length representation of numbers used by the DWARF
+symbolic debugging format. @xref{Uleb128,@code{.uleb128}}.
@ifclear no-space-dir
+@node Skip
+@section @code{.skip @var{size} , @var{fill}}
+
+@cindex @code{skip} directive
+@cindex filling memory
+This directive emits @var{size} bytes, each of value @var{fill}. Both
+@var{size} and @var{fill} are absolute expressions. If the comma and
+@var{fill} are omitted, @var{fill} is assumed to be zero. This is the same as
+@samp{.space}.
+
@node Space
@section @code{.space @var{size} , @var{fill}}
@cindex filling memory
This directive emits @var{size} bytes, each of value @var{fill}. Both
@var{size} and @var{fill} are absolute expressions. If the comma
-and @var{fill} are omitted, @var{fill} is assumed to be zero.
+and @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same
+as @samp{.skip}.
@ifset HPPA
@quotation
is the address of the location counter when the @code{.stabd} was
assembled.
-@item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
@cindex @code{stabn} directive
+@item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
The name of the symbol is set to the empty string @code{""}.
-@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
@cindex @code{stabs} directive
+@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
All five fields are specified.
@end table
@end ifset
particular machine, the assembler marks the end of each string with a 0 byte.
You can use any of the escape sequences described in @ref{Strings,,Strings}.
+@node Struct
+@section @code{.struct @var{expression}}
+
+@cindex @code{struct} directive
+Switch to the absolute section, and set the section offset to @var{expression},
+which must be an absolute expression. You might use this as follows:
+@smallexample
+ .struct 0
+field1:
+ .struct field1 + 4
+field2:
+ .struct field2 + 4
+field3:
+@end smallexample
+This would define the symbol @code{field1} to have the value 0, the symbol
+@code{field2} to have the value 4, and the symbol @code{field3} to have the
+value 8. Assembly would be left in the absolute section, and you would need to
+use a @code{.section} directive of some sort to change to some other section
+before further assembly.
+
+@ifset ELF
+@node SubSection
+@section @code{.subsection @var{name}}
+
+@cindex @code{.subsection} directive
+@cindex Section Stack
+This is one of the ELF section stack manipulation directives. The others are
+@pxref{Section}, @xref{PushSection}, @pxref{PopSection}, and
+@pxref{Previous}.
+
+This directive replaces the current subsection with @code{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.
+@end ifset
+
+@ifset ELF
+@node Symver
+@section @code{.symver}
+@cindex @code{symver} directive
+@cindex symbol versioning
+@cindex versions of symbols
+Use the @code{.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.
+
+For ELF targets, the @code{.symver} directive is used like this:
+@smallexample
+.symver @var{name}, @var{name2@@nodename}
+@end smallexample
+If the symbol @var{name} is defined within the file
+being assembled, the @code{.versym} directive effectively creates a symbol
+alias with the name @var{name2@@nodename}, and in fact the main reason that we
+just don't try and create a regular alias is that the @var{@@} character isn't
+permitted in symbol names. The @var{name2} part of the name is the actual name
+of the symbol by which it will be externally referenced. The name @var{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 @var{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 @var{nodename} should correspond to the
+nodename of the symbol you are trying to override.
+
+If the symbol @var{name} is not defined within the file being assembled, all
+references to @var{name} will be changed to @var{name2@@nodename}. If no
+reference to @var{name} is made, @var{name2@@nodename} will be removed from the
+symbol table.
+@end ifset
+
@ifset COFF
@node Tag
@section @code{.tag @var{structname}}
This directive affects subsequent pages, as well as the current page if
it appears within ten lines of the top of a page.
-@ifset COFF
@node Type
-@section @code{.type @var{int}}
+@section @code{.type @var{int}} (COFF version)
@cindex COFF symbol type
@cindex symbol type, COFF
@cindex @code{type} directive
This directive, permitted only within @code{.def}/@code{.endef} pairs,
records the integer @var{int} as the type attribute of a symbol table entry.
-@ifset BOUT
+@ifset BOUT
@samp{.type} is associated only with COFF format output; when
@code{@value{AS}} is configured for @code{b.out} output, it accepts this
directive but ignores it.
@end ifset
-@end ifset
+
+@section @code{.type @var{name} , @var{type description}} (ELF version)
+
+@cindex ELF symbol type
+@cindex symbol type, ELF
+@cindex @code{type} directive
+This directive is used to set the type of symbol @var{name} to be either a
+function symbol or an ojbect symbol. There are five different syntaxes
+supported for the @var{type description} field, in order to provide
+comptability with various other assemblers. The syntaxes supported are:
+
+@smallexample
+ .type <name>,#function
+ .type <name>,#object
+
+ .type <name>,@@function
+ .type <name>,@@object
+
+ .type <name>,%function
+ .type <name>,%object
+
+ .type <name>,"function"
+ .type <name>,"object"
+
+ .type <name> STT_FUNCTION
+ .type <name> STT_OBJECT
+@end smallexample
+
+@node Uleb128
+@section @code{.uleb128 @var{expressions}}
+
+@cindex @code{uleb128} directive
+@var{uleb128} stands for ``unsigned little endian base 128.'' This is a
+compact, variable length representation of numbers used by the DWARF
+symbolic debugging format. @xref{Sleb128,@code{.sleb128}}.
@ifset COFF
@node Val
@end ifset
@end ifset
+@ifset ELF
+@node Version
+@section @code{.version "@var{string}"}
+
+@cindex @code{.version}
+This directive creates a @code{.note} section and places into it an ELF
+formatted note of type NT_VERSION. The note's name is set to @code{string}.
+@end ifset
+
+@ifset ELF
+@node VTableEntry
+@section @code{.vtable_entry @var{table}, @var{offset}}
+
+@cindex @code{.vtable_entry}
+This directive finds or creates a symbol @code{table} and creates a
+@code{VTABLE_ENTRY} relocation for it with an addend of @code{offset}.
+
+@node VTableInherit
+@section @code{.vtable_inherit @var{child}, @var{parent}}
+
+@cindex @code{.vtable_inherit}
+This directive finds the symbol @code{child} and finds or creates the symbol
+@code{parent} and then creates a @code{VTABLE_INHERIT} relocation for the
+parent whoes addend is the value of the child symbol. As a special case the
+parent name of @code{0} is treated as refering the @code{*ABS*} section.
+@end ifset
+
+@ifset ELF
+@node Weak
+@section @code{.weak @var{names}}
+
+@cindex @code{.weak}
+This directive sets the weak attribute on the comma seperated list of symbol
+@code{names}. If the symbols do not already exist, they will be created.
+@end ifset
+
@node Word
@section @code{.word @var{expressions}}
They are included for compatibility with older assemblers.
@table @t
@item .abort
-@item .app-file
@item .line
@end table
subject, see the hardware manufacturer's manual.
@menu
-@c start-sanitize-arc
+@ifset A29K
+* AMD29K-Dependent:: AMD 29K Dependent Features
+@end ifset
@ifset ARC
* ARC-Dependent:: ARC Dependent Features
@end ifset
-@c end-sanitize-arc
-@ifset VAX
-* Vax-Dependent:: VAX Dependent Features
+@ifset ARM
+* ARM-Dependent:: ARM Dependent Features
@end ifset
-@ifset A29K
-* AMD29K-Dependent:: AMD 29K Dependent Features
+@ifset D10V
+* D10V-Dependent:: D10V Dependent Features
+@end ifset
+@ifset D30V
+* D30V-Dependent:: D30V Dependent Features
@end ifset
@ifset H8/300
* H8/300-Dependent:: Hitachi H8/300 Dependent Features
@ifset HPPA
* HPPA-Dependent:: HPPA Dependent Features
@end ifset
-@ifset SH
-* SH-Dependent:: Hitachi SH Dependent Features
+@ifset I370
+* ESA/390-Dependent:: IBM ESA/390 Dependent Features
+@end ifset
+@ifset I80386
+* i386-Dependent:: Intel 80386 Dependent Features
+@end ifset
+@ifset I860
+* i860-Dependent:: Intel 80860 Dependent Features
@end ifset
@ifset I960
* i960-Dependent:: Intel 80960 Dependent Features
@end ifset
+@ifset M32R
+* M32R-Dependent:: M32R Dependent Features
+@end ifset
@ifset M680X0
* M68K-Dependent:: M680x0 Dependent Features
@end ifset
+@ifset M68HC11
+* M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features
+@end ifset
+@ifset MIPS
+* MIPS-Dependent:: MIPS Dependent Features
+@end ifset
+@ifset SH
+* SH-Dependent:: Hitachi SH Dependent Features
+@end ifset
+@ifset PJ
+* PJ-Dependent:: picoJava Dependent Features
+@end ifset
@ifset SPARC
* Sparc-Dependent:: SPARC Dependent Features
@end ifset
+@ifset TIC54X
+* TIC54X-Dependent:: TI TMS320C54x Dependent Features
+@end ifset
+@ifset V850
+* V850-Dependent:: V850 Dependent Features
+@end ifset
@ifset Z8000
* Z8000-Dependent:: Z8000 Dependent Features
@end ifset
-@ifset MIPS
-* MIPS-Dependent:: MIPS Dependent Features
-@end ifset
-@ifset I80386
-* i386-Dependent:: 80386 Dependent Features
+@ifset VAX
+* Vax-Dependent:: VAX Dependent Features
@end ifset
@end menu
@c node and sectioning commands; hence the repetition of @chapter BLAH
@c in both conditional blocks.
-@c start-sanitize-arc
@ifset ARC
@ifset GENERIC
@page
a few additional instructions at each level.
By default, @code{@value{AS}} assumes the core instruction set (ARC
-base). The @code{.cpu} pseudo-op is used to select a different variant.
+base). The @code{.cpu} pseudo-op is intended to be used to select
+the variant.
@table @code
@cindex @code{-mbig-endian} option (ARC)
@table @code
@item .cpu
@cindex @code{cpu} directive, SPARC
-This must be followed by the desired cpu. It must be one of
-@code{base}, @code{host}, @code{graphics}, or @code{audio}.
+This must be followed by the desired cpu.
+The ARC is intended to be customizable, @code{.cpu} is used to
+select the desired variant [though currently there are none].
@end table
-@end ifset
-@c end-sanitize-arc
-
-@ifset VAX
-@include c-vax.texi
@end ifset
@ifset A29K
@include c-a29k.texi
@end ifset
+@ifset ARM
+@include c-arm.texi
+@end ifset
+
@ifset Hitachi-all
@ifclear GENERIC
@node Machine Dependencies
@end ifclear
@end ifset
+@ifset D10V
+@include c-d10v.texi
+@end ifset
+
+@ifset D30V
+@include c-d30v.texi
+@end ifset
+
@ifset H8/300
@include c-h8300.texi
@end ifset
@include c-hppa.texi
@end ifset
-@ifset SH
-@include c-sh.texi
+@ifset I370
+@include c-i370.texi
+@end ifset
+
+@ifset I80386
+@include c-i386.texi
+@end ifset
+
+@ifset I860
+@include c-i860.texi
@end ifset
@ifset I960
@include c-i960.texi
@end ifset
+@ifset M32R
+@include c-m32r.texi
+@end ifset
+
@ifset M680X0
@include c-m68k.texi
@end ifset
-@ignore
-@c FIXME! Stop ignoring when filled in.
-@node 32x32
-@chapter 32x32
-
-@section Options
-The 32x32 version of @code{@value{AS}} accepts a @samp{-m32032} option to
-specify thiat it is compiling for a 32032 processor, or a
-@samp{-m32532} to specify that it is compiling for a 32532 option.
-The default (if neither is specified) is chosen when the assembler
-is compiled.
+@ifset M68HC11
+@include c-m68hc11.texi
+@end ifset
-@section Syntax
-I don't know anything about the 32x32 syntax assembled by
-@code{@value{AS}}. Someone who undersands the processor (I've never seen
-one) and the possible syntaxes should write this section.
+@ifset MIPS
+@include c-mips.texi
+@end ifset
-@section Floating Point
-The 32x32 uses @sc{ieee} floating point numbers, but @code{@value{AS}}
-only creates single or double precision values. I don't know if the
-32x32 understands extended precision numbers.
+@ifset NS32K
+@include c-ns32k.texi
+@end ifset
-@section 32x32 Machine Directives
-The 32x32 has no machine dependent directives.
+@ifset PJ
+@include c-pj.texi
+@end ifset
-@end ignore
+@ifset SH
+@include c-sh.texi
+@end ifset
@ifset SPARC
@include c-sparc.texi
@end ifset
-@ifset I80386
-@include c-i386.texi
+@ifset TIC54X
+@include c-tic54x.texi
@end ifset
@ifset Z8000
@include c-z8k.texi
@end ifset
-@ifset MIPS
-@include c-mips.texi
+@ifset VAX
+@include c-vax.texi
+@end ifset
+
+@ifset V850
+@include c-v850.texi
@end ifset
@ifset GENERIC
@raisesections
@end ifset
+@node Reporting Bugs
+@chapter Reporting Bugs
+@cindex bugs in assembler
+@cindex reporting bugs in assembler
+
+Your bug reports play an essential role in making @code{@value{AS}} reliable.
+
+Reporting a bug may help you by bringing a solution to your problem, or it may
+not. But in any case the principal function of a bug report is to help the
+entire community by making the next version of @code{@value{AS}} work better.
+Bug reports are your contribution to the maintenance of @code{@value{AS}}.
+
+In order for a bug report to serve its purpose, you must include the
+information that enables us to fix the bug.
+
+@menu
+* Bug Criteria:: Have you found a bug?
+* Bug Reporting:: How to report bugs
+@end menu
+
+@node Bug Criteria
+@section Have you found a bug?
+@cindex bug criteria
+
+If you are not sure whether you have found a bug, here are some guidelines:
+
+@itemize @bullet
+@cindex fatal signal
+@cindex assembler crash
+@cindex crash of assembler
+@item
+If the assembler gets a fatal signal, for any input whatever, that is a
+@code{@value{AS}} bug. Reliable assemblers never crash.
+
+@cindex error on valid input
+@item
+If @code{@value{AS}} produces an error message for valid input, that is a bug.
+
+@cindex invalid input
+@item
+If @code{@value{AS}} does not produce an error message for invalid input, that
+is a bug. However, you should note that your idea of ``invalid input'' might
+be our idea of ``an extension'' or ``support for traditional practice''.
+
+@item
+If you are an experienced user of assemblers, your suggestions for improvement
+of @code{@value{AS}} are welcome in any case.
+@end itemize
+
+@node Bug Reporting
+@section How to report bugs
+@cindex bug reports
+@cindex assembler bugs, reporting
+
+A number of companies and individuals offer support for @sc{gnu} products. If
+you obtained @code{@value{AS}} from a support organization, we recommend you
+contact that organization first.
+
+You can find contact information for many support companies and
+individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
+distribution.
+
+In any event, we also recommend that you send bug reports for @code{@value{AS}}
+to @samp{bug-gnu-utils@@gnu.org}.
+
+The fundamental principle of reporting bugs usefully is this:
+@strong{report all the facts}. If you are not sure whether to state a
+fact or leave it out, state it!
+
+Often people omit facts because they think they know what causes the problem
+and assume that some details do not matter. Thus, you might assume that the
+name of a symbol you use in an example does not matter. Well, probably it does
+not, but one cannot be sure. Perhaps the bug is a stray memory reference which
+happens to fetch from the location where that name is stored in memory;
+perhaps, if the name were different, the contents of that location would fool
+the 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.
+
+Keep in mind that the purpose of a bug report is to enable us to fix the bug if
+it is new to us. Therefore, always write your bug reports on the assumption
+that the bug has not been reported previously.
+
+Sometimes people give a few sketchy facts and ask, ``Does this ring a
+bell?'' Those bug reports are useless, and we urge everyone to
+@emph{refuse to respond to them} except to chide the sender to report
+bugs properly.
+
+To enable us to fix the bug, you should include all these things:
+
+@itemize @bullet
+@item
+The version of @code{@value{AS}}. @code{@value{AS}} announces it if you start
+it with the @samp{--version} argument.
+
+Without this, we will not know whether there is any point in looking for
+the bug in the current version of @code{@value{AS}}.
+
+@item
+Any patches you may have applied to the @code{@value{AS}} source.
+
+@item
+The type of machine you are using, and the operating system name and
+version number.
+
+@item
+What compiler (and its version) was used to compile @code{@value{AS}}---e.g.
+``@code{gcc-2.7}''.
+
+@item
+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.
+
+If we were to try to guess the arguments, we would probably guess wrong
+and then we might not encounter the bug.
+
+@item
+A complete input file 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 @samp{-S} option. If you are using @code{@value{GCC}}, use
+the options @samp{-v --save-temps}; this will save the assembler source in a
+file with an extension of @file{.s}, and also show you exactly how
+@code{@value{AS}} is being run.
+
+@item
+A description of what behavior you observe that you believe is
+incorrect. For example, ``It gets a fatal signal.''
+
+Of course, if the bug is that @code{@value{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.
+
+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
+@code{@value{AS}} is out of synch, or you have encountered a bug in the C
+library on your system. (This has happened!) Your copy might crash and ours
+would not. If you told us to expect a crash, then when ours fails to crash, we
+would know that the bug was not happening for us. If you had not told us to
+expect a crash, then we would not be able to draw any conclusion from our
+observations.
+
+@item
+If you wish to suggest changes to the @code{@value{AS}} source, send us context
+diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
+option. Always send diffs from the old file to the new file. If you even
+discuss something in the @code{@value{AS}} source, refer to it by context, not
+by line number.
+
+The line numbers in our development sources will not match those in your
+sources. Your line numbers would convey no useful information to us.
+@end itemize
+
+Here are some things that are not necessary:
+
+@itemize @bullet
+@item
+A description of the envelope of the bug.
+
+Often people who encounter a bug spend a lot of time investigating
+which changes to the input file will make the bug go away and which
+changes will not affect it.
+
+This is often time consuming and not very useful, because the way we
+will find the bug is by running a single example under the debugger
+with breakpoints, not by pure deduction from a series of examples.
+We recommend that you save your time for something else.
+
+Of course, if you can find a simpler example to report @emph{instead}
+of the original one, that is a convenience for us. Errors in the
+output will be easier to spot, running under the debugger will take
+less time, and so on.
+
+However, simplification is not vital; if you do not want to do this,
+report the bug anyway and send us the entire test case you used.
+
+@item
+A patch for the bug.
+
+A patch for the bug does help us if it is a good one. But do not omit
+the necessary information, such as the test case, on the assumption that
+a patch is all we need. We might see problems with your patch and decide
+to fix the problem another way, or we might not understand it at all.
+
+Sometimes with a program as complicated as @code{@value{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.
+
+And if we cannot understand what bug you are trying to fix, or why your
+patch should be an improvement, we will not install it. A test case will
+help us to understand.
+
+@item
+A guess about what the bug is or what it depends on.
+
+Such guesses are usually wrong. Even we cannot guess right about such
+things without first using the debugger to find the facts.
+@end itemize
+
@node Acknowledgements
@chapter Acknowledgements
If you have contributed to @code{@value{AS}} 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 (January 1994), the
-maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
+maintainer, and we'll correct the situation. Currently
+@c (January 1994),
+the maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any
more details?}
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, and made a few other minor
-patches.
+added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and
+PowerPC assembler, and made a few other minor patches.
Steve Chamberlain made @code{@value{AS}} able to generate listings.
Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
and some initial 64-bit support).
+Linas Vepstas added GAS support for the ESA/390 "IBM 370" architecture.
+
+Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD
+support for openVMS/Alpha.
+
+Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic*
+flavors.
+
Several engineers at Cygnus Support have also provided many small bug fixes and
configuration enhancements.
want to be, let us know. Some of the history has been lost; we are not
intentionally leaving anyone out.
+@node GNU Free Documentation License
+@chapter GNU Free Documentation License
+
+ GNU Free Documentation License
+
+ Version 1.1, March 2000
+
+ Copyright (C) 2000 Free Software Foundation, Inc.
+ 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+0. PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document "free" in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+1. APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The "Document", below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as "you".
+
+A "Modified Version" of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A "Secondary Section" is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The "Invariant Sections" are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The "Cover Texts" are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A "Transparent" copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not "Transparent" is called "Opaque".
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML designed for human modification. Opaque formats include
+PostScript, PDF, proprietary formats that can be read and edited only
+by proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML produced by some word processors for output
+purposes only.
+
+The "Title Page" means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+
+2. VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+3. COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+4. MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+A. Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.
+B. List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has less than five).
+C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+D. Preserve all the copyright notices of the Document.
+E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+F. Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.
+G. Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.
+H. Include an unaltered copy of this License.
+I. Preserve the section entitled "History", and its title, and add to
+ it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.
+J. Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.
+K. In any section entitled "Acknowledgements" or "Dedications",
+ preserve the section's title, and preserve in the section all the
+ substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+L. Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+M. Delete any section entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+N. Do not retitle any existing section as "Endorsements"
+ or to conflict in title with any Invariant Section.
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+5. COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled "History"
+in the various original documents, forming one section entitled
+"History"; likewise combine any sections entitled "Acknowledgements",
+and any sections entitled "Dedications". You must delete all sections
+entitled "Endorsements."
+
+
+6. COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+7. AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an "aggregate", and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
+
+8. TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
+
+9. TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+10. FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+ Copyright (c) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+ A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+@end smallexample
+
+If you have no Invariant Sections, write "with no Invariant Sections"
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write "no Front-Cover Texts" instead of
+"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
@node Index
@unnumbered Index