Go to the next section.

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

Here is a brief summary of how to invoke as. For details, see section Command-Line Options. 

as [ -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 ]
 [ -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite | -bump ]
 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
 [ -b ] [ -no-relax ]
 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
 [ -nocpp ] [ -EL ] [ -EB ] [ -G num ] [ -mcpu=CPU ]
 [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ]
 [ --trap ] [ --break ]
 [ --emulation=name ]
 [ -- | 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 Issue warnings when difference tables altered for long displacements.

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

  • -o objfile Name the object-file output from as 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.

    • The following options are available when as is configured for the Intel 80960 processor.

    -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
    Specify which variant of the 960 architecture is the target.

    -b
    Add code to collect statistics about branches taken.

    -no-relax
    Do not alter compare-and-branch instructions for long displacements; error if necessary.

    The following options are available when as is configured for the Motorola 68000 series.

    -l
    Shorten references to undefined symbols, to one word instead of two.

    -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040
    | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32
    Specify what processor in the 68000 family is the target. The default is normally the 68020, but this can be changed at configuration time.

    -m68881 | -m68882 | -mno-68881 | -mno-68882
    The target machine does (or does not) have a floating-point coprocessor. The default is to assume a coprocessor for 68020, 68030, and cpu32. Although the basic 68000 is not compatible with the 68881, a combination of the two can be specified, since it's possible to do emulation of the coprocessor instructions with the main processor.

    -m68851 | -mno-68851
    The target machine does (or does not) have a memory-management unit coprocessor. The default is to assume an MMU for 68020 and up.

    The following options are available when as is configured for the SPARC architecture:

    -Av6 | -Av7 | -Av8 | -Av9 | -Asparclite
    Explicitly select a variant of the SPARC architecture.

    -bump
    Warn when the assembler switches to another architecture.

    The following options are available when as is configured for a MIPS processor.

    -G num
    This option sets the largest size of an object that can be referenced implicitly with the gp register. It is only accepted for targets that use ECOFF format, such as a DECstation running Ultrix. The default value is 8.

    -EB
    Generate "big endian" format output.

    -EL
    Generate "little endian" format output.

    -mips1
    -mips2
    -mips3
    Generate code for a particular MIPS Instruction Set Architecture level. `-mips1' corresponds to the R2000 and R3000 processors, `-mips2' to the R6000 processor, and `-mips3' to the R4000 processor.

    -m4650
    -no-m4650
    Generate code for the MIPS R4650 chip. This tells the assembler to accept the `mad' and `madu' instruction, and to not schedule `nop' instructions around accesses to the `HI' and `LO' registers. `-no-m4650' turns off this option.

    -mcpu=CPU
    Generate code for a particular MIPS cpu. This has little effect on the assembler, but it is passed by gcc.

    --emulation=name
    This option causes as to emulated as configured for some other target, in all respects, including output format (choosing between ELF and ECOFF only), handling of pseudo-opcodes which may generate debugging information or store symbol table information, and default endianness. The available configuration names are: `mipsecoff', `mipself', `mipslecoff', `mipsbecoff', `mipslelf', `mipsbelf'. The first two do not alter the default endianness from that of the primary target for which the assembler was configured; the others change the default to little- or big-endian as indicated by the `b' or `l' in the name. Using `-EB' or `-EL' will override the endianness selection in any case.

    This option is currently supported only when the primary target as is configured for is a MIPS ELF or ECOFF target. Furthermore, the primary target or others specified with `--enable-targets=...' at configuration time must include support for the other format, if both are to be available. For example, the Irix 5 configuration includes support for both.

    Eventually, this option will support more configurations, with more fine-grained control over the assembler's behavior, and will be supported for more processors.

    -nocpp
    as ignores this option. It is accepted for compatibility with the native tools.

    --trap
    --no-trap
    --break
    --no-break
    Control how to deal with multiplication overflow and division by zero. `--trap' or `--no-break' (which are synonyms) take a trap exception (and only work for Instruction Set Architecture level 2 and higher); `--break' or `--no-trap' (also synonyms, and the default) take a break exception.

    Structure of this Manual

    This manual is intended to describe what you need to know to use GNU as. We cover the syntax expected in source files, including notation for symbols, constants, and expressions; the directives that as understands; and of course how to invoke as.

    This manual also describes some of the machine-dependent features of various flavors of the assembler.

    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. You may want to consult the manufacturer's machine architecture manual for this information.

    as, the GNU Assembler

    GNU as is really a family of assemblers. 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.

    as is primarily intended to assemble the output of the GNU C compiler gcc for use by the linker ld. Nevertheless, we've tried to make as assemble correctly everything that other assemblers for the same machine would assemble. Any exceptions are documented explicitly (see section Machine Dependent Features). This doesn't mean as always uses the same syntax as another assembler for the same architecture; for example, we know of several incompatible versions of 680x0 assembly language syntax.

    Unlike older assemblers, as 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 machine specific, as can be configured to produce either a.out or COFF format object files. On the machine specific, as can be configured to produce either b.out or COFF format object files. On the machine specific, as can be configured to produce either SOM or ELF format object files.

    Command Line

    After the program name as, the command line may contain options and file names. Options may appear in any order, and may be before, after, or between file names. The order of file names is significant.

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

    Except for `--' any command line argument that begins with a hyphen (`-') is an option. Each option changes the behavior of as. 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: 

    as -o my-object-file.o mumble.s
as -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 as. The program may be in one or more files; how the source is partitioned into files doesn't change the meaning of the source.

    The source program is a concatenation of the text in all the files, in the order specified.

    Each time you run as it assembles exactly one source program. The source program is made up of one or more files. (The standard input is also a file.)

    You give as a command line that has zero or more input file names. The input files are read (from left file name to right). A command line argument (in any position) that has no special meaning is taken to be an input file name.

    If you give as no file names it attempts to read one input file from the as standard input, which is normally your terminal. You may have to type ctl-D to tell as 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, as 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 as.

    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 as source is itself synthesized from other files. See section .app-file string.

    Output (Object) File

    Every time you run as it produces an output file, which is your assembly language program translated into numbers. This file is the object file. Its default name is a.out, or b.out when as 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 ld. It contains assembled program code, information to help ld integrate the assembled program into a runnable file, and (optionally) symbolic information for the debugger.

    Error and Warning Messages

    as may write warnings and error messages to the standard error file (usually your terminal). This should not happen when a compiler runs as automatically. Warnings report an assumption made so that as 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) (see section .ln 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.

    Go to the next section.