nasm - the Netwide Assembler - portable 80x86 assembler
SYNOPSIS
nasm [ -f format ] [ -o outfile ] [ options... ] infile
nasm -h
nasm -r
DESCRIPTION
The nasm command assembles the file infile and directs
output to the file outfile if specified. If outfile is not
specified, nasm will derive a default output file name
from the name of its input file, usually by appending `.o'
or `.obj', or by removing all extensions for a raw binary
file. Failing that, the output file name will be
`nasm.out'.
OPTIONS
-h Causes nasm to exit immediately, after giving a
summary of its invocation options, and listing all
its supported output file formats.
-a Causes nasm to assemble the given input file with
out first applying the macro preprocessor.
-e Causes nasm to preprocess the given input file, and
write the output to stdout (or the specified output
file name), and not actually assemble anything.
-M Causes nasm to output Makefile-style dependencies
to stdout; normal output is suppressed.
-E filename
Causes nasm to redirect error messages to filename.
This option exists to support operating systems on
which stderr is not easily redirected.
-r Causes nasm to exit immediately, after displaying
its version number.
-f format
Specifies the output file format. Formats include
bin, to produce flat-form binary files, and aout
and elf to produce Linux a.out and ELF object
files, respectively.
-o outfile
Specifies a precise name for the output file, over
riding nasm's default means of determining it.
-l listfile
Causes an assembly listing to be directed to the
given file, in which the original source is dis
played on the right hand side (plus the source for
macros) and the generated code is shown in hex on
the left.
-s Causes nasm to send its error messages and/or help
text to stdout instead of stderr.
-w[+-]foo
Causes nasm to enable or disable certain classes of
warning messages, for example -w+orphan-labels or
-w-macro-params to, respectively, enable warnings
about labels alone on lines or disable warnings
about incorrect numbers of parameters in macro
calls.
-I directory
Adds a directory to the search path for include
files. The directory specification must include the
trailing slash, as it will be directly prepended to
the name of the include file.
-i directory
Same as the -I option.
-P file
Specifies a file to be pre-included, before the
main source file starts to be processed.
-p file
Same as the -P option.
-D macro[=value]
Pre-defines a single-line macro.
-d macro[=value]
Same as the -D option.
-U macro
Undefines a single-line macro.
-u macro
Same as the -U option.
SYNTAX
This man page does not fully describe the syntax of nasm's
assembly language, but does give a summary of the differ
ences from other assemblers.
Registers have no leading `%' sign, unlike gas, and float
ing-point stack registers are referred to as st0, st1, and
so on.
Floating-point instructions may use either the single-
thus, one could either write
fadd st0,st1
fadd st1,st0
or one could use the alternative single-operand forms
fadd st1
fadd to st1
Uninitialised storage is reserved using the RESB, RESW,
RESD, RESQ and REST pseudo-opcodes, each taking one param
eter which gives the number of bytes, words, doublewords,
quadwords or ten-byte words to reserve.
Repetition of data items is not done by the DUP keyword as
seen in DOS assemblers, but by the use of the TIMES pre
fix, like this:
message: times 3 db 'abc'
times 64-$+message db 0
which defines the string `abcabcabc', followed by the
right number of zero bytes to make the total length up to
64 bytes.
Symbol references are always understood to be immediate
(i.e. the address of the symbol), unless square brackets
are used, in which case the contents of the memory loca
tion are used. Thus:
mov ax,wordvar
loads AX with the address of the variable `wordvar',
whereas
mov ax,[wordvar]
mov ax,[wordvar+1]
mov ax,[es:wordvar+bx]
all refer to the contents of memory locations. The syn
taxes
mov ax,es:wordvar[bx]
es mov ax,wordvar[1]
are not legal at all, although the use of a segment regis
ter name as an instruction prefix is valid, and can be
used with instructions such as LODSB which can't be over
ridden any other way.
Constants may be expressed numerically in most formats: a
trailing H, Q or B denotes hex, octal or binary
well. Leading zeros are not treated specially at all.
Character constants may be enclosed in single or double
quotes; there is no escape character. The ordering is lit
tle-endian (reversed), so that the character constant
'abcd' denotes 0x64636261 and not 0x61626364.
Local labels begin with a period, and their `locality' is
granted by the assembler prepending the name of the previ
ous non-local symbol. Thus declaring a label `.loop' after
a label `label' has actually defined a symbol called
`label.loop'.
DIRECTIVES
SECTION name or SEGMENT name causes nasm to direct all
following code to the named section. Section names vary
with output file format, although most formats support the
names .text, .data and .bss. (The exception is the obj
format, in which all segments are user-definable.)
ABSOLUTE address causes nasm to position its notional
assembly point at an absolute address: so no code or data
may be generated, but you can use RESB, RESW and RESD to
move the assembly point further on, and you can define
labels. So this directive may be used to define data
structures. When you have finished doing absolute assem
bly, you must issue another SECTION directive to return to
normal assembly.
BITS 16 or BITS 32 switches the default processor mode for
which nasm is generating code: it is equivalent to USE16
or USE32 in DOS assemblers.
EXTERN symbol and GLOBAL symbol import and export symbol
definitions, respectively, from and to other modules. Note
that the GLOBAL directive must appear before the defini
tion of the symbol it refers to.
STRUC strucname and ENDSTRUC, when used to bracket a num
ber of RESB, RESW or similar instructions, define a data
structure. In addition to defining the offsets of the
structure members, the construct also defines a symbol for
the size of the structure, which is simply the structure
name with _size tacked on to the end.
FORMAT-SPECIFIC DIRECTIVES
ORG address is used by the bin flat-form binary output
format, and specifies the address at which the output code
will eventually be loaded.
GROUP grpname seg1 seg2... is used by the obj (Microsoft
16-bit) output format, and defines segment groups. This
format also uses UPPERCASE, which directs that all seg
ment, group and symbol names output to the object file
still case sensitive.
LIBRARY libname is used by the rdf output format, and
causes a dependency record to be written to the output
file which indicates that the program requires a certain
library in order to run.
MACRO PREPROCESSOR
Single-line macros are defined using the %define or %ide
fine commands, in a similar fashion to the C preprocessor.
They can be overloaded with respect to number of parame
ters, although defining a macro with no parameters pre
vents the definition of any macro with the same name tak
ing parameters, and vice versa. %define defines macros
whose names match case-sensitively, whereas %idefine
defines case-insensitive macros.
Multi-line macros are defined using %macro and %imacro
(the distinction is the same as that between %define and
%idefine), whose syntax is as follows:
%macro name minprm[-maxprm][+][.nolist] [defaults]
<some lines of macro expansion text>
%endmacro
Again, these macros may be overloaded. The trailing plus
sign indicates that any parameters after the last one get
subsumed, with their separating commas, into the last
parameter. The defaults part can be used to specify
defaults for unspecified macro parameters after minparam.
%endm is a valid synonym for %endmacro.
To refer to the macro parameters within a macro expansion,
you use %1, %2 and so on. You can also enforce that a
macro parameter should contain a condition code by using
%+1, and you can invert the condition code by using %-1.
You can also define a label specific to a macro invocation
by prefixing it with a double % sign.
Files can be included using the %include directive, which
works like C.
The preprocessor has a `context stack', which may be used
by one macro to store information that a later one will
retrieve. You can push a context on the stack using %push,
remove one using %pop, and change the name of the top con
text (without disturbing any associated definitions) using
%repl. Labels and %define macros specific to the top con
text may be defined by prefixing their names with %$, and
things specific to the next context down with %$$, and so
on.
Conditional assembly is done by means of %ifdef, %ifndef,
several putative macro names, and will evaluate TRUE if
any of them is defined.) In addition, the directives
%ifctx and %ifnctx can be used to condition on the name of
the top context on the context stack. The obvious set of
`else-if' directives, %elifdef, %elifndef, %elifctx and
%elifnctx are also supported.
BUGS
There is a reported seg-fault on some (Linux) systems with
some large source files. This appears to be very hard to
reproduce. All other known bugs have been fixed...
RESTRICTIONS
There is no support for listing files, symbol maps, or
debugging object-file records. The advanced features of
the ELF and Win32 object file formats are not supported,
and there is no means for warning the programmer against
using an instruction beyond the capability of the target
processor.
SEE ALSO
as(1), ld(1).
Man(1) output converted with
man2html