disasm: extension byte support in the disassembler
[nasm.git] / nasm.1
blobd662df84239f8f13d4db92d7cacfd3eb05883176
1 .TH NASM 1 "The Netwide Assembler Project"
2 .SH NAME
3 nasm \- the Netwide Assembler, a portable 80x86 assembler
4 .SH SYNOPSIS
5 .B nasm
7 .B \-@
8 response file
9 ] [
10 .B \-f
11 format
12 ] [
13 .B \-o
14 outfile
15 ] [
16 .B \-l
17 listfile
18 ] [
19 .IR options ...
20 ] filename
21 .br
22 .B nasm \-h
23 .br
24 .B nasm \-v
25 .SH DESCRIPTION
26 The
27 .B nasm
28 command assembles the file
29 .I filename
30 and directs output to the file
31 .I outfile
32 if specified. If
33 .I outfile
34 is not specified,
35 .B nasm
36 will derive a default output file name from the name of its input
37 file, usually by appending `.o' or `.obj', or by removing all
38 extensions for a raw binary file. Failing that, the output file name
39 will be `nasm.out'.
40 .SS OPTIONS
41 .TP
42 .BI \-@ " filename"
43 Causes
44 .B nasm
45 to process options from 
46 .I filename
47 as if they were included on the command line.
48 .TP
49 .B \-a
50 Causes
51 .B nasm
52 to assemble the given input file without first applying the macro
53 preprocessor.
54 .TP
55 .BI \-D " macro[=value]"
56 Pre-defines a single-line macro.
57 .TP
58 .BI \-d " macro[=value]"
59 Same as the
60 .B \-D
61 option.
62 .TP
63 .B \-e
64 Causes
65 .B nasm
66 to preprocess the given input file, and write the output to
67 .I stdout
68 (or the specified output file name), and not actually assemble
69 anything.
70 .TP
71 .BI \-f " format"
72 Specifies the output file format. To see a list of valid output
73 formats, use the
74 .B -hf
75 option.
76 .TP
77 .B \-g
78 Causes
79 .B nasm
80 to generate debug information in selected format
81 .TP
82 .B \-h
83 Causes
84 .B nasm
85 to exit immediately, after giving a summary of its invocation
86 options.
87 .TP
88 .B \-hf
89 Same as
90 .B -h
91 , but also lists all valid output formats.
92 .TP
93 .BI \-I " directory"
94 Adds a directory to the search path for include files. The directory
95 specification must include the trailing slash, as it will be
96 directly prepended to the name of the include file.
97 .TP
98 .BI \-i " directory"
99 Same as the
100 .B \-I
101 option.
103 .BI \-l " listfile"
104 Causes an assembly listing to be directed to the given file, in
105 which the original source is displayed on the right hand side (plus
106 the source for included files and the expansions of multi-line
107 macros) and the generated code is shown in hex on the left.
109 .B \-M
110 Causes
111 .B nasm
112 to output Makefile-style dependencies to stdout; normal output is
113 suppressed.
115 .BI \-O " number"
116 optimize branch offsets (-O0 disables, default).
118 .BI \-o " outfile"
119 Specifies a precise name for the output file, overriding
120 .BR nasm 's
121 default means of determining it.
123 .BI \-P " file"
124 Specifies a file to be pre-included, before the main source file
125 starts to be processed.
127 .BI \-p " file"
128 Same as the
129 .B \-P
130 option.
132 .BI \-r
133 Causes
134 .B nasm
135 to exit immediately, after displaying its version number.
136 .I (obsolete)
138 .B \-s
139 Causes
140 .B nasm
141 to send its error messages and/or help text to
142 .I stdout
143 instead of
144 .IR stderr .
146 .B \-t
147 Causes
148 .B nasm
149 to assemble in SciTech TASM compatible mode
151 .BI \-U " macro"
152 Undefines a single-line macro.
154 .BI \-u " macro"
155 Same as the
156 .B \-U
157 option.
159 .BI \-v
160 Causes
161 .B nasm
162 to exit immediately, after displaying its version number.
164 .BI \-w [+-]foo
165 Causes
166 .B nasm
167 to enable or disable certain classes of warning messages, for
168 example
169 .B \-w+orphan-labels
171 .B \-w-macro-params
173 .BI \-X " format"
174 specifies error reporting format (gnu or vc).
176 .BI \-Z " filename"
177 Causes
178 .B nasm
179 to redirect error messages to
180 .IR filename .
181 This option exists to support operating systems on which stderr is not
182 easily redirected.
185 .SS SYNTAX
186 This man page does not fully describe the syntax of
187 .BR nasm 's
188 assembly language, but does give a summary of the differences from
189 other assemblers.
191 .I Registers
192 have no leading `%' sign, unlike
193 .BR gas ,
194 and floating-point stack registers are referred to as
195 .IR st0 ,
196 .IR st1 ,
197 and so on.
199 .I Floating-point instructions
200 may use either the single-operand form or the double. A
201 .I TO
202 keyword is provided; thus, one could either write
204 .ti +15n
205 fadd st0,st1
207 .ti +15n
208 fadd st1,st0
210 or one could use the alternative single-operand forms
212 .ti +15n
213 fadd st1
215 .ti +15n
216 fadd to st1
218 .I Uninitialised storage
219 is reserved using the
220 .IR RESB ,
221 .IR RESW ,
222 .IR RESD ,
223 .IR RESQ ,
224 .I REST
226 .I RESO
227 pseudo-opcodes, each taking one parameter which gives the number of
228 bytes, words, doublewords, quadwords or ten-byte words to reserve.
230 .I Repetition
231 of data items is not done by the
232 .I DUP
233 keyword as seen in DOS assemblers, but by the use of the
234 .I TIMES
235 prefix, like this:
237 .ti +6n
238 .ta 9n
239 message:        times 3 db 'abc'
241 .ti +15n
242 times 64-$+message db 0
244 which defines the string `abcabcabc', followed by the right number
245 of zero bytes to make the total length up to 64 bytes.
247 .I Symbol references
248 are always understood to be immediate (i.e. the address of the
249 symbol), unless square brackets are used, in which case the contents
250 of the memory location are used. Thus:
252 .ti +15n
253 mov ax,wordvar
255 loads AX with the address of the variable `wordvar', whereas
257 .ti +15n
258 mov ax,[wordvar]
260 .ti +15n
261 mov ax,[wordvar+1]
263 .ti +15n
264 mov ax,[es:wordvar+bx]
266 all refer to the
267 .I contents
268 of memory locations. The syntaxes
270 .ti +15n
271 mov ax,es:wordvar[bx]
273 .ti +15n
274 es mov ax,wordvar[1]
276 are not legal at all, although the use of a segment register name as
277 an instruction prefix is valid, and can be used with instructions
278 such as
279 .I LODSB
280 which can't be overridden any other way.
282 .I Constants
283 may be expressed numerically in most formats: a trailing H, Q or B
284 denotes hex, octal or binary respectively, and a leading `0x' or `$'
285 denotes hex as well. Leading zeros are not treated specially at all.
286 Character constants may be enclosed in single or double quotes;
287 there is no escape character. The ordering is little-endian
288 (reversed), so that the character constant
289 .I 'abcd'
290 denotes 0x64636261 and not 0x61626364.
292 .I Local labels
293 begin with a period, and their `locality' is granted by the
294 assembler prepending the name of the previous non-local symbol. Thus
295 declaring a label `.loop' after a label `label' has actually defined
296 a symbol called `label.loop'.
297 .SS DIRECTIVES
298 .I SECTION name
300 .I SEGMENT name
301 causes
302 .B nasm
303 to direct all following code to the named section. Section names
304 vary with output file format, although most formats support the
305 names
306 .IR .text ,
307 .I .data
309 .IR .bss .
310 (The exception is the
311 .I obj
312 format, in which all segments are user-definable.)
314 .I ABSOLUTE address
315 causes
316 .B nasm
317 to position its notional assembly point at an absolute address: so
318 no code or data may be generated, but you can use
319 .IR RESB ,
320 .I RESW
322 .I RESD
323 to move the assembly point further on, and you can define labels. So
324 this directive may be used to define data structures. When you have
325 finished doing absolute assembly, you must issue another
326 .I SECTION
327 directive to return to normal assembly.
329 .I BITS 16,
330 .I BITS 32
332 .I BITS 64
333 switches the default processor mode for which
334 .B nasm
335 is generating code: it is equivalent to
336 .I USE16
338 .I USE32
339 in DOS assemblers.
341 .I EXTERN symbol
343 .I GLOBAL symbol
344 import and export symbol definitions, respectively, from and to
345 other modules. Note that the
346 .I GLOBAL
347 directive must appear before the definition of the symbol it refers
350 .I STRUC strucname
352 .IR ENDSTRUC ,
353 when used to bracket a number of
354 .IR RESB ,
355 .I RESW
356 or similar instructions, define a data structure. In addition to
357 defining the offsets of the structure members, the construct also
358 defines a symbol for the size of the structure, which is simply the
359 structure name with
360 .I _size
361 tacked on to the end.
362 .SS FORMAT-SPECIFIC DIRECTIVES
363 .I ORG address
364 is used by the
365 .I bin
366 flat-form binary output format, and specifies the address at which
367 the output code will eventually be loaded.
369 .I GROUP grpname seg1 seg2...
370 is used by the
371 .I obj
372 (Microsoft 16-bit) output format, and defines segment groups. This
373 format also uses
374 .IR UPPERCASE ,
375 which directs that all segment, group and symbol names output to the
376 object file should be in uppercase. Note that the actual assembly is
377 still case sensitive.
379 .I LIBRARY libname
380 is used by the
381 .I rdf
382 output format, and causes a dependency record to be written to the
383 output file which indicates that the program requires a certain
384 library in order to run.
385 .SS MACRO PREPROCESSOR
386 Single-line macros are defined using the
387 .I %define
389 .I %idefine
390 commands, in a similar fashion to the C preprocessor. They can be
391 overloaded with respect to number of parameters, although defining a
392 macro with no parameters prevents the definition of any macro with
393 the same name taking parameters, and vice versa.
394 .I %define
395 defines macros whose names match case-sensitively, whereas
396 .I %idefine
397 defines case-insensitive macros.
399 Multi-line macros are defined using
400 .I %macro
402 .I %imacro
403 (the distinction is the same as that between
404 .I %define
406 .IR %idefine ),
407 whose syntax is as follows:
409 .ti +6n
410 %macro
411 .I name
412 .IR minprm [- maxprm "][+][.nolist] [" defaults ]
414 .ti +15n
415 <some lines of macro expansion text>
417 .ti +6n
418 %endmacro
420 Again, these macros may be overloaded. The trailing plus sign
421 indicates that any parameters after the last one get subsumed, with
422 their separating commas, into the last parameter. The
423 .I defaults
424 part can be used to specify defaults for unspecified macro
425 parameters after
426 .IR minparam .
427 .I %endm
428 is a valid synonym for
429 .IR %endmacro .
431 To refer to the macro parameters within a macro expansion, you use
432 .IR %1 ,
433 .I %2
434 and so on. You can also enforce that a macro parameter should
435 contain a condition code by using
436 .IR %+1 ,
437 and you can invert the condition code by using
438 .IR %-1 .
439 You can also define a label specific to a macro invocation by
440 prefixing it with a double % sign.
442 Files can be included using the
443 .I %include
444 directive, which works like C.
446 The preprocessor has a `context stack', which may be used by one
447 macro to store information that a later one will retrieve. You can
448 push a context on the stack using
449 .IR %push ,
450 remove one using
451 .IR %pop ,
452 and change the name of the top context (without disturbing any
453 associated definitions) using
454 .IR %repl .
455 Labels and
456 .I %define
457 macros specific to the top context may be defined by prefixing their
458 names with %$, and things specific to the next context down with
459 %$$, and so on.
461 Conditional assembly is done by means of
462 .IR %ifdef ,
463 .IR %ifndef ,
464 .I %else
466 .I %endif
467 as in C. (Except that
468 .I %ifdef
469 can accept several putative macro names, and will evaluate TRUE if
470 any of them is defined.) In addition, the directives
471 .I %ifctx
473 .I %ifnctx
474 can be used to condition on the name of the top context on the
475 context stack. The obvious set of `else-if' directives,
476 .IR %elifdef ,
477 .IR %elifndef ,
478 .IR %elifctx
480 .IR %elifnctx
481 are also supported.
482 .SH BUGS
483 Please report bugs through the bug tracker function at http://nasm.sourceforge.org.
484 .SH SEE ALSO
485 .BR as "(" 1 "),"
486 .BR ld "(" 1 ")."