1NASM(1) The Netwide Assembler Project NASM(1)
2
3
4
6 nasm - the Netwide Assembler, a portable 80x86 assembler
7
9 nasm [-@ response file] [-f format] [-o outfile] [-l listfile]
10 [options...] filename
11
13 The nasm command assembles the file filename and directs output to the
14 file outfile if specified. If outfile is not specified, nasm will
15 derive a default output file name from the name of its input file,
16 usually by appending ‘.o’ or ‘.obj’, or by removing all extensions for
17 a raw binary file. Failing that, the output file name will be
18 ‘nasm.out’.
19
21 -@ filename
22 Causes nasm to process options from filename as if they were
23 included on the command line.
24
25 -a
26 Causes nasm to assemble the given input file without first applying
27 the macro preprocessor.
28
29 -D|-d macro[=value]
30 Pre-defines a single-line macro.
31
32 -E|-e
33 Causes nasm to preprocess the given input file, and write the
34 output to stdout (or the specified output file name), and not
35 actually assemble anything.
36
37 -f format
38 Specifies the output file format. To see a list of valid output
39 formats, use the -hf option.
40
41 -F format
42 Specifies the debug information format. To see a list of valid
43 output formats, use the -y option (for example -felf -y).
44
45 -g
46 Causes nasm to generate debug information in selected format.
47
48 -h
49 Causes nasm to exit immediately, after giving a summary of its
50 invocation options.
51
52 -hf
53 Same as -h , but also lists all valid output formats.
54
55 -I|-i directory
56 Adds a directory to the search path for include files. The
57 directory specification must include the trailing slash, as it will
58 be directly prepended to the name of the include file.
59
60 -l listfile
61 Causes an assembly listing to be directed to the given file, in
62 which the original source is displayed on the right hand side (plus
63 the source for included files and the expansions of multi-line
64 macros) and the generated code is shown in hex on the left.
65
66 -M
67 Causes nasm to output Makefile-style dependencies to stdout; normal
68 output is suppressed.
69
70 -MG file
71 Same as -M but assumes that missing Makefile dependecies are
72 generated and added to dependency list without a prefix.
73
74 -MF file
75 Output Makefile-style dependencies to the specified file.
76
77 -MD file
78 Same as a combination of -M and -MF options.
79
80 -MT file
81 Override the default name of the dependency target dependency
82 target name. This is normally the same as the output filename,
83 specified by the -o option.
84
85 -MQ file
86 The same as -MT except it tries to quote characters that have
87 special meaning in Makefile syntax. This is not foolproof, as not
88 all characters with special meaning are quotable in Make.
89
90 -MP
91 Emit phony target.
92
93 -O number
94 Optimize branch offsets.
95
96 · -O0: No optimization
97
98 · -O1: Minimal optimization
99
100 · -Ox: Multipass optimization (default)
101
102 -o outfile
103 Specifies a precise name for the output file, overriding nasm's
104 default means of determining it.
105
106 -P|-p file
107 Specifies a file to be pre-included, before the main source file
108 starts to be processed.
109
110 -s
111 Causes nasm to send its error messages and/or help text to stdout
112 instead of stderr.
113
114 -t
115 Causes nasm to assemble in SciTech TASM compatible mode.
116
117 -U|-u macro
118 Undefines a single-line macro.
119
120 -v
121 Causes nasm to exit immediately, after displaying its version
122 number.
123
124 *-W[no-]foo'
125 Causes nasm to enable or disable certain classes of warning
126 messages, in gcc-like style, for example -Worphan-labels or
127 -Wno-orphan-labels.
128
129 -w[+-]foo
130 Causes nasm to enable or disable certain classes of warning
131 messages, for example -w+orphan-labels or -w-macro-params.
132
133 -X format
134 Specifies error reporting format (gnu or vc).
135
136 -y
137 Causes nasm to list supported debug formats.
138
139 -Z filename
140 Causes nasm to redirect error messages to filename. This option
141 exists to support operating systems on which stderr is not easily
142 redirected.
143
144 --prefix, --postfix
145 Prepend or append (respectively) the given argument to all global
146 or extern variables.
147
149 This man page does not fully describe the syntax of nasm's assembly
150 language, but does give a summary of the differences from other
151 assemblers.
152
153 Registers have no leading ‘%’ sign, unlike gas, and floating-point
154 stack registers are referred to as st0, st1, and so on.
155
156 Floating-point instructions may use either the single-operand form or
157 the double. A TO keyword is provided; thus, one could either write
158
159 fadd st0,st1
160 fadd st1,st0
161
162 or one could use the alternative single-operand forms
163
164 fadd st1
165 fadd to st1
166
167 Uninitialised storage is reserved using the RESB, RESW, RESD, RESQ,
168 REST and RESO pseudo-opcodes, each taking one parameter which gives the
169 number of bytes, words, doublewords, quadwords or ten-byte words to
170 reserve.
171
172 Repetition of data items is not done by the DUP keyword as seen in DOS
173 assemblers, but by the use of the TIMES prefix, like this:
174
175 message: times 3 db 'abc'
176 times 64-$+message db 0
177
178 which defines the string abcabcabc, followed by the right number of
179 zero bytes to make the total length up to 64 bytes.
180
181 Symbol references are always understood to be immediate (i.e. the
182 address of the symbol), unless square brackets are used, in which case
183 the contents of the memory location are used. Thus:
184
185 mov ax,wordvar
186
187 loads AX with the address of the variable wordvar, whereas
188
189 mov ax,[wordvar]
190 mov ax,[wordvar+1]
191 mov ax,[es:wordvar+bx]
192
193 all refer to the contents of memory locations. The syntaxes
194
195 mov ax,es:wordvar[bx]
196 es mov ax,wordvar[1]
197
198 are not legal at all, although the use of a segment register name as an
199 instruction prefix is valid, and can be used with instructions such as
200 LODSB which can’t be overridden any other way.
201
202 Constants may be expressed numerically in most formats: a trailing H, Q
203 or B denotes hex, octal or binary respectively, and a leading ‘0x’ or
204 ‘$’ denotes hex as well. Leading zeros are not treated specially at
205 all. Character constants may be enclosed in single or double quotes;
206 there is no escape character. The ordering is little-endian (reversed),
207 so that the character constant 'abcd' denotes 0x64636261 and not
208 0x61626364.
209
210 Local labels begin with a period, and their ‘locality’ is granted by
211 the assembler prepending the name of the previous non-local symbol.
212 Thus declaring a label ‘.loop’ after a label ‘label’ has actually
213 defined a symbol called ‘label.loop’.
214
216 SECTION name or SEGMENT name causes nasm to direct all following code
217 to the named section. Section names vary with output file format,
218 although most formats support the names .text, .data and .bss. (The
219 exception is the obj format, in which all segments are user-definable.)
220
221 ABSOLUTE address causes nasm to position its notional assembly point at
222 an absolute address: so no code or data may be generated, but you can
223 use RESB, RESW and RESD to move the assembly point further on, and you
224 can define labels. So this directive may be used to define data
225 structures. When you have finished doing absolute assembly, you must
226 issue another SECTION directive to return to normal assembly.
227
228 BITS 16, BITS 32 or BITS 64 switches the default processor mode for
229 which nasm is generating code: it is equivalent to USE16 or USE32 in
230 DOS assemblers.
231
232 EXTERN symbol and GLOBAL symbol import and export symbol definitions,
233 respectively, from and to other modules. Note that the GLOBAL directive
234 must appear before the definition of the symbol it refers to.
235
236 STRUC strucname and ENDSTRUC, when used to bracket a number of RESB,
237 RESW or similar instructions, define a data structure. In addition to
238 defining the offsets of the structure members, the construct also
239 defines a symbol for the size of the structure, which is simply the
240 structure name with size tacked on to the end.
241
243 ORG address is used by the bin flat-form binary output format, and
244 specifies the address at which the output code will eventually be
245 loaded.
246
247 GROUP grpname seg1 seg2... is used by the obj (Microsoft 16-bit) output
248 format, and defines segment groups. This format also uses UPPERCASE,
249 which directs that all segment, group and symbol names output to the
250 object file should be in uppercase. Note that the actual assembly is
251 still case sensitive.
252
253 LIBRARY libname is used by the rdf output format, and causes a
254 dependency record to be written to the output file which indicates that
255 the program requires a certain library in order to run.
256
258 Single-line macros are defined using the %define or %idefine commands,
259 in a similar fashion to the C preprocessor. They can be overloaded with
260 respect to number of parameters, although defining a macro with no
261 parameters prevents the definition of any macro with the same name
262 taking parameters, and vice versa. %define defines macros whose names
263 match case-sensitively, whereas %idefine defines case-insensitive
264 macros.
265
266 Multi-line macros are defined using %macro and %imacro (the distinction
267 is the same as that between %define and %idefine), whose syntax is as
268 follows
269
270 %macro name minprm[-maxprm][+][.nolist] [defaults]
271 <some lines of macro expansion text>
272 %endmacro
273
274 Again, these macros may be overloaded. The trailing plus sign indicates
275 that any parameters after the last one get subsumed, with their
276 separating commas, into the last parameter. The defaults part can be
277 used to specify defaults for unspecified macro parameters after
278 minparam. %endm is a valid synonym for %endmacro.
279
280 To refer to the macro parameters within a macro expansion, you use %1,
281 %2 and so on. You can also enforce that a macro parameter should
282 contain a condition code by using %+1, and you can invert the condition
283 code by using %-1. You can also define a label specific to a macro
284 invocation by prefixing it with a double ‘%’ sign.
285
286 Files can be included using the %include directive, which works like C.
287
288 The preprocessor has a ‘context stack’, which may be used by one macro
289 to store information that a later one will retrieve. You can push a
290 context on the stack using %push, remove one using %pop, and change the
291 name of the top context (without disturbing any associated definitions)
292 using %repl. Labels and %define macros specific to the top context may
293 be defined by prefixing their names with %$, and things specific to the
294 next context down with %$$, and so on.
295
296 Conditional assembly is done by means of %ifdef, %ifndef, %else and
297 %endif as in C. (Except that %ifdef can accept several putative macro
298 names, and will evaluate TRUE if any of them is defined.) In addition,
299 the directives %ifctx and %ifnctx can be used to condition on the name
300 of the top context on the context stack. The obvious set of ‘else-if’
301 directives, %elifdef, %elifndef, %elifctx and %elifnctx are also
302 supported.
303
305 Please report bugs through the bug tracker function at http://nasm.us.
306
308 as(1), ld(1).
309
310
311
312NASM 06/09/2014 NASM(1)