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