The Free Software Foundation Inc. thanks The Nice Computer
Company of Australia for loaning Dean Elsner to write the
first (Vax) version of
as for Project GNU.
The proprietors, management and staff of TNCCA thank FSF for
distracting the boss while they got some work
Copyright (C) 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided 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.
This manual is a user guide to the GNU assembler
This version of the manual describes
configured to generate
code for architectures.
Here is a brief summary of how to invoke
. For details,
see section Command-Line Options.
[ -a[dhlns][=file] ] [ -D ] [ --defsym sym=val ] [ -f ] [ --help ] [ -I dir ] [ -J ] [ -K ] [ -L ] [ -o objfile ] [ -R ] [ --statistics ] [ -v ] [ -version ] [ --version ] [ -W ] [ -w ] [ -x ] [ -Z ] [ -- | files ... ]
asversion and exit.
-- | files ...
This manual is intended to describe what you need to know to use
. We cover the syntax expected in source files, including
notation for symbols, constants, and expressions; the directives that
understands; and of course how to invoke
We also cover special features in the
, including assembler directives.
On the other hand, this manual is not intended as an introduction to programming in assembly language--let alone programming in general! In a similar vein, we make no attempt to introduce the machine architecture; we do not describe the instruction set, standard mnemonics, registers or addressing modes that are standard to a particular architecture.
as is really a family of assemblers.
This manual describes
, a member of that family which is
configured for the architectures.
If you use (or have used) the GNU assembler on one architecture, you
should find a fairly similar environment when you use it on another
architecture. Each version has much in common with the others,
including object file formats, most assembler directives (often called
pseudo-ops) and assembler syntax.
is primarily intended to assemble the output of the
GNU C compiler
for use by the linker
. Nevertheless, we've tried to make
assemble correctly everything that other assemblers for the same
machine would assemble.
Unlike older assemblers,
is designed to assemble a source
program in one pass of the source file. This has a subtle impact on the
.org directive (see section
.org new-lc , fill).
The GNU assembler can be configured to produce several alternative
object file formats. For the most part, this does not affect how you
write assembly language programs; but directives for debugging symbols
are typically different in different file formats. See section Symbol Attributes.
On the ,
is configured to produce
format object files.
After the program name
, the command line may contain
options and file names. Options may appear in any order, and may be
before, after, or between file names. The order of file names is
`--' (two hyphens) by itself names the standard input file
explicitly, as one of the files for
Except for `--' any command line argument that begins with a
hyphen (`-') is an option. Each option changes the behavior of
. No option changes the way another option works. An
option is a `-' followed by one or more letters; the case of
the letter is important. All options are optional.
Some options expect exactly one file name to follow them. The file name may either immediately follow the option's letter (compatible with older assemblers) or it may be the next command argument (GNU standard). These two command lines are equivalent:
-o my-object-file.o mumble.s -omy-object-file.o mumble.s
We use the phrase source program, abbreviated source, to
describe the program input to one run of
. The program may
be in one or more files; how the source is partitioned into files
doesn't change the meaning of the source.
The source program is a concatenation of the text in all the files, in the order specified.
Each time you run
it assembles exactly one source
program. The source program is made up of one or more files.
(The standard input is also a file.)
a command line that has zero or more input file
names. The input files are read (from left file name to right). A
command line argument (in any position) that has no special meaning
is taken to be an input file name.
If you give
no file names it attempts to read one input file
standard input, which is normally your terminal. You
may have to type ctl-D to tell
there is no more program
Use `--' if you need to explicitly name the standard input file in your command line.
If the source is empty,
produces a small, empty object
There are two ways of locating a line in the input file (or files) and either may be used in reporting error messages. One way refers to a line number in a physical file; the other refers to a line number in a "logical" file. See section Error and Warning Messages.
Physical files are those files named in the command line given
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
source is itself synthesized from other files.
Every time you run
it produces an output file, which is
your assembly language program translated into numbers. This file
is the object file. Its default name is
is configured for the Intel 80960.
You can give it another name by using the
-o option. Conventionally,
object file names end with `.o'. The default name is used for historical
reasons: older assemblers were capable of assembling self-contained programs
directly into a runnable program. (For some formats, this isn't currently
possible, but it can be done for the
The object file is meant for input to the linker
. It contains
assembled program code, information to help
the assembled program into a runnable file, and (optionally) symbolic
information for the debugger.
may write warnings and error messages to the standard error
file (usually your terminal). This should not happen when a compiler
automatically. Warnings report an assumption made so
could keep assembling a flawed program; errors report a
grave problem that stops the assembly.
Warning messages have the format
file_name:NNN:Warning Message Text
(where NNN is a line number). If a logical file name has been given
.app-file string) it is used for the filename,
otherwise the name of the current input file is used. If a logical line
number was given
then it is used to calculate the number printed,
otherwise the actual line in the current source file is printed. The
message text is intended to be self explanatory (in the grand Unix
Error messages have the format
file_name:NNN:FATAL:Error Message Text
The file name and line number are derived as for warning messages. The actual message text may be rather less explanatory because many of them aren't supposed to happen.