1NASM(1)                  The Netwide Assembler Project                 NASM(1)
2
3
4

NAME

6       nasm - the Netwide Assembler, a portable 80x86 assembler
7

SYNOPSIS

9       nasm [-@ response file] [-f format] [-o outfile] [-l listfile]
10       [options...] filename
11

DESCRIPTION

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

OPTIONS

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.
47
48       -gformat
49           Equivalent to -g -F format.
50
51       -h
52           Causes nasm to exit immediately, after giving a summary of its
53           invocation options.
54
55       -hf
56           Same as -h , but also lists all valid output formats.
57
58       -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
63       -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
69       -M
70           Causes nasm to output Makefile-style dependencies to stdout; normal
71           output is suppressed.
72
73       -MG file
74           Same as -M but assumes that missing Makefile dependecies are
75           generated and added to dependency list without a prefix.
76
77       -MF file
78           Output Makefile-style dependencies to the specified file.
79
80       -MD file
81           Same as a combination of -M and -MF options.
82
83       -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
88       -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
93       -MP
94           Emit phony target.
95
96       -O number
97           Optimize branch offsets.
98
99-O0: No optimization
100
101-O1: Minimal optimization
102
103-Ox: Multipass optimization (default)
104
105       -o outfile
106           Specifies a precise name for the output file, overriding nasm's
107           default means of determining it.
108
109       -P|-p file
110           Specifies a file to be pre-included, before the main source file
111           starts to be processed.
112
113       -s
114           Causes nasm to send its error messages and/or help text to stdout
115           instead of stderr.
116
117       -t
118           Causes nasm to assemble in SciTech TASM compatible mode.
119
120       -U|-u macro
121           Undefines a single-line macro.
122
123       -v
124           Causes nasm to exit immediately, after displaying its version
125           number.
126
127       *-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
132       -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
136       -X format
137           Specifies error reporting format (gnu or vc).
138
139       -y
140           Causes nasm to list supported debug formats.
141
142       -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
147       --prefix, --postfix
148           Prepend or append (respectively) the given argument to all global
149           or extern variables.
150

SYNTAX

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
156       Registers have no leading ‘%’ sign, unlike gas, and floating-point
157       stack registers are referred to as st0, st1, and so on.
158
159       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
162           fadd st0,st1
163           fadd st1,st0
164
165       or one could use the alternative single-operand forms
166
167           fadd st1
168           fadd to st1
169
170       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
175       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
178           message: times 3 db 'abc'
179                    times 64-$+message db 0
180
181       which defines the string abcabcabc, followed by the right number of
182       zero bytes to make the total length up to 64 bytes.
183
184       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
188           mov ax,wordvar
189
190       loads AX with the address of the variable wordvar, whereas
191
192           mov ax,[wordvar]
193           mov ax,[wordvar+1]
194           mov ax,[es:wordvar+bx]
195
196       all refer to the contents of memory locations. The syntaxes
197
198           mov ax,es:wordvar[bx]
199           es mov ax,wordvar[1]
200
201       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
205       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
213       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

DIRECTIVES

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
224       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
231       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
235       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
239       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

FORMAT-SPECIFIC DIRECTIVES

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
250       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
256       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

MACRO PREPROCESSOR

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
269       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
273           %macro name minprm[-maxprm][+][.nolist] [defaults]
274                   <some lines of macro expansion text>
275           %endmacro
276
277       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
283       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
289       Files can be included using the %include directive, which works like C.
290
291       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
299       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

BUGS

308       Please report bugs through the bug tracker function at http://nasm.us.
309

SEE ALSO

311       as(1), ld(1).
312
313
314
315NASM                              08/28/2020                           NASM(1)
Impressum