nasm.txt

   1 nasm(1)
   2 =======
   3 :doctype:       manpage
   4 :man source:    NASM
   5 :man manual:    The Netwide Assembler Project
   6
   7 NAME
   8 ----
   9 nasm - the Netwide Assembler, a portable 80x86 assembler
  10
  11 SYNOPSIS
  12 --------
  13 *nasm* [*-@* response file] [*-f* format] [*-o* outfile] [*-l* listfile] ['options'...] filename
  14
  15 DESCRIPTION
  16 -----------
  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'.
  22
  23 OPTIONS
  24 -------
  25 *-@* 'filename'::
  26         Causes *nasm* to process options from filename as if they were included on
  27         the command line.
  28
  29 *-a*::
  30         Causes *nasm* to assemble the given input file without first applying the
  31         macro preprocessor.
  32
  33 *-D*|*-d* 'macro[=value]'::
  34         Pre-defines a single-line macro.
  35
  36 *-E*|*-e*::
  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
  39         anything.
  40
  41 *-f* 'format'::
  42         Specifies the output file format. To see a list of valid output formats,
  43         use the *-hf* option.
  44
  45 *-F* 'format'::
  46         Specifies the debug information format. To see a list of valid output
  47         formats, use the *-y* option (for example *-felf -y*).
  48
  49 *-g*::
  50         Causes *nasm* to generate debug information.
  51
  52 *-g*'format'::
  53         Equivalent to **-g -F**__ format__.
  54
  55 *-h*::
  56         Causes *nasm* to exit immediately, after giving a summary of its
  57         invocation options.
  58
  59 *-hf*::
  60         Same as *-h* , but also lists all valid output formats.
  61
  62 *-I*|*-i* 'directory'::
  63         Adds a directory to the search path for include files. The directory
  64         specification must include the trailing slash, as it will be directly
  65         prepended to the name of the include file.
  66
  67 *-l* 'listfile'::
  68         Causes an assembly listing to be directed to the given file, in which
  69         the original source is displayed on the right hand side (plus the source
  70         for included files and the expansions of multi-line macros) and the
  71         generated code is shown in hex on the left.
  72
  73 *-M*::
  74         Causes *nasm* to output Makefile-style dependencies to stdout; normal
  75         output is suppressed.
  76
  77 *-MG* 'file'::
  78         Same as *-M* but assumes that missing Makefile dependecies are generated
  79         and added to dependency list without a prefix.
  80
  81 *-MF* 'file'::
  82         Output Makefile-style dependencies to the specified file.
  83
  84 *-MD* 'file'::
  85         Same as a combination of *-M* and *-MF* options.
  86
  87 *-MT* 'file'::
  88         Override the default name of the dependency target dependency target name.
  89         This is normally the same as the output filename, specified by
  90         the *-o* option.
  91
  92 *-MQ* 'file'::
  93         The same as *-MT* except it tries to quote characters that have special
  94         meaning in Makefile syntax. This is not foolproof, as not all characters
  95         with special meaning are quotable in Make.
  96
  97 *-MP*::
  98         Emit phony target.
  99
 100 *-O* 'number'::
 101         Optimize branch offsets.
 102         * *-O0*: No optimization
 103         * *-O1*: Minimal optimization
 104         * *-Ox*: Multipass optimization (default)
 105
 106 *-o* 'outfile'::
 107         Specifies a precise name for the output file, overriding *nasm*'s default
 108         means of determining it.
 109
 110 *-P*|*-p* 'file'::
 111         Specifies a file to be pre-included, before the main source file
 112         starts to be processed.
 113
 114 *-s*::
 115         Causes *nasm* to send its error messages and/or help text to stdout
 116         instead of stderr.
 117
 118 *-t*::
 119         Causes *nasm* to assemble in SciTech TASM compatible mode.
 120
 121 *-U*|*-u* 'macro'::
 122         Undefines a single-line macro.
 123
 124 *-v*::
 125         Causes *nasm* to exit immediately, after displaying its version number.
 126
 127 *-W[no-]foo'::
 128         Causes *nasm* to enable or disable certain classes of warning messages,
 129         in gcc-like style, for example *-Worphan-labels* or *-Wno-orphan-labels*.
 130
 131 *-w*'[+-]foo'::
 132         Causes *nasm* to enable or disable certain classes of warning messages,
 133         for example *-w+orphan-labels* or *-w-macro-params*.
 134
 135 *-X* 'format'::
 136         Specifies error reporting format (gnu or vc).
 137
 138 *-y*::
 139         Causes *nasm* to list supported debug formats.
 140
 141 *-Z* 'filename'::
 142         Causes *nasm* to redirect error messages to 'filename'. This option exists
 143         to support operating systems on which stderr is not easily redirected.
 144
 145 --prefix::
 146 --postfix::
 147         Prepend or append (respectively) the given argument to all global or
 148         extern variables.
 149
 150 SYNTAX
 151 ------
 152 This man page does not fully describe the syntax of *nasm*'s assembly language,
 153 but does give a summary of the differences from other assemblers.
 154
 155 'Registers' have no leading `%' sign, unlike *gas*, and floating-point stack
 156 registers are referred to as 'st0', 'st1', and so on.
 157
 158 'Floating-point instructions' may use either the single-operand form or the
 159 double. A 'TO' keyword is provided; thus, one could either write
 160
 161         fadd st0,st1
 162         fadd st1,st0
 163
 164 or one could use the alternative single-operand forms
 165
 166         fadd st1
 167         fadd to st1
 168
 169 'Uninitialised storage' is reserved using the 'RESB', 'RESW', 'RESD', 'RESQ',
 170 'REST' and 'RESO' pseudo-opcodes, each taking one parameter which gives the
 171 number of bytes, words, doublewords, quadwords or ten-byte words to reserve.
 172
 173 'Repetition' of data items is not done by the 'DUP' keyword as seen in DOS
 174 assemblers, but by the use of the 'TIMES' prefix, like this:
 175
 176         message: times 3 db 'abc'
 177                  times 64-$+message db 0
 178
 179 which defines the string `abcabcabc`, followed by the right number of zero
 180 bytes to make the total length up to 64 bytes.
 181
 182 'Symbol references' are always understood to be immediate (i.e. the address
 183 of the symbol), unless square brackets are used, in which case the contents
 184 of the memory location are used. Thus:
 185
 186         mov ax,wordvar
 187
 188 loads AX with the address of the variable `wordvar`, whereas
 189
 190         mov ax,[wordvar]
 191         mov ax,[wordvar+1]
 192         mov ax,[es:wordvar+bx]
 193
 194 all refer to the 'contents' of memory locations. The syntaxes
 195
 196         mov ax,es:wordvar[bx]
 197         es mov ax,wordvar[1]
 198
 199 are not legal at all, although the use of a segment register name as an instruction
 200 prefix is valid, and can be used with instructions such as 'LODSB' which can't
 201 be overridden any other way.
 202
 203 'Constants' may be expressed numerically in most formats: a trailing H, Q or
 204 B denotes hex, octal or binary respectively, and a leading `0x' or `$' denotes
 205 hex as well. Leading zeros are not treated specially at all. Character constants
 206 may be enclosed in single or double quotes; there is no escape character. The
 207 ordering is little-endian (reversed), so that the character constant ''abcd''
 208 denotes 0x64636261 and not 0x61626364.
 209
 210 Local labels begin with a period, and their `locality' is granted by the assembler
 211 prepending the name of the previous non-local symbol. Thus declaring a label
 212 `.loop' after a label `label' has actually defined a symbol called `label.loop'.
 213
 214 DIRECTIVES
 215 ----------
 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, although most
 218 formats support the names '.text', '.data' and '.bss'. (The exception is the
 219 '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 use 'RESB',
 223 'RESW' and 'RESD' to move the assembly point further on, and you can define labels.
 224 So this directive may be used to define data structures. When you have finished
 225 doing absolute assembly, you must issue another 'SECTION' directive to return to
 226 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 DOS
 230 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 must
 234 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 defines a symbol
 239 for the size of the structure, which is simply the structure name with 'size'
 240 tacked on to the end.
 241
 242 FORMAT-SPECIFIC DIRECTIVES
 243 --------------------------
 244 'ORG' 'address' is used by the 'bin' flat-form binary output format, and
 245 specifies the address at which the output code will eventually be loaded.
 246
 247 'GROUP' 'grpname' 'seg1' 'seg2'... is used by the obj (Microsoft 16-bit)
 248 output format, and defines segment groups. This format also uses 'UPPERCASE',
 249 which directs that all segment, group and symbol names output to the object
 250 file should be in uppercase. Note that the actual assembly is still case
 251 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
 257 MACRO PREPROCESSOR
 258 ------------------
 259 Single-line macros are defined using the '%define' or '%idefine' commands, in
 260 a similar fashion to the C preprocessor. They can be overloaded with respect
 261 to number of parameters, although defining a macro with no parameters prevents
 262 the definition of any macro with the same name taking parameters, and vice versa.
 263 '%define' defines macros whose names match case-sensitively, whereas '%idefine'
 264 defines case-insensitive macros.
 265
 266 Multi-line macros are defined using '%macro' and '%imacro' (the distinction is the
 267 same as that between '%define' and '%idefine'), whose syntax is as follows
 268
 269         %macro name minprm[-maxprm][+][.nolist] [defaults]
 270                 <some lines of macro expansion text>
 271         %endmacro
 272
 273 Again, these macros may be overloaded. The trailing plus sign indicates that
 274 any parameters after the last one get subsumed, with their separating commas,
 275 into the last parameter. The 'defaults' part can be used to specify defaults for
 276 unspecified macro parameters after 'minparam'. '%endm' is a valid synonym for
 277 '%endmacro'.
 278
 279 To refer to the macro parameters within a macro expansion, you use '%1', '%2' and
 280 so on. You can also enforce that a macro parameter should contain a condition
 281 code by using '%+1', and you can invert the condition code by using '%-1'. You can also
 282 define a label specific to a macro invocation by prefixing it with a double `%' sign.
 283
 284 Files can be included using the '%include' directive, which works like C.
 285
 286 The preprocessor has a `context stack', which may be used by one macro to store
 287 information that a later one will retrieve. You can push a context on the stack
 288 using '%push', remove one using '%pop', and change the name of the top context (without
 289 disturbing any associated definitions) using '%repl'. Labels and '%define' macros
 290 specific to the top context may be defined by prefixing their names with %$,
 291 and things specific to the next context down with %$$, and so on.
 292
 293 Conditional assembly is done by means of '%ifdef', '%ifndef', '%else' and '%endif'
 294 as in C. (Except that '%ifdef' can accept several putative macro names, and
 295 will evaluate TRUE if any of them is defined.) In addition, the directives
 296 '%ifctx' and '%ifnctx' can be used to condition on the name of the top context
 297 on the context stack. The obvious set of `else-if' directives, '%elifdef',
 298 '%elifndef', '%elifctx' and '%elifnctx' are also supported.
 299
 300 BUGS
 301 ----
 302 Please report bugs through the bug tracker function at http://nasm.us.
 303
 304 SEE ALSO
 305 --------
 306 *as*(1), *ld*(1).