nasm/nasm.1

.TH NASM 1 "The Netwide Assembler Project"
.SH NAME
nasm \- the Netwide Assembler, a portable 80x86 assembler
.SH SYNOPSIS
.B nasm
[
.B \-@
response file
] [
.B \-f
format
] [
.B \-o
outfile
] [
.B \-l
listfile
] [
.IR options ...
] filename
.br
.B nasm \-h
.br
.B nasm \-v
.SH DESCRIPTION
The
.B nasm
command assembles the file
.I filename
and directs output to the file
.I outfile
if specified. If
.I outfile
is not specified,
.B 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'.
.SS OPTIONS
.TP
.BI \-@ " filename"
Causes
.B nasm
to process options from 
.I filename
as if they were included on the command line.
.TP
.B \-a
Causes
.B nasm
to assemble the given input file without first applying the macro
preprocessor.
.TP
.BI \-D " macro[=value]"
Pre-defines a single-line macro.
.TP
.BI \-d " macro[=value]"
Same as the
.B \-D
option.
.TP
.B \-e
Causes
.B nasm
to preprocess the given input file, and write the output to
.I stdout
(or the specified output file name), and not actually assemble
anything.
.TP
.BI \-f " format"
Specifies the output file format. To see a list of valid output
formats, use the
.B -hf
option.
.TP
.B \-g
Causes
.B nasm
to generate debug information in selected format
.TP
.B \-h
Causes
.B nasm
to exit immediately, after giving a summary of its invocation
options.
.TP
.B \-hf
Same as
.B -h
, but also lists all valid output formats.
.TP
.BI \-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.
.TP
.BI \-i " directory"
Same as the
.B \-I
option.
.TP
.BI \-l " listfile"
Causes an assembly listing to be directed to the given file, in
which the original source is displayed on the right hand side (plus
the source for included files and the expansions of multi-line
macros) and the generated code is shown in hex on the left.
.TP
.B \-M
Causes
.B nasm
to output Makefile-style dependencies to stdout; normal output is
suppressed.
.TP
.BI \-MG " file"
Same as
.B \-M
but assumes that missing Makefile dependecies are generated and added
to dependency list without a prefix.
.TP
.BI \-MF " file"
Output Makefile-style dependencies to the specified file.
.TP
.BI \-MD " file"
Same as a combination of
.B \-M
and
.B \-MF
options.
.TP
.BI \-MT " file"
Override the default name of the dependency target
dependency target name. This is normally the same
as the output filename, specified by the
.B \-o
option.
.TP
.BI \-MQ " file"
The same as
.B \-MT
except it tries to quote characters that have special
meaning in Makefile syntax. This is not foolproof,
as not all characters with special meaning are quotable
in Make.
.TP
.BI \-MP
Emit phony target
.TP
.BI \-O " number"
Optimize branch offsets.
.ti
.B \-O0
:No optimization (default)
.ti
.B \-O1
:Minimal optimization
.ti
.B \-Ox
:Multipass optimization (recommended)
.TP
.BI \-o " outfile"
Specifies a precise name for the output file, overriding
.BR nasm 's
default means of determining it.
.TP
.BI \-P " file"
Specifies a file to be pre-included, before the main source file
starts to be processed.
.TP
.BI \-p " file"
Same as the
.B \-P
option.
.TP
.BI \-r
Causes
.B nasm
to exit immediately, after displaying its version number.
.I (obsolete)
.TP
.B \-s
Causes
.B nasm
to send its error messages and/or help text to
.I stdout
instead of
.IR stderr .
.TP
.B \-t
Causes
.B nasm
to assemble in SciTech TASM compatible mode
.TP
.BI \-U " macro"
Undefines a single-line macro.
.TP
.BI \-u " macro"
Same as the
.B \-U
option.
.TP
.BI \-v
Causes
.B nasm
to exit immediately, after displaying its version number.
.TP
.BI \-w [+-]foo
Causes
.B nasm
to enable or disable certain classes of warning messages, for
example
.B \-w+orphan-labels
or
.B \-w-macro-params
.TP
.BI \-X " format"
specifies error reporting format (gnu or vc).
.TP
.BI \-Z " filename"
Causes
.B nasm
to redirect error messages to
.IR filename .
This option exists to support operating systems on which stderr is not
easily redirected.
.TP
.BI \-\-prefix
.TP
.BI \-\-postfix
Prepend or append (respectively) the given argument to all
global or extern variables.
.PP
.RE
.SS SYNTAX
This man page does not fully describe the syntax of
.BR nasm 's
assembly language, but does give a summary of the differences from
other assemblers.
.PP
.I Registers
have no leading `%' sign, unlike
.BR gas ,
and floating-point stack registers are referred to as
.IR st0 ,
.IR st1 ,
and so on.
.PP
.I Floating-point instructions
may use either the single-operand form or the double. A
.I TO
keyword is provided; thus, one could either write
.PP
.ti +15n
fadd st0,st1
.br
.ti +15n
fadd st1,st0
.PP
or one could use the alternative single-operand forms
.PP
.ti +15n
fadd st1
.br
.ti +15n
fadd to st1
.PP
.I Uninitialised storage
is reserved using the
.IR RESB ,
.IR RESW ,
.IR RESD ,
.IR RESQ ,
.I REST
and
.I RESO
pseudo-opcodes, each taking one parameter which gives the number of
bytes, words, doublewords, quadwords or ten-byte words to reserve.
.PP
.I Repetition
of data items is not done by the
.I DUP
keyword as seen in DOS assemblers, but by the use of the
.I TIMES
prefix, like this:
.PP
.ti +6n
.ta 9n
message:	times 3 db 'abc'
.br
.ti +15n
times 64-$+message db 0
.PP
which defines the string `abcabcabc', followed by the right number
of zero bytes to make the total length up to 64 bytes.
.PP
.I 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 location are used. Thus:
.PP
.ti +15n
mov ax,wordvar
.PP
loads AX with the address of the variable `wordvar', whereas
.PP
.ti +15n
mov ax,[wordvar]
.br
.ti +15n
mov ax,[wordvar+1]
.br
.ti +15n
mov ax,[es:wordvar+bx]
.PP
all refer to the
.I contents
of memory locations. The syntaxes
.PP
.ti +15n
mov ax,es:wordvar[bx]
.br
.ti +15n
es mov ax,wordvar[1]
.PP
are not legal at all, although the use of a segment register name as
an instruction prefix is valid, and can be used with instructions
such as
.I LODSB
which can't be overridden any other way.
.PP
.I Constants
may be expressed numerically in most formats: a trailing H, Q or B
denotes hex, octal or binary respectively, and a leading `0x' or `$'
denotes hex as 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 little-endian
(reversed), so that the character constant
.I 'abcd'
denotes 0x64636261 and not 0x61626364.
.PP
.I Local labels
begin with a period, and their `locality' is granted by the
assembler prepending the name of the previous non-local symbol. Thus
declaring a label `.loop' after a label `label' has actually defined
a symbol called `label.loop'.
.SS DIRECTIVES
.I SECTION name
or
.I SEGMENT name
causes
.B nasm
to direct all following code to the named section. Section names
vary with output file format, although most formats support the
names
.IR .text ,
.I .data
and
.IR .bss .
(The exception is the
.I obj
format, in which all segments are user-definable.)
.PP
.I ABSOLUTE address
causes
.B nasm
to position its notional assembly point at an absolute address: so
no code or data may be generated, but you can use
.IR RESB ,
.I RESW
and
.I 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 assembly, you must issue another
.I SECTION
directive to return to normal assembly.
.PP
.I BITS 16,
.I BITS 32
or
.I BITS 64
switches the default processor mode for which
.B nasm
is generating code: it is equivalent to
.I USE16
or
.I USE32
in DOS assemblers.
.PP
.I EXTERN symbol
and
.I GLOBAL symbol
import and export symbol definitions, respectively, from and to
other modules. Note that the
.I GLOBAL
directive must appear before the definition of the symbol it refers
to.
.PP
.I STRUC strucname
and
.IR ENDSTRUC ,
when used to bracket a number of
.IR RESB ,
.I 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
.I _size
tacked on to the end.
.SS FORMAT-SPECIFIC DIRECTIVES
.I ORG address
is used by the
.I bin
flat-form binary output format, and specifies the address at which
the output code will eventually be loaded.
.PP
.I GROUP grpname seg1 seg2...
is used by the
.I obj
(Microsoft 16-bit) output format, and defines segment groups. This
format also uses
.IR UPPERCASE ,
which directs that all segment, group and symbol names output to the
object file should be in uppercase. Note that the actual assembly is
still case sensitive.
.PP
.I LIBRARY libname
is used by the
.I 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.
.SS MACRO PREPROCESSOR
Single-line macros are defined using the
.I %define
or
.I %idefine
commands, in a similar fashion to the C preprocessor. They can be
overloaded with respect to number of parameters, although defining a
macro with no parameters prevents the definition of any macro with
the same name taking parameters, and vice versa.
.I %define
defines macros whose names match case-sensitively, whereas
.I %idefine
defines case-insensitive macros.
.PP
Multi-line macros are defined using
.I %macro
and
.I %imacro
(the distinction is the same as that between
.I %define
and
.IR %idefine ),
whose syntax is as follows:
.PP
.ti +6n
%macro
.I name
.IR minprm [- maxprm "][+][.nolist] [" defaults ]
.br
.ti +15n
<some lines of macro expansion text>
.br
.ti +6n
%endmacro
.PP
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
.I defaults
part can be used to specify defaults for unspecified macro
parameters after
.IR minparam .
.I %endm
is a valid synonym for
.IR %endmacro .
.PP
To refer to the macro parameters within a macro expansion, you use
.IR %1 ,
.I %2
and so on. You can also enforce that a macro parameter should
contain a condition code by using
.IR %+1 ,
and you can invert the condition code by using
.IR %-1 .
You can also define a label specific to a macro invocation by
prefixing it with a double % sign.
.PP
Files can be included using the
.I %include
directive, which works like C.
.PP
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
.IR %push ,
remove one using
.IR %pop ,
and change the name of the top context (without disturbing any
associated definitions) using
.IR %repl .
Labels and
.I %define
macros specific to the top context may be defined by prefixing their
names with %$, and things specific to the next context down with
%$$, and so on.
.PP
Conditional assembly is done by means of
.IR %ifdef ,
.IR %ifndef ,
.I %else
and
.I %endif
as in C. (Except that
.I %ifdef
can accept several putative macro names, and will evaluate TRUE if
any of them is defined.) In addition, the directives
.I %ifctx
and
.I %ifnctx
can be used to condition on the name of the top context on the
context stack. The obvious set of `else-if' directives,
.IR %elifdef ,
.IR %elifndef ,
.IR %elifctx
and
.IR %elifnctx
are also supported.
.SH BUGS
Please report bugs through the bug tracker function at http://nasm.sourceforge.org.
.SH SEE ALSO
.BR as "(" 1 "),"
.BR ld "(" 1 ")."