5 :man manual: The Netwide Assembler Project
9 nasm - the Netwide Assembler, a portable 80x86 assembler
13 *nasm* [*-@* response file] [*-f* format] [*-o* outfile] [*-l* listfile] ['options'...] filename
17 The *nasm* command assembles the file 'filename' and directs output to the file
18 'outfile' if specified. If 'outfile' is not specified, *nasm* will derive a default
19 output file name from the name of its input file, usually by appending `.o' or
20 `.obj', or by removing all extensions for a raw binary file. Failing that, the
21 output file name will be `nasm.out'.
26 Causes *nasm* to process options from filename as if they were included on
30 Causes *nasm* to assemble the given input file without first applying the
33 *-D*|*-d* 'macro[=value]'::
34 Pre-defines a single-line macro.
37 Causes *nasm* to preprocess the given input file, and write the output to
38 'stdout' (or the specified output file name), and not actually assemble
42 Specifies the output file format. To see a list of valid output formats,
46 Causes *nasm* to generate debug information in selected format
49 Causes *nasm* to exit immediately, after giving a summary of its
53 Same as *-h* , but also lists all valid output formats.
55 *-I*|*-i* 'directory'::
56 Adds a directory to the search path for include files. The directory
57 specification must include the trailing slash, as it will be directly
58 prepended to the name of the include file.
61 Causes an assembly listing to be directed to the given file, in which
62 the original source is displayed on the right hand side (plus the source
63 for included files and the expansions of multi-line macros) and the
64 generated code is shown in hex on the left.
67 Causes *nasm* to output Makefile-style dependencies to stdout; normal
71 Same as *-M* but assumes that missing Makefile dependecies are generated
72 and added to dependency list without a prefix.
75 Output Makefile-style dependencies to the specified file.
78 Same as a combination of *-M* and *-MF* options.
81 Override the default name of the dependency target dependency target name.
82 This is normally the same as the output filename, specified by
86 The same as *-MT* except it tries to quote characters that have special
87 meaning in Makefile syntax. This is not foolproof, as not all characters
88 with special meaning are quotable in Make.
94 Optimize branch offsets.
95 * *-O0*: No optimization
96 * *-O1*: Minimal optimization
97 * *-Ox*: Multipass optimization (default)
100 Specifies a precise name for the output file, overriding *nasm*'s default
101 means of determining it.
104 Specifies a file to be pre-included, before the main source file
105 starts to be processed.
108 Causes *nasm* to send its error messages and/or help text to stdout
112 Causes *nasm* to assemble in SciTech TASM compatible mode.
115 Undefines a single-line macro.
118 Causes *nasm* to exit immediately, after displaying its version number.
121 Causes *nasm* to enable or disable certain classes of warning messages,
122 for example *-w+orphan-labels* or *-w-macro-params*.
125 Specifies error reporting format (gnu or vc).
128 Causes *nasm* to redirect error messages to 'filename'. This option exists
129 to support operating systems on which stderr is not easily redirected.
133 Prepend or append (respectively) the given argument to all global or
138 This man page does not fully describe the syntax of *nasm*'s assembly language,
139 but does give a summary of the differences from other assemblers.
141 'Registers' have no leading `%' sign, unlike *gas*, and floating-point stack
142 registers are referred to as 'st0', 'st1', and so on.
144 'Floating-point instructions' may use either the single-operand form or the
145 double. A 'TO' keyword is provided; thus, one could either write
150 or one could use the alternative single-operand forms
155 'Uninitialised storage' is reserved using the 'RESB', 'RESW', 'RESD', 'RESQ',
156 'REST' and 'RESO' pseudo-opcodes, each taking one parameter which gives the
157 number of bytes, words, doublewords, quadwords or ten-byte words to reserve.
159 'Repetition' of data items is not done by the 'DUP' keyword as seen in DOS
160 assemblers, but by the use of the 'TIMES' prefix, like this:
162 message: times 3 db 'abc'
163 times 64-$+message db 0
165 which defines the string `abcabcabc`, followed by the right number of zero
166 bytes to make the total length up to 64 bytes.
168 'Symbol references' are always understood to be immediate (i.e. the address
169 of the symbol), unless square brackets are used, in which case the contents
170 of the memory location are used. Thus:
174 loads AX with the address of the variable `wordvar`, whereas
178 mov ax,[es:wordvar+bx]
180 all refer to the 'contents' of memory locations. The syntaxes
182 mov ax,es:wordvar[bx]
185 are not legal at all, although the use of a segment register name as an instruction
186 prefix is valid, and can be used with instructions such as 'LODSB' which can't
187 be overridden any other way.
189 'Constants' may be expressed numerically in most formats: a trailing H, Q or
190 B denotes hex, octal or binary respectively, and a leading `0x' or `$' denotes
191 hex as well. Leading zeros are not treated specially at all. Character constants
192 may be enclosed in single or double quotes; there is no escape character. The
193 ordering is little-endian (reversed), so that the character constant ''abcd''
194 denotes 0x64636261 and not 0x61626364.
196 Local labels begin with a period, and their `locality' is granted by the assembler
197 prepending the name of the previous non-local symbol. Thus declaring a label
198 `.loop' after a label `label' has actually defined a symbol called `label.loop'.
202 'SECTION' 'name' or 'SEGMENT' 'name' causes *nasm* to direct all following code
203 to the named section. Section names vary with output file format, although most
204 formats support the names '.text', '.data' and '.bss'. (The exception is the
205 'obj' format, in which all segments are user-definable.)
207 'ABSOLUTE' 'address' causes *nasm* to position its notional assembly point at
208 an absolute address: so no code or data may be generated, but you can use 'RESB',
209 'RESW' and 'RESD' to move the assembly point further on, and you can define labels.
210 So this directive may be used to define data structures. When you have finished
211 doing absolute assembly, you must issue another 'SECTION' directive to return to
214 'BITS' '16', 'BITS' '32' or 'BITS' '64' switches the default processor mode for
215 which *nasm* is generating code: it is equivalent to 'USE16' or 'USE32' in DOS
218 'EXTERN' 'symbol' and 'GLOBAL' 'symbol' import and export symbol definitions,
219 respectively, from and to other modules. Note that the 'GLOBAL' directive must
220 appear before the definition of the symbol it refers to.
222 'STRUC' 'strucname' and 'ENDSTRUC', when used to bracket a number of 'RESB',
223 'RESW' or similar instructions, define a data structure. In addition to
224 defining the offsets of the structure members, the construct also defines a symbol
225 for the size of the structure, which is simply the structure name with 'size'
226 tacked on to the end.
228 FORMAT-SPECIFIC DIRECTIVES
229 --------------------------
230 'ORG' 'address' is used by the 'bin' flat-form binary output format, and
231 specifies the address at which the output code will eventually be loaded.
233 'GROUP' 'grpname' 'seg1' 'seg2'... is used by the obj (Microsoft 16-bit)
234 output format, and defines segment groups. This format also uses 'UPPERCASE',
235 which directs that all segment, group and symbol names output to the object
236 file should be in uppercase. Note that the actual assembly is still case
239 'LIBRARY' 'libname' is used by the 'rdf' output format, and causes a
240 dependency record to be written to the output file which indicates that
241 the program requires a certain library in order to run.
245 Single-line macros are defined using the '%define' or '%idefine' commands, in
246 a similar fashion to the C preprocessor. They can be overloaded with respect
247 to number of parameters, although defining a macro with no parameters prevents
248 the definition of any macro with the same name taking parameters, and vice versa.
249 '%define' defines macros whose names match case-sensitively, whereas '%idefine'
250 defines case-insensitive macros.
252 Multi-line macros are defined using '%macro' and '%imacro' (the distinction is the
253 same as that between '%define' and '%idefine'), whose syntax is as follows
255 %macro name minprm[-maxprm][+][.nolist] [defaults]
256 <some lines of macro expansion text>
259 Again, these macros may be overloaded. The trailing plus sign indicates that
260 any parameters after the last one get subsumed, with their separating commas,
261 into the last parameter. The 'defaults' part can be used to specify defaults for
262 unspecified macro parameters after 'minparam'. '%endm' is a valid synonym for
265 To refer to the macro parameters within a macro expansion, you use '%1', '%2' and
266 so on. You can also enforce that a macro parameter should contain a condition
267 code by using '%+1', and you can invert the condition code by using '%-1'. You can also
268 define a label specific to a macro invocation by prefixing it with a double `%' sign.
270 Files can be included using the '%include' directive, which works like C.
272 The preprocessor has a `context stack', which may be used by one macro to store
273 information that a later one will retrieve. You can push a context on the stack
274 using '%push', remove one using '%pop', and change the name of the top context (without
275 disturbing any associated definitions) using '%repl'. Labels and '%define' macros
276 specific to the top context may be defined by prefixing their names with %$,
277 and things specific to the next context down with %$$, and so on.
279 Conditional assembly is done by means of '%ifdef', '%ifndef', '%else' and '%endif'
280 as in C. (Except that '%ifdef' can accept several putative macro names, and
281 will evaluate TRUE if any of them is defined.) In addition, the directives
282 '%ifctx' and '%ifnctx' can be used to condition on the name of the top context
283 on the context stack. The obvious set of `else-if' directives, '%elifdef',
284 '%elifndef', '%elifctx' and '%elifnctx' are also supported.
288 Please report bugs through the bug tracker function at http://nasm.us.