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