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

SYNTAX

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

DIRECTIVES

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

FORMAT-SPECIFIC DIRECTIVES

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

MACRO PREPROCESSOR

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

BUGS

305       Please report bugs through the bug tracker function at http://nasm.us.
306

SEE ALSO

308       as(1), ld(1).
309
310
311
312NASM                              06/09/2014                           NASM(1)
Impressum