1NASM(1) General Commands Manual NASM(1)
2
6 nasm - the Netwide Assembler, a portable 80x86 assembler
7
9 nasm [ -@ response file ] [ -f format ] [ -o outfile ] [ -l listfile ]
10 [ options... ] filename
11 nasm -h
12 nasm -v
13
15 The nasm command assembles the file filename and directs output to the
16 file outfile if specified. If outfile is not specified, nasm will
17 derive a default output file name from the name of its input file, usu‐
18 ally by appending `.o' or `.obj', or by removing all extensions for a
19 raw binary file. Failing that, the output file name will be `nasm.out'.
20 OPTIONS
22 -@ filename
23 Causes nasm to process options from filename as if they were
24 included on the command line.
25 -a Causes nasm to assemble the given input file without first
27 applying the macro preprocessor.
28 -D macro[=value]
30 Pre-defines a single-line macro.
31 -d macro[=value]
33 Same as the -D option.
34 -e Causes nasm to preprocess the given input file, and write the
36 output to stdout (or the specified output file name), and not
37 actually assemble anything.
38 -f format
40 Specifies the output file format. To see a list of valid output
41 formats, use the -hf option.
42 -g Causes nasm to generate debug information in selected format
44 -h Causes nasm to exit immediately, after giving a summary of its
46 invocation options.
47 -hf Same as -h , but also lists all valid output formats.
49 -I directory
51 Adds a directory to the search path for include files. The
52 directory specification must include the trailing slash, as it
53 will be directly prepended to the name of the include file.
54 -i directory
56 Same as the -I option.
57 -l listfile
59 Causes an assembly listing to be directed to the given file, in
60 which the original source is displayed on the right hand side
61 (plus the source for included files and the expansions of multi-
62 line macros) and the generated code is shown in hex on the left.
63 -M Causes nasm to output Makefile-style dependencies to stdout;
65 normal output is suppressed.
66 -O number
68 optimize branch offsets (-O0 disables, default).
69 -o outfile
71 Specifies a precise name for the output file, overriding nasm's
72 default means of determining it.
73 -P file
75 Specifies a file to be pre-included, before the main source file
76 starts to be processed.
77 -p file
79 Same as the -P option.
80 -r Causes nasm to exit immediately, after displaying its version
82 number. (obsolete)
83 -s Causes nasm to send its error messages and/or help text to std‐
85 out instead of stderr.
86 -t Causes nasm to assemble in SciTech TASM compatible mode
88 -U macro
90 Undefines a single-line macro.
91 -u macro
93 Same as the -U option.
94 -v Causes nasm to exit immediately, after displaying its version
96 number.
97 -w[+-]foo
99 Causes nasm to enable or disable certain classes of warning mes‐
100 sages, for example -w+orphan-labels or -w-macro-params
101 -X format
103 specifies error reporting format (gnu or vc).
104 -Z filename
106 Causes nasm to redirect error messages to filename. This option
107 exists to support operating systems on which stderr is not eas‐
108 ily redirected.
109 SYNTAX
111 This man page does not fully describe the syntax of nasm's assembly
112 language, but does give a summary of the differences from other assem‐
113 blers.
114 Registers have no leading `%' sign, unlike gas, and floating-point
116 stack registers are referred to as st0, st1, and so on.
117 Floating-point instructions may use either the single-operand form or
119 the double. A TO keyword is provided; thus, one could either write
120 fadd st0,st1
122 fadd st1,st0
123 or one could use the alternative single-operand forms
125 fadd st1
127 fadd to st1
128 Uninitialised storage is reserved using the RESB, RESW, RESD, RESQ,
130 REST and RESO pseudo-opcodes, each taking one parameter which gives the
131 number of bytes, words, doublewords, quadwords or ten-byte words to
132 reserve.
133 Repetition of data items is not done by the DUP keyword as seen in DOS
135 assemblers, but by the use of the TIMES prefix, like this:
136 message: times 3 db 'abc'
138 times 64-$+message db 0
139 which defines the string `abcabcabc', followed by the right number of
141 zero bytes to make the total length up to 64 bytes.
142 Symbol references are always understood to be immediate (i.e. the
144 address of the symbol), unless square brackets are used, in which case
145 the contents of the memory location are used. Thus:
146 mov ax,wordvar
148 loads AX with the address of the variable `wordvar', whereas
150 mov ax,[wordvar]
152 mov ax,[wordvar+1]
153 mov ax,[es:wordvar+bx]
154 all refer to the contents of memory locations. The syntaxes
156 mov ax,es:wordvar[bx]
158 es mov ax,wordvar[1]
159 are not legal at all, although the use of a segment register name as an
161 instruction prefix is valid, and can be used with instructions such as
162 LODSB which can't be overridden any other way.
163 Constants may be expressed numerically in most formats: a trailing H, Q
165 or B denotes hex, octal or binary respectively, and a leading `0x' or
166 `$' denotes hex as well. Leading zeros are not treated specially at
167 all. Character constants may be enclosed in single or double quotes;
168 there is no escape character. The ordering is little-endian (reversed),
169 so that the character constant 'abcd' denotes 0x64636261 and not
170 0x61626364.
171 Local labels begin with a period, and their `locality' is granted by
173 the assembler prepending the name of the previous non-local symbol.
174 Thus declaring a label `.loop' after a label `label' has actually
175 defined a symbol called `label.loop'.
176 DIRECTIVES
178 SECTION name or SEGMENT name causes nasm to direct all following code
179 to the named section. Section names vary with output file format,
180 although most formats support the names .text, .data and .bss. (The
181 exception is the obj format, in which all segments are user-definable.)
182 ABSOLUTE address causes nasm to position its notional assembly point at
184 an absolute address: so no code or data may be generated, but you can
185 use RESB, RESW and RESD to move the assembly point further on, and you
186 can define labels. So this directive may be used to define data struc‐
187 tures. When you have finished doing absolute assembly, you must issue
188 another SECTION directive to return to normal assembly.
189 BITS 16, BITS 32 or BITS 64 switches the default processor mode for
191 which nasm is generating code: it is equivalent to USE16 or USE32 in
192 DOS assemblers.
193 EXTERN symbol and GLOBAL symbol import and export symbol definitions,
195 respectively, from and to other modules. Note that the GLOBAL directive
196 must appear before the definition of the symbol it refers to.
197 STRUC strucname and ENDSTRUC, when used to bracket a number of RESB,
199 RESW or similar instructions, define a data structure. In addition to
200 defining the offsets of the structure members, the construct also
201 defines a symbol for the size of the structure, which is simply the
202 structure name with _size tacked on to the end.
203 FORMAT-SPECIFIC DIRECTIVES
205 ORG address is used by the bin flat-form binary output format, and
206 specifies the address at which the output code will eventually be
207 loaded.
208 GROUP grpname seg1 seg2... is used by the obj (Microsoft 16-bit) out‐
210 put format, and defines segment groups. This format also uses UPPER‐
211 CASE, which directs that all segment, group and symbol names output to
212 the object file should be in uppercase. Note that the actual assembly
213 is still case sensitive.
214 LIBRARY libname is used by the rdf output format, and causes a depen‐
216 dency record to be written to the output file which indicates that the
217 program requires a certain library in order to run.
218 MACRO PREPROCESSOR
220 Single-line macros are defined using the %define or %idefine commands,
221 in a similar fashion to the C preprocessor. They can be overloaded with
222 respect to number of parameters, although defining a macro with no
223 parameters prevents the definition of any macro with the same name tak‐
224 ing parameters, and vice versa. %define defines macros whose names
225 match case-sensitively, whereas %idefine defines case-insensitive
226 macros.
227 Multi-line macros are defined using %macro and %imacro (the distinction
229 is the same as that between %define and %idefine), whose syntax is as
230 follows:
231 %macro name minprm[-maxprm][+][.nolist] [defaults]
233 <some lines of macro expansion text>
234 %endmacro
235 Again, these macros may be overloaded. The trailing plus sign indicates
237 that any parameters after the last one get subsumed, with their sepa‐
238 rating commas, into the last parameter. The defaults part can be used
239 to specify defaults for unspecified macro parameters after minparam.
240 %endm is a valid synonym for %endmacro.
241 To refer to the macro parameters within a macro expansion, you use %1,
243 %2 and so on. You can also enforce that a macro parameter should con‐
244 tain a condition code by using %+1, and you can invert the condition
245 code by using %-1. You can also define a label specific to a macro
246 invocation by prefixing it with a double % sign.
247 Files can be included using the %include directive, which works like C.
249 The preprocessor has a `context stack', which may be used by one macro
251 to store information that a later one will retrieve. You can push a
252 context on the stack using %push, remove one using %pop, and change the
253 name of the top context (without disturbing any associated definitions)
254 using %repl. Labels and %define macros specific to the top context may
255 be defined by prefixing their names with %$, and things specific to the
256 next context down with %$$, and so on.
257 Conditional assembly is done by means of %ifdef, %ifndef, %else and
259 %endif as in C. (Except that %ifdef can accept several putative macro
260 names, and will evaluate TRUE if any of them is defined.) In addition,
261 the directives %ifctx and %ifnctx can be used to condition on the name
262 of the top context on the context stack. The obvious set of `else-if'
263 directives, %elifdef, %elifndef, %elifctx and %elifnctx are also sup‐
264 ported.
265
267 Please report bugs through the bug tracker function at
268 http://nasm.sourceforge.org.
269
271 as(1), ld(1).
272 The Netwide Assembler Project NASM(1)