All assembler directives have names that begin with a period (.). The rest of the name is letters, usually in lower case.
The following documentation discusses the directives that are available, regardless of the target machine configuration for the GNU assembler. Some machine configurations provide additional directives. See also Machine Dependent Features.
This directive stops the assembly immediately. It is for compatibility with other assemblers. The original idea was that the assembly language source would be piped into the assembler. If the sender of the source quit, it could use this directive tells as to quit also. One day .abort will not be supported.
.ABORT
When producing COFF output, as accepts this directive as a synonym for .abort.
When
producing b.out
output, as
accepts this directive, but ignores it.
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 in the following. 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
way the required alignment is specified varies from system to system. For
the a29k, hppa, m86k, m88k, w65, sparc, and Hitachi SH, and i386 using
ELF format, the first expression is the alignment request in bytes.
For
example, .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 number
of low-order zero bits the location counter must have after advancement.
For example .align
3 advances the
location counter until it a multiple of 8. If the location counter is already
a multiple of 8, no change is needed.
This
inconsistency is due to the different behaviors of the various native assemblers
for these systems which AS must emulate. AS also provides .balign
and .p2align
directives, described later, which have a consistent behavior across all
architectures (but are specific to AS).
.app-file
(which may also be spelled ‘.file’)
tells as that we are about to start a new logical file. string is the new
file name. In general, the filename is recognized whether or not it is
surrounded by quotes ‘"’; but if you wish to specify an empty file name
is permitted, you must give the quotes–" ". This statement may go
away in future: it is only recognized to be compatible with old as programs.
.ascii
expects zero or more string literals (see Strings) separated by commas.
It assembles each string (with no automatic trailing zero byte) into consecutive
addresses.
.asciz
is just like .ascii,
but each string is followed by a zero byte. The z
in .asciz
stands for zero.
.balign[wl]
abs-expr,
abs-expr
Pad
the location counter (in the current subsection) to a particular storage
boundary. The first expression (which must be absolute) is the alignment
request in bytes. For example .balign
8 advances the
location counter until it is a multiple of 8. If the location counter is
already a multiple of 8, no change is needed.
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
.balignw
and .balignl
directives are variants of the .balign
directive. The .balignw
directive treats the fill pattern as a two byte word value. The .balignl
directives treats the fill pattern as a four byte longword value. For example,
.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.
.byte
expects zero or more expressions, separated by commas. Each expression
is assembled into the next byte.
.comm
declares a named common area in the bss section. Normally ld
reserves memory addresses for it during linking, so no partial program
defines the location of the symbol. Use .comm
to tell ld
that it must be at least length
bytes long. ld
allocates space for each .comm
symbol that is at least as long as the longest .comm
request in any of the partial programs linked. length
is an absolute expression.
The
syntax for .comm
differs slightly on the HPPA. The syntax is symbol.comm,
length; symbol
is optional.
.data
tells as to assemble the following statements onto the end of the data
subsection numbered subsection
(which is an absolute expression). If subsection
is omitted, it defaults to zero.
Begin
defining debugging information for a symbol name;
the definition extends until the .endef
directive is encountered.
This
directive is only observed when as is configured for COFF format output;
when producing b.out,
.def
is recognized, but ignored.
This
directive sets the descriptor of the symbol (see Symbol
Attributes) to the low 16 bits of an absolute
expression.
The
.desc
directive is not available when as
is configured for COFF output; it is only for a.out
or b.out
object format. For the sake of compatibility, as
accepts it, but produces no output, when configured for COFF.
This
directive is generated by compilers to include auxiliary debugging information
in the symbol table. It is only permitted inside .def/.endef
pairs. .dim
is only meaningful when generating COFF format output; when as
is generating b.out,
it accepts this directive but ignores it.
.double
expects zero or more flonums, separated by commas. It assembles floating
point numbers. The exact kind of floating point numbers emitted depends
on how as
is configured. See Machine
Dependent Features for documentation specifically
discussing a particular architecture.
Force
a page break at this point, when generating assembly listings.
.else
is part of the as support for conditional assembly; see .if
absolute expression. It
marks the beginning of a section of code to be assembled if the condition
for the preceding .if
was false.
This
directive flags the end of a symbol definition begun with .def.
.endef
is only meaningful when generating COFF format output; if as
is configured to generate b.out,
it accepts this directive but ignores it.
ffb
.endif
is part of the as support for conditional assembly; it marks the end of
a block of code that is only assembled conditionally. See
.if
absolute expression.
This
directive sets the value of symbol
to expression.
It is synonymous with .set;
see .set
symbol, expression
. The syntax for equ
on the HPPA is symbol.equ
expression.
.extern
is accepted in the source program—for compatibility with other assemblers—but
it is ignored. as
treats all undefined symbols as external.
.file
(which may also be spelled .app-file)
tells as
that we are about to start a new logical file. string
is the new file name. In general, the filename is recognized whether or
not it is surrounded by quotes (");
but if you wish to specify an empty file name, you must give the quotes–
" ".
This statement may go away in future; it is only recognized to be compatible
with old as
programs. In some configurations of as,
.file
has already been removed to avoid conflicts with other assemblers. For
documenta
ffb
tion for a particular machine on this subject of .file,
see Machine
Dependent Features.
result,
size
and value
are absolute expressions. This emits repeat
copies of size
bytes. repeat
may be zero or more. size
may be zero or more, but if it is more than 8, then it is deemed to have
the value 8, compatible with other people’s assemblers. The contents of
each repeat
bytes is taken from an 8-byte number. The highest order 4 bytes are zero.
The lowest order 4 bytes are value
rendered in
the byte-order of an integer on the computer as
is assembling for. Each size
bytes in a repetition is taken from the lowest order size
bytes of this number. Again, this bizarre behavior is compatible with other
people’s assemblers.
size
and value
are optional. If the second comma and value are absent, value
is assumed
zero. If the first comma and following tokens are absent, size
is assumed
to be 1.
.float
assembles zero or more flonums, separated by commas. It has the same effect
as .single.
The exact kind of floating point numbers emitted depends on how as
is configured. For documentation on a particular architectur
ffb
e's floating
point issues, see Machine
Dependent Features.
.global
makes the symbol visible to ld.
If you define symbol
in your partial program, its value is made available to other partial programs
that are linked with it. Otherwise, symbol
takes its attributes from a symbol of the same name from another file linked
into the same program. Both spellings (.globl
and .global)
are accepted, for compatibility with other assemblers.
On
the HPPA, .global
is not always enough to make it accessible to other partial programs. You
may need the HPPA-only .EXPORT
directive as well. See Assembler
Directives for HPPA.
.hword
expects zero or more expressions, and emits a 16 bit number for each.
This
directive is a synonym for .short;
depending on the target architecture, it may also be a synonym for .word.
.ident
is used by some assemblers to place tags in object files. as
simply accepts the directive for source-file compatibility with such assemblers,
but does not actually emit anything for it.
.if
marks the beginning of a section of code which is only considered part
of the source program being assembled if the argument (which must be an
absolute expression) is non-zero. The end of the conditional section of
code must be marked by .endif .ifdef
symbol
.ifndef symbol
.ifnotdef symbol
.include
provides a way to include supporting files at specified points in your
source program. The code from file
is assembled as if it followed the point of the .include; when the end
of the included file is reached, assembly of the original file continues.
You can control the search paths used with the -I
command-line option (see Command-Line
Options). Quotation marks are required
around file.
Expect
zero or more expressions,
of any section, separated by commas. For each expression, emit a number
that, at run time, is the value of that expression. The byte order and
bit size of the number depends on what kind of target the assembly is for.
Evaluate
a sequence of statements assigning different values to symbol.
The sequence of statements starts at the .irp
directive, and is terminated by an .endr
directive. For each value,
symbol
is set to value,
and the sequence of statements is assembled.
If
no value
is listed, the sequence of statements is assembled once, with symbol
set to the
null string. To refer to symbol
within the sequence of statements, use \symbol.
.irp
param,1,2,3
For
example, assembling the previous statement is equivalent to assembling
the following.
move
d1,sp@-
Evaluate
a sequence of statements assigning different values to symbol.
The sequence of statements starts at the .irpc directive, and is terminated
by an .endr directive. For each character in value,
symbol
is set to the character, and the sequence of statements is assembled. If
no value
is listed, the sequence of statements is assembled once, with symbol
set to the null string. To refer to symbol
within the sequence of statements, use \symbol.
.irpc
param,123
For
example, assembling the previous statement is equivalent to assembling
the following.
move
d1,sp@-
.lcomm
Reserve length
(an absolute expression) bytes for a local common denoted by symbol.
The section and value of symbol
are those
of the new local common. The addresses are allocated in the bss section,
so that at run-time the bytes start off zeroed. symbol
is not declared global (see .global
symbol, .globl symbol
), so is normally not visible to ld.
The
syntax for .lcomm
differs slightly on the HPPA. The syntax is symbol.lcomm,
length; symbol
is optional.
as
accepts this directive, for compatibility with other assemblers, but ignores
it.
Change
the logical line number. line-number
must be an absolute expression. The next line has that logical line number.
Therefore any other statements on the current line (after a statement separator
character) are reported as on logical line number line-number-1.
One day as
will no longer support this directive: it is recognized only for compatibility
with existing assembler programs.
Warning:
Even
though this is a directive associated with the a.out
or b.out
object-code formats, as
still recognizes it when producing COFF output, and treats .line
as though it were the COFF .ln
if it is found outside a .def/.endef
pair.
Inside
a .def,
.line
is, instead, one of the directives used by compilers to generate auxiliary
symbol information for debugging.
.ln
is a synonym for .line.
If
val
is non-zero, this tells as to enter MRI mode. If val
is zero, this tells as
to exit MRI mode. This change affects code assembled until the next .mri
directive, or until the end of the file. See Assemble
in MRI Compatibilty Mode: -M
.
Control
(in conjunction with the .nolist
directive) whether or not assembly listings are generated. These two directives
maintain an internal counter (which is zero initially). .list
increments the counter, and .nolist
decrements it. A
ffb
ssembly listings are generated whenever the counter is
greater than zero. By default, listings are disabled. When you enable them
(with the -a
command line option; see Command-Line
Options), the initial value of the listing
counter is one.
.long is
the same as .int,
see .int
expressions
.
The
commands, .macro
and .endm,
allow you to define macros that generate assembly output. For example,
the following definition specifies a macro sum
that puts a sequence of numbers into memory.
.macro
sum
from=0, to=5
With
that definition, SUM
0,5 is equivalent
to the following assembly input.
.long
0
.macro macname
.macro macname macargs...
.macro
comm
.macro
plus1 p, p1
.macro plus1 p p1
.macro reserve_str p1=0 p2
The first argument has a
default value, but not the second.
After the definition is complete,
you can call the macro either as reserve_str
a, b
(with \p1
evaluating to a
and \p2
evaluating to b),
or as reserve_str,
b (with
\p1
evaluating as the default, in this case 0,
and \p2
evaluating to b).
When you call a macro, you
can specify the argument values either by position, or by keyword.
.endm
.exitm
\@
Control
(in conjunction with the .list
directive) whether or not assembly listings are generated. These two directives
maintain an internal counter (which is zero initially). .list
increments the counter, and .nolist
decrements it. Assembly listings are generated whenever the counter is
greater than zero.
.octa
This directive expects zero or more bignums, separated by commas. For each
bignum, it emits a 16-byte integer.
The
term octa comes from contexts in which a word is two bytes;
hence octa-word for 16 bytes.
Advance
the location counter of the current section to new-lc.
new-lc
is either an absolute expression or an expression with the same section
as the current subsection. That is, you can’t use .org
to cross sections: if new-lc
has the wrong section, the .org
directive is ignored. To be compatible with former assemblers, if the section
of new-lc is
absolute, as issues a warning, then pretends the section of new-lc
is the same
as the current subsection.
.org
may only increase the location counter, or leave it unchanged; you cannot
use .org
to move the location counter backwards.
Because
as
tries to assemble programs in one pass, new-lc
may not be undefined. If you really detest this restriction we eagerly
await a chance to share your improved assembler.
Beware
that the origin is relative to the start of the section, not to the start
of the subsection. This is compatible with other people’s assemblers.
When
the location counter (of the current subsection) is advanced, the intervening
bytes are filled with fill
which should be an absolute expression. If the comma and fill
are omitted, fill
defaults to zero.
.p2align[wl]
abs-expr,
abs-expr
.p2align[wl]
Pad the location counter (in the current subsection) to a particular storage
boundary.
The
first expression (which must be absolute) is the number of low-order zero
bits the location counter must have after advancement. For example .p2align
3 advances the
location counter until it a multiple of 8. If the location counter is already
a multiple of 8, no change is needed.
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
.p2alignw
and .p2alignl
directives are variants of the .p2align
directive. The .p2alignw
directive treats the fill pattern as a two byte word value. The .p2alignl
directives treats the fill pattern as a four byte longword value. For example,
.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
ffb
skips 1 or 3 bytes, the fill value
is undefined.
Use
this directive to declare the number of lines—and, optionally, the number
of columns—to use for each page, when generating listings.
If
you do not use .psize,
listings use a default line-count of 60. You may omit the comma and columns
specification; the default width is 200 columns.
as
generates formfeeds whenever the specified number of lines is exceeded
(or whenever you explicitly request one, using .eject).
If
you specify lines
as 0,
no formfeeds are generated save those explicitly specified with .eject.
.quad
expects zero or more bignums, separated by commas. For each bignum, it
emits an 8-byte integer. If the bignum won’t fit in 8 bytes, it prints
a warning message; and just takes the lowest order 8 bytes of the bignum.
The term quad comes from contexts in which a word is two
bytes; hence quad-word for 8 bytes.
Repeat
the sequence of lines between the .rept
directive and the next .endr
directive count
times.
.rept
3
For
example, assembling the previous statement is equivalent to assembling
the following.
.long
0
Use
ffb
subheading
as the title (third line, immediately after the title line) when generating
assembly listings.
This
directive affects subsequent pages, as well as the current page if it appears
within ten lines of the top of a page.
Set
the storage-class value for a symbol. This directive may only be used inside
a .def/.endef
pair. Storage class may flag whether a symbol is static or external, or
it may record further symbolic debugging information.
The
.scl
directive is primarily associated with COFF output; when configured to
generate b.out
output format, as accepts this directive but ignores it.
Assemble
the following code into end of subsection numbered subsection
in the COFF named section name.
If you omit subsection,
as
uses subsection number zero. .section
.text is equivalent
to the .text
directive; .section
.data
is equivalent to the .data
directive. This directive is only supported for targets that actually support
arbitrarily named sections; on a.out
targets, for example, it is not accepted, even with a standard a.out
section name as its parameter.
Set
the value of symbol
to expression.
This changes symbol’s
value and type to conform to expression.
If symbol
was flagged as external, it remains flagged. (See Symbol
Attributes.)
You
may .set
a symbol many times in the same assembly.
If
you .set
a global symbol, the value stored in the object file is the last value
stored into it.
The
syntax for set
on the HPPA is symbol.set
expression.
.short
is normally the same as .word.
See .word
expressions.
In
some configurations, however, .short
and .word
generate numbers of different lengths; for discussion on this subject for
particular architectures, see the documentation for the particular machine
with Machine
Dependent Features.
.single
assembles zero or more flonums, separated by commas. It has the same effect
as .float. The exact kind of floating point numbers emitted depends on
how as
is configured; see the documentation for the particular machine with Machine
Dependent Features.
This
directive is generated by compilers to include auxiliary debugging information
in the symbol table. It is only permitted inside .def/.endef
pairs.
.size
is only meaningful when generating COFF format output; when as
is generating b.out,
it accepts this directive but ignores it.
This
directive emits size
bytes, each of value, fill.
Both size
and fill are
absolute expressions. If the comma and fill
are omitted, fill
is assumed to be zero.
Warning:
On
the AMD 29K, this directive is ignored; it is accepted for compatibility
with other AMD 29K assemblers.
Warning:
There
are three directives that begin .stabs.
All emit symbols (see Symbols),
for use by symbolic debuggers. The symbols are not entered in the as
hash table: they cannot be referenced elsewhere in the source file. Up
to five fields are required, a
ffb
s the following descriptions clarify.
string
type
other
desc
value
If
a warning is detected while reading a .stabd,
.stabn,or
.stabs
statement, the symbol has probably already been created; you get a half-formed
symbol in your object file. This is compatible with earlier assemblers!
.stabd type, other
, desc
The symbol’s value is set
to the location counter, relocatability. When your program is linked, the
value of this symbol is the address of the location counter when the .stabd
was assembled.
.stabn type, other
, desc, value
.stabs string , type,
other , desc, value
Copy
the characters in str
to the object file. You may specify more than one string to copy, separated
by commas. Unless otherwise sp
ffb
ecified for a particular machine, the assembler
marks the end of each string with a 0 byte. You can use any of the escape
sequences described in Strings.
This
directive is generated by compilers to include auxiliary debugging information
in the symbol table. It is only permitted inside .def/.endef
pairs. Tags are used to link structure definitions in the symbol table
with instances of those structures. .tag
is only used when generating COFF format output; when as
is generating b.out,
it accepts this directive but ignores it.
.text
tells as
to assemble the following statements onto the end of the text subsection
numbered subsection,
which is an absolute expression. If subsection
is omitted, subsection number zero is used.
Use
heading
as the title (second line, immediately after the source file name and pagenumber)
when generating assembly listings. .title
affects subsequent pages, as well as the current page if it appears within
ten lines of the top of a page.
This
directive, permitted only within .def/.endef
pairs, records the integer int
as the type attribute of a symbol table entry. .type
is associated only with COFF format output; when as
is configured for b.out
output, it accepts this directive but ignores it.
This
directive, permitted only within .def/.endef
pairs, records the address addr
as the value attribute of a symbol table entry.
.val
is used only for COFF output; when as is configured for b.out,
it accepts this directive but ignores it.
This
directive expects zero or more expressions,
of any section, separated by commas. The size of the number emitted, and
its byte order, depend on what target computer the assembly is for.
Warning:
Special treatment to support compilers
Machines
with a 32-bit address space, but that do less than 32-bit addressing, require
the following special treatment. If the machine of interest to you does
32-bit addressing, you can ignore this issue. Also ignore this issue if
the machine you use doesn’t require it; see the discussion for the particular
machine with Machine
Dependent Features.
In
order to assemble compiler output into something that works, as
occasionally does strange things to .word
directives.
Directives
of the form .word
sym1-sym2 are
often emitted by compilers as part of jump tables. Therefore, when as
assembles a directive of the form .word
sym1-sym2, and
the difference between sym1
and sym2
does not fit in 16 bits, as
creates a secondary jump table, immediately before the next label.
This secondary jump table is preceded by a short-jump to the first byte
after the secondary table. This short-jump prevents the flow of control
from accidentally falling into the new table. Inside the table is a long-jump
to sym2.
The original .word
contains sym1
minus the address of the long-jump to sym2.
If there were several occurrences of .word
sym1-sym2 before
the secondary jump table, all of them are adjusted.
If
there was a .word sym3-sym4,
that also did not fit in sixteen bits, a long-jump to sym4
is included in the secondary jump table, and the .word
directives are adjusted to contain sym3
minus the address of the long-jump to sym4;
and so on, for as many entries in the original jump table as necessary.
One
day these directives won’t work. They are included for compatibility with
older assemblers.
.abort
Assembles the following
section of code if the specified symbol
has been defined.
Assembles the following
section of code if the specified symbol
has not been defined. Both spelling variants are equivalent.
move
d\param,sp@-
.endr
move
d2,sp@-
move
d3,sp@-
move
d\param,sp@-
.endr
move
d2,sp@-
move
d3,sp@-7.32
In the AMD29K configuration
of as, this command is not available; use the synonym .ln
in that context.
.long
\from
.if
\to-\from
sum
"(\from+1)",\to
.endif
endm
.long
1
.long
2
.long
3
.long
4
.long
5
Begin the definition of
a macro called macname.
If your macro definition requires arguments, specify their names after
the macro name, separated by co
ffb
mmas or spaces. You can supply a default
value for any macro argument by following the name with =deflt.
For example, the following are all valid .macro
statements:
Begin the definition of
a macro called comm,
which takes no arguments.
Either statement begins
the definition of a macro called plus1,
which takes two arguments; within the macro definition, write \p
or \p1
to evaluate the arguments.
Begin the definition of
a macro called reserve_
str, with two
arguments.
For example, sum
9,17 is equivalent
to sum to=17, from=9.
Mark the end of a macro
definition.
Exit early from the current
macro definition.
as
maintains a counter of how many macros it has executed in this pseudo-variable;
you can copy that number to your output with \@,
but only within a macro definition.
.long
0
.endr
.long
0
.long
0
.space
has a completely different meaning for HPPA targets; use .block
as a substitute. See HP9000 Series 800 Assembly Language Reference Manual
(HP 92432-90001) for the meaning of the .space
directive. See also Assembler
Directives.
In most versions of the
GNU assembler, the directive .space
has the effect of .block;
see the documentation for the particular machine with Machine
Dependent Features.
This is the symbol’s name.
It may contain any character except \000,
so is more general than ordinary symbol names. Some debuggers used to code
arbitrarily complex structures into symbol names using this field.
An absolute expression.
The symbol’s type is set to the low 8 bits of this expression. Any bit
pattern is permitted, but ld
and debuggers choke on silly bit patterns.
An absolute expression.
The symbol’s “other” attribute is set to the low 8 bits of this expression.
An absolute expression.
The symbol’s descriptor is set to the low 16 bits of this expression.
An absolute expression which
becomes the symbol’s value.
The “name” of the symbol
generated is not even an empty string. It is a null pointer, for compatibility.
Older assemblers used a null pointer so they didn’t waste space in object
files with empty strings.
The name of the symbol is
set to the empty string "".
All five fields are specified.
.app-file
.line
0