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 done.

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.

Overview

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 ... ]

-a[dhlns]

Turn on listings, in any of a variety of ways:

-ad

omit debugging directives

-ah

include high-level source

-al

include assembly

-an

omit forms processing

-as

include symbols

=file

set the name of the listing file

You may combine these options; for example, use `-aln' for assembly listing without forms processing. The `=file' option, if used, must be the last one. By itself, `-a' defaults to `-ahls'---that is, all listings turned on.

-D

Ignored. This option is accepted for script compatibility with calls to other assemblers.

--defsym sym=value

Define the symbol sym to be value before assembling the input file. value must be an integer constant. As in C, a leading `0x' indicates a hexadecimal value, and a leading `0' indicates an octal value.

-f

"fast"---skip whitespace and comment preprocessing (assume source is compiler output).

--help

Print a summary of the command line options and exit.

-I dir

Add directory dir to the search list for .include directives.

-J

Don't warn about signed overflow.

-K

This option is accepted but has no effect on the family.

-L

Keep (in the symbol table) local symbols, starting with `L'.

-o objfile

Name the object-file output from objfile.

-R

Fold the data section into the text section.

--statistics

Print the maximum space (in bytes) and total time (in seconds) used by assembly.

-v

-version

Print the as version.

--version

Print the as version and exit.

-W

Suppress warning messages.

-w

Ignored.

-x

Ignored.

-Z

Generate an object file even after errors.

-- | files ...

Standard input, or source files to assemble.

• Manual: Structure of this Manual
• GNU Assembler: , the GNU Assembler
• Object Formats: Object File Formats
• Command Line: Command Line
• Input Files: Input Files
• Object: Output (Object) File
• Errors: Error and Warning Messages

Structure of this Manual

This manual is intended to describe what you need to know to use GNU . 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 configuration of , 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.

, the GNU Assembler

GNU 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).

Object File Formats

The GNU assembler can be configured to produce several alternative object file formats. For the most part, this does not affect how you write assembly language programs; but directives for debugging symbols are typically different in different file formats. See section Symbol Attributes. On the , is configured to produce format object files.

Command Line

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 significant.

`--' (two hyphens) by itself names the standard input file explicitly, as one of the files for to assemble.

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

Input Files

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.)

You give 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 from the standard input, which is normally your terminal. You may have to type ctl-D to tell there is no more program to assemble.

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 file.

Filenames and Line-numbers

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 to .

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. See section .app-file string.

Output (Object) File

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 a.out. b.out when 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 a.out format.)

The object file is meant for input to the linker . It contains assembled program code, information to help integrate the assembled program into a runnable file, and (optionally) symbolic information for the debugger.

Error and Warning Messages

may write warnings and error messages to the standard error file (usually your terminal). This should not happen when a compiler runs automatically. Warnings report an assumption made so that 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 (see section .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 (see section .line line-number) then it is used to calculate the number printed, otherwise the actual line in the current source file is printed. The message text is intended to be self explanatory (in the grand Unix tradition).

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.