"Fossies" - the Fresh Open Source Software Archive

Member "nasm-2.15.05/doc/html/nasmdoc2.html" (28 Aug 2020, 50439 Bytes) of package /linux/misc/nasm-2.15.05-xdoc.tar.xz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
    2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    3 <html xmlns="http://www.w3.org/1999/xhtml">
    4 <head>
    5 <title>NASM - The Netwide Assembler</title>
    6 <link href="nasmdoc.css" rel="stylesheet" type="text/css" />
    7 <link href="local.css" rel="stylesheet" type="text/css" />
    8 </head>
    9 <body>
   10 <ul class="navbar">
   11 <li class="first"><a class="prev" href="nasmdoc1.html">Chapter 1</a></li>
   12 <li><a class="next" href="nasmdoc3.html">Chapter 3</a></li>
   13 <li><a class="toc" href="nasmdoc0.html">Contents</a></li>
   14 <li class="last"><a class="index" href="nasmdoci.html">Index</a></li>
   15 </ul>
   16 <div class="title">
   17 <h1>NASM - The Netwide Assembler</h1>
   18 <span class="subtitle">version 2.15.05</span>
   19 </div>
   20 <div class="contents"
   21 >
   22 <h2 id="chapter-2">Chapter 2: Running NASM</h2>
   23 <h3 id="section-2.1">2.1 NASM Command-Line Syntax</h3>
   24 <p>To assemble a file, you issue a command of the form</p>
   25 <pre>
   26 nasm -f &lt;format&gt; &lt;filename&gt; [-o &lt;output&gt;]
   27 </pre>
   28 <p>For example,</p>
   29 <pre>
   30 nasm -f elf myfile.asm
   31 </pre>
   32 <p>will assemble <code>myfile.asm</code> into an ELF object file
   33 <code>myfile.o</code>. And</p>
   34 <pre>
   35 nasm -f bin myfile.asm -o myfile.com
   36 </pre>
   37 <p>will assemble <code>myfile.asm</code> into a raw binary file
   38 <code>myfile.com</code>.</p>
   39 <p>To produce a listing file, with the hex codes output from NASM displayed
   40 on the left of the original sources, use the <code>-l</code> option to give
   41 a listing file name, for example:</p>
   42 <pre>
   43 nasm -f coff myfile.asm -l myfile.lst
   44 </pre>
   45 <p>To get further usage instructions from NASM, try typing</p>
   46 <pre>
   47 nasm -h
   48 </pre>
   49 <p>The option <code>--help</code> is an alias for the <code>-h</code>
   50 option.</p>
   51 <p>If you use Linux but aren't sure whether your system is
   52 <code>a.out</code> or ELF, type</p>
   53 <pre>
   54 file nasm
   55 </pre>
   56 <p>(in the directory in which you put the NASM binary when you installed
   57 it). If it says something like</p>
   58 <pre>
   59 nasm: ELF 32-bit LSB executable i386 (386 and up) Version 1
   60 </pre>
   61 <p>then your system is <code>ELF</code>, and you should use the option
   62 <code>-f elf</code> when you want NASM to produce Linux object files. If it
   63 says</p>
   64 <pre>
   65 nasm: Linux/i386 demand-paged executable (QMAGIC)
   66 </pre>
   67 <p>or something similar, your system is <code>a.out</code>, and you should
   68 use <code>-f aout</code> instead (Linux <code>a.out</code> systems have
   69 long been obsolete, and are rare these days.)</p>
   70 <p>Like Unix compilers and assemblers, NASM is silent unless it goes wrong:
   71 you won't see any output at all, unless it gives error messages.</p>
   72 <h4 id="section-2.1.1">2.1.1 The <code>-o</code> Option: Specifying the Output File Name</h4>
   73 <p>NASM will normally choose the name of your output file for you;
   74 precisely how it does this is dependent on the object file format. For
   75 Microsoft object file formats (<code>obj</code>, <code>win32</code> and
   76 <code>win64</code>), it will remove the <code>.asm</code> extension (or
   77 whatever extension you like to use &ndash; NASM doesn't care) from your
   78 source file name and substitute <code>.obj</code>. For Unix object file
   79 formats (<code>aout</code>, <code>as86</code>, <code>coff</code>,
   80 <code>elf32</code>, <code>elf64</code>, <code>elfx32</code>,
   81 <code>ieee</code>, <code>macho32</code> and <code>macho64</code>) it will
   82 substitute <code>.o</code>. For <code>dbg</code>, <code>rdf</code>,
   83 <code>ith</code> and <code>srec</code>, it will use <code>.dbg</code>,
   84 <code>.rdf</code>, <code>.ith</code> and <code>.srec</code>, respectively,
   85 and for the <code>bin</code> format it will simply remove the extension, so
   86 that <code>myfile.asm</code> produces the output file <code>myfile</code>.</p>
   87 <p>If the output file already exists, NASM will overwrite it, unless it has
   88 the same name as the input file, in which case it will give a warning and
   89 use <code>nasm.out</code> as the output file name instead.</p>
   90 <p>For situations in which this behaviour is unacceptable, NASM provides
   91 the <code>-o</code> command-line option, which allows you to specify your
   92 desired output file name. You invoke <code>-o</code> by following it with
   93 the name you wish for the output file, either with or without an
   94 intervening space. For example:</p>
   95 <pre>
   96 nasm -f bin program.asm -o program.com 
   97 nasm -f bin driver.asm -odriver.sys
   98 </pre>
   99 <p>Note that this is a small o, and is different from a capital O , which
  100 is used to specify the number of optimization passes required. See
  101 <a href="#section-2.1.24">section 2.1.24</a>.</p>
  102 <h4 id="section-2.1.2">2.1.2 The <code>-f</code> Option: Specifying the Output File Format</h4>
  103 <p>If you do not supply the <code>-f</code> option to NASM, it will choose
  104 an output file format for you itself. In the distribution versions of NASM,
  105 the default is always <code>bin</code>; if you've compiled your own copy of
  106 NASM, you can redefine <code>OF_DEFAULT</code> at compile time and choose
  107 what you want the default to be.</p>
  108 <p>Like <code>-o</code>, the intervening space between <code>-f</code> and
  109 the output file format is optional; so <code>-f elf</code> and
  110 <code>-felf</code> are both valid.</p>
  111 <p>A complete list of the available output file formats can be given by
  112 issuing the command <code>nasm -h</code>.</p>
  113 <h4 id="section-2.1.3">2.1.3 The <code>-l</code> Option: Generating a Listing File</h4>
  114 <p>If you supply the <code>-l</code> option to NASM, followed (with the
  115 usual optional space) by a file name, NASM will generate a source-listing
  116 file for you, in which addresses and generated code are listed on the left,
  117 and the actual source code, with expansions of multi-line macros (except
  118 those which specifically request no expansion in source listings: see
  119 <a href="nasmdoc4.html#section-4.3.11">section 4.3.11</a>) on the right.
  120 For example:</p>
  121 <pre>
  122 nasm -f elf myfile.asm -l myfile.lst
  123 </pre>
  124 <p>If a list file is selected, you may turn off listing for a section of
  125 your source with <code>[list -]</code>, and turn it back on with
  126 <code>[list +]</code>, (the default, obviously). There is no "user form"
  127 (without the brackets). This can be used to list only sections of interest,
  128 avoiding excessively long listings.</p>
  129 <h4 id="section-2.1.4">2.1.4 The <code>-L</code> Option: Additional or Modified Listing Info</h4>
  130 <p>Use this option to specify listing output details.</p>
  131 <p>Supported options are:</p>
  132 <ul>
  133 <li>
  134 <p><code>-Lb</code> show builtin macro packages (standard and
  135 <code>%use</code>)</p>
  136 </li>
  137 <li>
  138 <p><code>-Ld</code> show byte and repeat counts in decimal, not hex</p>
  139 </li>
  140 <li>
  141 <p><code>-Le</code> show the preprocessed input</p>
  142 </li>
  143 <li>
  144 <p><code>-Lf</code> ignore <code>.nolist</code> and force listing output</p>
  145 </li>
  146 <li>
  147 <p><code>-Lm</code> show multi-line macro calls with expanded parameters</p>
  148 </li>
  149 <li>
  150 <p><code>-Lp</code> output a list file in every pass, in case of errors</p>
  151 </li>
  152 <li>
  153 <p><code>-Ls</code> show all single-line macro definitions</p>
  154 </li>
  155 <li>
  156 <p><code>-Lw</code> flush the output after every line (very slow, mainly
  157 useful to debug NASM crashes)</p>
  158 </li>
  159 <li>
  160 <p><code>-L+</code> enable <em>all</em> listing options except
  161 <code>-Lw</code> (very verbose)</p>
  162 </li>
  163 </ul>
  164 <p>These options can be enabled or disabled at runtime using the
  165 <code>%pragma list options</code> directive:</p>
  166 <pre>
  167 %pragma list options [+|-]flags...
  168 </pre>
  169 <p>For example, to turn on the <code>d</code> and <code>m</code> flags but
  170 disable the <code>s</code> flag:</p>
  171 <pre>
  172 %pragma list options +dm -s
  173 </pre>
  174 <p>For forward compatility reasons, an undefined flag will be ignored.
  175 Thus, a new flag introduced in a newer version of NASM can be specified
  176 without breaking older versions. Listing flags will always be a single
  177 alphanumeric character and are case sensitive.</p>
  178 <h4 id="section-2.1.5">2.1.5 The <code>-M</code> Option: Generate Makefile Dependencies</h4>
  179 <p>This option can be used to generate makefile dependencies on stdout.
  180 This can be redirected to a file for further processing. For example:</p>
  181 <pre>
  182 nasm -M myfile.asm &gt; myfile.dep
  183 </pre>
  184 <h4 id="section-2.1.6">2.1.6 The <code>-MG</code> Option: Generate Makefile Dependencies</h4>
  185 <p>This option can be used to generate makefile dependencies on stdout.
  186 This differs from the <code>-M</code> option in that if a nonexisting file
  187 is encountered, it is assumed to be a generated file and is added to the
  188 dependency list without a prefix.</p>
  189 <h4 id="section-2.1.7">2.1.7 The <code>-MF</code> Option: Set Makefile Dependency File</h4>
  190 <p>This option can be used with the <code>-M</code> or <code>-MG</code>
  191 options to send the output to a file, rather than to stdout. For example:</p>
  192 <pre>
  193 nasm -M -MF myfile.dep myfile.asm
  194 </pre>
  195 <h4 id="section-2.1.8">2.1.8 The <code>-MD</code> Option: Assemble and Generate Dependencies</h4>
  196 <p>The <code>-MD</code> option acts as the combination of the
  197 <code>-M</code> and <code>-MF</code> options (i.e. a filename has to be
  198 specified.) However, unlike the <code>-M</code> or <code>-MG</code>
  199 options, <code>-MD</code> does <em>not</em> inhibit the normal operation of
  200 the assembler. Use this to automatically generate updated dependencies with
  201 every assembly session. For example:</p>
  202 <pre>
  203 nasm -f elf -o myfile.o -MD myfile.dep myfile.asm
  204 </pre>
  205 <p>If the argument after <code>-MD</code> is an option rather than a
  206 filename, then the output filename is the first applicable one of:</p>
  207 <ul>
  208 <li>
  209 <p>the filename set in the <code>-MF</code> option;</p>
  210 </li>
  211 <li>
  212 <p>the output filename from the <code>-o</code> option with <code>.d</code>
  213 appended;</p>
  214 </li>
  215 <li>
  216 <p>the input filename with the extension set to <code>.d</code>.</p>
  217 </li>
  218 </ul>
  219 <h4 id="section-2.1.9">2.1.9 The <code>-MT</code> Option: Dependency Target Name</h4>
  220 <p>The <code>-MT</code> option can be used to override the default name of
  221 the dependency target. This is normally the same as the output filename,
  222 specified by the <code>-o</code> option.</p>
  223 <h4 id="section-2.1.10">2.1.10 The <code>-MQ</code> Option: Dependency Target Name (Quoted)</h4>
  224 <p>The <code>-MQ</code> option acts as the <code>-MT</code> option, except
  225 it tries to quote characters that have special meaning in Makefile syntax.
  226 This is not foolproof, as not all characters with special meaning are
  227 quotable in Make. The default output (if no <code>-MT</code> or
  228 <code>-MQ</code> option is specified) is automatically quoted.</p>
  229 <h4 id="section-2.1.11">2.1.11 The <code>-MP</code> Option: Emit phony targets</h4>
  230 <p>When used with any of the dependency generation options, the
  231 <code>-MP</code> option causes NASM to emit a phony target without
  232 dependencies for each header file. This prevents Make from complaining if a
  233 header file has been removed.</p>
  234 <h4 id="section-2.1.12">2.1.12 The <code>-MW</code> Option: Watcom Make quoting style</h4>
  235 <p>This option causes NASM to attempt to quote dependencies according to
  236 Watcom Make conventions rather than POSIX Make conventions (also used by
  237 most other Make variants.) This quotes <code>#</code> as <code>$#</code>
  238 rather than <code>\#</code>, uses <code>&amp;</code> rather than
  239 <code>\</code> for continuation lines, and encloses filenames containing
  240 whitespace in double quotes.</p>
  241 <h4 id="section-2.1.13">2.1.13 The <code>-F</code> Option: Selecting a Debug Information Format</h4>
  242 <p>This option is used to select the format of the debug information
  243 emitted into the output file, to be used by a debugger (or <em>will</em>
  244 be). Prior to version 2.03.01, the use of this switch did <em>not</em>
  245 enable output of the selected debug info format. Use <code>-g</code>, see
  246 <a href="#section-2.1.14">section 2.1.14</a>, to enable output. Versions
  247 2.03.01 and later automatically enable <code>-g</code> if <code>-F</code>
  248 is specified.</p>
  249 <p>A complete list of the available debug file formats for an output format
  250 can be seen by issuing the command <code>nasm -h</code>. Not all output
  251 formats currently support debugging output.</p>
  252 <p>This should not be confused with the <code>-f dbg</code> output format
  253 option, see <a href="nasmdoc8.html#section-8.14">section 8.14</a>.</p>
  254 <h4 id="section-2.1.14">2.1.14 The <code>-g</code> Option: Enabling Debug Information.</h4>
  255 <p>This option can be used to generate debugging information in the
  256 specified format. See <a href="#section-2.1.13">section 2.1.13</a>. Using
  257 <code>-g</code> without <code>-F</code> results in emitting debug info in
  258 the default format, if any, for the selected output format. If no debug
  259 information is currently implemented in the selected output format,
  260 <code>-g</code> is <em>silently ignored</em>.</p>
  261 <h4 id="section-2.1.15">2.1.15 The <code>-X</code> Option: Selecting an Error Reporting Format</h4>
  262 <p>This option can be used to select an error reporting format for any
  263 error messages that might be produced by NASM.</p>
  264 <p>Currently, two error reporting formats may be selected. They are the
  265 <code>-Xvc</code> option and the <code>-Xgnu</code> option. The GNU format
  266 is the default and looks like this:</p>
  267 <pre>
  268 filename.asm:65: error: specific error message
  269 </pre>
  270 <p>where <code>filename.asm</code> is the name of the source file in which
  271 the error was detected, <code>65</code> is the source file line number on
  272 which the error was detected, <code>error</code> is the severity of the
  273 error (this could be <code>warning</code>), and
  274 <code>specific error message</code> is a more detailed text message which
  275 should help pinpoint the exact problem.</p>
  276 <p>The other format, specified by <code>-Xvc</code> is the style used by
  277 Microsoft Visual C++ and some other programs. It looks like this:</p>
  278 <pre>
  279 filename.asm(65) : error: specific error message
  280 </pre>
  281 <p>where the only difference is that the line number is in parentheses
  282 instead of being delimited by colons.</p>
  283 <p>See also the <code>Visual C++</code> output format,
  284 <a href="nasmdoc8.html#section-8.5">section 8.5</a>.</p>
  285 <h4 id="section-2.1.16">2.1.16 The <code>-Z</code> Option: Send Errors to a File</h4>
  286 <p>Under <code>MS-DOS</code> it can be difficult (though there are ways) to
  287 redirect the standard-error output of a program to a file. Since NASM
  288 usually produces its warning and error messages on <code>stderr</code>,
  289 this can make it hard to capture the errors if (for example) you want to
  290 load them into an editor.</p>
  291 <p>NASM therefore provides the <code>-Z</code> option, taking a filename
  292 argument which causes errors to be sent to the specified files rather than
  293 standard error. Therefore you can redirect the errors into a file by typing</p>
  294 <pre>
  295 nasm -Z myfile.err -f obj myfile.asm
  296 </pre>
  297 <p>In earlier versions of NASM, this option was called <code>-E</code>, but
  298 it was changed since <code>-E</code> is an option conventionally used for
  299 preprocessing only, with disastrous results. See
  300 <a href="#section-2.1.22">section 2.1.22</a>.</p>
  301 <h4 id="section-2.1.17">2.1.17 The <code>-s</code> Option: Send Errors to <code>stdout</code></h4>
  302 <p>The <code>-s</code> option redirects error messages to
  303 <code>stdout</code> rather than <code>stderr</code>, so it can be
  304 redirected under <code>MS-DOS</code>. To assemble the file
  305 <code>myfile.asm</code> and pipe its output to the <code>more</code>
  306 program, you can type:</p>
  307 <pre>
  308 nasm -s -f obj myfile.asm | more
  309 </pre>
  310 <p>See also the <code>-Z</code> option, <a href="#section-2.1.16">section
  311 2.1.16</a>.</p>
  312 <h4 id="section-2.1.18">2.1.18 The <code>-i</code> Option: Include File Search Directories</h4>
  313 <p>When NASM sees the <code>%include</code> or <code>%pathsearch</code>
  314 directive in a source file (see
  315 <a href="nasmdoc4.html#section-4.6.1">section 4.6.1</a>,
  316 <a href="nasmdoc4.html#section-4.6.2">section 4.6.2</a> or
  317 <a href="nasmdoc3.html#section-3.2.3">section 3.2.3</a>), it will search
  318 for the given file not only in the current directory, but also in any
  319 directories specified on the command line by the use of the <code>-i</code>
  320 option. Therefore you can include files from a macro library, for example,
  321 by typing</p>
  322 <pre>
  323 nasm -ic:\macrolib\ -f obj myfile.asm
  324 </pre>
  325 <p>(As usual, a space between <code>-i</code> and the path name is allowed,
  326 and optional).</p>
  327 <p>Prior NASM 2.14 a path provided in the option has been considered as a
  328 verbatim copy and providing a path separator been up to a caller. One could
  329 implicitly concatenate a search path together with a filename. Still this
  330 was rather a trick than something useful. Now the trailing path separator
  331 is made to always present, thus <code>-ifoo</code> will be considered as
  332 the <code>-ifoo/</code> directory.</p>
  333 <p>If you want to define a <em>standard</em> include search path, similar
  334 to <code>/usr/include</code> on Unix systems, you should place one or more
  335 <code>-i</code> directives in the <code>NASMENV</code> environment variable
  336 (see <a href="#section-2.1.35">section 2.1.35</a>).</p>
  337 <p>For Makefile compatibility with many C compilers, this option can also
  338 be specified as <code>-I</code>.</p>
  339 <h4 id="section-2.1.19">2.1.19 The <code>-p</code> Option: Pre-Include a File</h4>
  340 <p>NASM allows you to specify files to be <em>pre-included</em> into your
  341 source file, by the use of the <code>-p</code> option. So running</p>
  342 <pre>
  343 nasm myfile.asm -p myinc.inc
  344 </pre>
  345 <p>is equivalent to running <code>nasm myfile.asm</code> and placing the
  346 directive <code>%include "myinc.inc"</code> at the start of the file.</p>
  347 <p><code>--include</code> option is also accepted.</p>
  348 <p>For consistency with the <code>-I</code>, <code>-D</code> and
  349 <code>-U</code> options, this option can also be specified as
  350 <code>-P</code>.</p>
  351 <h4 id="section-2.1.20">2.1.20 The <code>-d</code> Option: Pre-Define a Macro</h4>
  352 <p>Just as the <code>-p</code> option gives an alternative to placing
  353 <code>%include</code> directives at the start of a source file, the
  354 <code>-d</code> option gives an alternative to placing a
  355 <code>%define</code> directive. You could code</p>
  356 <pre>
  357 nasm myfile.asm -dFOO=100
  358 </pre>
  359 <p>as an alternative to placing the directive</p>
  360 <pre>
  361 %define FOO 100
  362 </pre>
  363 <p>at the start of the file. You can miss off the macro value, as well: the
  364 option <code>-dFOO</code> is equivalent to coding <code>%define FOO</code>.
  365 This form of the directive may be useful for selecting assembly-time
  366 options which are then tested using <code>%ifdef</code>, for example
  367 <code>-dDEBUG</code>.</p>
  368 <p>For Makefile compatibility with many C compilers, this option can also
  369 be specified as <code>-D</code>.</p>
  370 <h4 id="section-2.1.21">2.1.21 The <code>-u</code> Option: Undefine a Macro</h4>
  371 <p>The <code>-u</code> option undefines a macro that would otherwise have
  372 been pre-defined, either automatically or by a <code>-p</code> or
  373 <code>-d</code> option specified earlier on the command lines.</p>
  374 <p>For example, the following command line:</p>
  375 <pre>
  376 nasm myfile.asm -dFOO=100 -uFOO
  377 </pre>
  378 <p>would result in <code>FOO</code> <em>not</em> being a predefined macro
  379 in the program. This is useful to override options specified at a different
  380 point in a Makefile.</p>
  381 <p>For Makefile compatibility with many C compilers, this option can also
  382 be specified as <code>-U</code>.</p>
  383 <h4 id="section-2.1.22">2.1.22 The <code>-E</code> Option: Preprocess Only</h4>
  384 <p>NASM allows the preprocessor to be run on its own, up to a point. Using
  385 the <code>-E</code> option (which requires no arguments) will cause NASM to
  386 preprocess its input file, expand all the macro references, remove all the
  387 comments and preprocessor directives, and print the resulting file on
  388 standard output (or save it to a file, if the <code>-o</code> option is
  389 also used).</p>
  390 <p>This option cannot be applied to programs which require the preprocessor
  391 to evaluate expressions which depend on the values of symbols: so code such
  392 as</p>
  393 <pre>
  394 %assign tablesize ($-tablestart)
  395 </pre>
  396 <p>will cause an error in preprocess-only mode.</p>
  397 <p>For compatiblity with older version of NASM, this option can also be
  398 written <code>-e</code>. <code>-E</code> in older versions of NASM was the
  399 equivalent of the current <code>-Z</code> option,
  400 <a href="#section-2.1.16">section 2.1.16</a>.</p>
  401 <h4 id="section-2.1.23">2.1.23 The <code>-a</code> Option: Don't Preprocess At All</h4>
  402 <p>If NASM is being used as the back end to a compiler, it might be
  403 desirable to suppress preprocessing completely and assume the compiler has
  404 already done it, to save time and increase compilation speeds. The
  405 <code>-a</code> option, requiring no argument, instructs NASM to replace
  406 its powerful preprocessor with a stub preprocessor which does nothing.</p>
  407 <h4 id="section-2.1.24">2.1.24 The <code>-O</code> Option: Specifying Multipass Optimization</h4>
  408 <p>Using the <code>-O</code> option, you can tell NASM to carry out
  409 different levels of optimization. Multiple flags can be specified after the
  410 <code>-O</code> options, some of which can be combined in a single option,
  411 e.g. <code>-Oxv</code>.</p>
  412 <ul>
  413 <li>
  414 <p><code>-O0</code>: No optimization. All operands take their long forms,
  415 if a short form is not specified, except conditional jumps. This is
  416 intended to match NASM 0.98 behavior.</p>
  417 </li>
  418 <li>
  419 <p><code>-O1</code>: Minimal optimization. As above, but immediate operands
  420 which will fit in a signed byte are optimized, unless the long form is
  421 specified. Conditional jumps default to the long form unless otherwise
  422 specified.</p>
  423 </li>
  424 <li>
  425 <p><code>-Ox</code> (where <code>x</code> is the actual letter
  426 <code>x</code>): Multipass optimization. Minimize branch offsets and signed
  427 immediate bytes, overriding size specification unless the
  428 <code>strict</code> keyword has been used (see
  429 <a href="nasmdoc3.html#section-3.7">section 3.7</a>). For compatibility
  430 with earlier releases, the letter <code>x</code> may also be any number
  431 greater than one. This number has no effect on the actual number of passes.</p>
  432 </li>
  433 <li>
  434 <p><code>-Ov</code>: At the end of assembly, print the number of passes
  435 actually executed.</p>
  436 </li>
  437 </ul>
  438 <p>The <code>-Ox</code> mode is recommended for most uses, and is the
  439 default since NASM 2.09.</p>
  440 <p>Note that this is a capital <code>O</code>, and is different from a
  441 small <code>o</code>, which is used to specify the output file name. See
  442 <a href="#section-2.1.1">section 2.1.1</a>.</p>
  443 <h4 id="section-2.1.25">2.1.25 The <code>-t</code> Option: Enable TASM Compatibility Mode</h4>
  444 <p>NASM includes a limited form of compatibility with Borland's
  445 <code>TASM</code>. When NASM's <code>-t</code> option is used, the
  446 following changes are made:</p>
  447 <ul>
  448 <li>
  449 <p>local labels may be prefixed with <code>@@</code> instead of
  450 <code>.</code></p>
  451 </li>
  452 <li>
  453 <p>size override is supported within brackets. In TASM compatible mode, a
  454 size override inside square brackets changes the size of the operand, and
  455 not the address type of the operand as it does in NASM syntax. E.g.
  456 <code>mov eax,[DWORD val]</code> is valid syntax in TASM compatibility
  457 mode. Note that you lose the ability to override the default address type
  458 for the instruction.</p>
  459 </li>
  460 <li>
  461 <p>unprefixed forms of some directives supported (<code>arg</code>,
  462 <code>elif</code>, <code>else</code>, <code>endif</code>, <code>if</code>,
  463 <code>ifdef</code>, <code>ifdifi</code>, <code>ifndef</code>,
  464 <code>include</code>, <code>local</code>)</p>
  465 </li>
  466 </ul>
  467 <h4 id="section-2.1.26">2.1.26 The <code>-w</code> and <code>-W</code> Options: Enable or Disable Assembly Warnings</h4>
  468 <p>NASM can observe many conditions during the course of assembly which are
  469 worth mentioning to the user, but not a sufficiently severe error to
  470 justify NASM refusing to generate an output file. These conditions are
  471 reported like errors, but come up with the word `warning' before the
  472 message. Warnings do not prevent NASM from generating an output file and
  473 returning a success status to the operating system.</p>
  474 <p>Some conditions are even less severe than that: they are only sometimes
  475 worth mentioning to the user. Therefore NASM supports the <code>-w</code>
  476 command-line option, which enables or disables certain classes of assembly
  477 warning. Such warning classes are described by a name, for example
  478 <code>label-orphan</code>; you can enable warnings of this class by the
  479 command-line option <code>-w+label-orphan</code> and disable it by
  480 <code>-w-label-orphan</code>.</p>
  481 <p>The current warning classes are:</p>
  482 <ul>
  483 <li>
  484 <p><code>all</code> is an group alias for <em>all</em> warning classes.
  485 Thus, <code>-w+all</code> enables all available warnings, and
  486 <code>-w-all</code> disables warnings entirely (since NASM 2.13).</p>
  487 </li>
  488 <li>
  489 <p><code>bad-pragma</code> is a backwards compatibility alias for
  490 <code>pragma-bad</code>.</p>
  491 </li>
  492 <li>
  493 <p><code>bnd</code> warns about ineffective use of the <code>BND</code>
  494 prefix when the <code>JMP</code> instruction is converted to the
  495 <code>SHORT</code> form. This should be extremely rare since the short
  496 <code>JMP</code> only is applicable to jumps inside the same module, but if
  497 it is legitimate, it may be necessary to use <code>bnd jmp dword</code>.</p>
  498 <p>Enabled by default.</p>
  499 </li>
  500 <li>
  501 <p><code>db-empty</code> warns about a <code>DB</code>, <code>DW</code>,
  502 etc declaration with no operands, producing no output. This is permitted,
  503 but often indicative of an error. See
  504 <a href="nasmdoc3.html#section-3.2.1">section 3.2.1</a>.</p>
  505 <p>Enabled by default.</p>
  506 </li>
  507 <li>
  508 <p><code>environment</code> warns if a nonexistent environment variable is
  509 accessed using the <code>%!</code> preprocessor construct (see
  510 <a href="nasmdoc4.html#section-4.11.2">section 4.11.2</a>.) Such
  511 environment variables are treated as empty (with this warning issued)
  512 starting in NASM 2.15; earlier versions of NASM would treat this as an
  513 error.</p>
  514 <p>Enabled by default.</p>
  515 </li>
  516 <li>
  517 <p><code>float</code> is a group alias for all warning classes prefixed by
  518 <code>float-</code>; currently <code>float-denorm</code>,
  519 <code>float-overflow</code>, <code>float-toolong</code>, and
  520 <code>float-underflow</code>.</p>
  521 </li>
  522 <li>
  523 <p><code>float-denorm</code> warns about denormal floating point constants.</p>
  524 <p>Disabled by default.</p>
  525 </li>
  526 <li>
  527 <p><code>float-overflow</code> warns about floating point underflow.</p>
  528 <p>Enabled by default.</p>
  529 </li>
  530 <li>
  531 <p><code>float-toolong</code> warns about too many digits in floating-point
  532 numbers.</p>
  533 <p>Enabled by default.</p>
  534 </li>
  535 <li>
  536 <p><code>float-underflow</code> warns about floating point underflow (a
  537 nonzero constant rounded to zero.)</p>
  538 <p>Disabled by default.</p>
  539 </li>
  540 <li>
  541 <p><code>hle</code> warns about invalid use of the HLE
  542 <code>XACQUIRE</code> or <code>XRELEASE</code> prefixes.</p>
  543 <p>Enabled by default.</p>
  544 </li>
  545 <li>
  546 <p><code>label</code> is a group alias for all warning classes prefixed by
  547 <code>label-</code>; currently <code>label-orphan</code>,
  548 <code>label-redef</code>, and <code>label-redef-late</code>.</p>
  549 </li>
  550 <li>
  551 <p><code>label-orphan</code> warns about source lines which contain no
  552 instruction but define a label without a trailing colon. This is most
  553 likely indicative of a typo, but is technically correct NASM syntax (see
  554 <a href="nasmdoc3.html#section-3.1">section 3.1</a>.)</p>
  555 <p>Enabled by default.</p>
  556 </li>
  557 <li>
  558 <p><code>label-redef</code> warns if a label is defined more than once, but
  559 the value is identical. It is an unconditional error to define the same
  560 label more than once to <em>different</em> values.</p>
  561 <p>Disabled by default.</p>
  562 </li>
  563 <li>
  564 <p><code>label-redef-late</code> the value of a label changed during the
  565 final, code-generation pass. This may be the result of strange use of the
  566 preprocessor. This is very likely to produce incorrect code and may end up
  567 being an unconditional error in a future version of NASM.</p>
  568 <p>Enabled and promoted to error by default.</p>
  569 </li>
  570 <li>
  571 <p><code>lock</code> warns about <code>LOCK</code> prefixes on unlockable
  572 instructions.</p>
  573 <p>Enabled by default.</p>
  574 </li>
  575 <li>
  576 <p><code>macro</code> is a group alias for all warning classes prefixed by
  577 <code>macro-</code>; currently <code>macro-def-case-single</code>,
  578 <code>macro-def-greedy-single</code>, <code>macro-def-param-single</code>,
  579 <code>macro-defaults</code>, <code>macro-params-legacy</code>,
  580 <code>macro-params-multi</code>, and <code>macro-params-single</code>.</p>
  581 </li>
  582 <li>
  583 <p><code>macro-def</code> is a group alias for all warning classes prefixed
  584 by <code>macro-def-</code>; currently <code>macro-def-case-single</code>,
  585 <code>macro-def-greedy-single</code>, and
  586 <code>macro-def-param-single</code>.</p>
  587 </li>
  588 <li>
  589 <p><code>macro-def-case-single</code> warns when a single-line macro is
  590 defined both case sensitive and case insensitive. The new macro definition
  591 will override (shadow) the original one, although the original macro is not
  592 deleted, and will be re-exposed if the new macro is deleted with
  593 <code>%undef</code>, or, if the original macro is the case insensitive one,
  594 the macro call is done with a different case.</p>
  595 <p>Enabled by default.</p>
  596 </li>
  597 <li>
  598 <p><code>macro-def-greedy-single</code> definition shadows greedy macro
  599 warns when a single-line macro is defined which would match a previously
  600 existing greedy definition. The new macro definition will override (shadow)
  601 the original one, although the original macro is not deleted, and will be
  602 re-exposed if the new macro is deleted with <code>%undef</code>, and will
  603 be invoked if called with a parameter count that does not match the new
  604 definition.</p>
  605 <p>Enabled by default.</p>
  606 </li>
  607 <li>
  608 <p><code>macro-def-param-single</code> warns if the same single-line macro
  609 is defined with and without parameters. The new macro definition will
  610 override (shadow) the original one, although the original macro is not
  611 deleted, and will be re-exposed if the new macro is deleted with
  612 <code>%undef</code>.</p>
  613 <p>Enabled and promoted to error by default.</p>
  614 </li>
  615 <li>
  616 <p><code>macro-defaults</code> warns when a macro has more default
  617 parameters than optional parameters. See
  618 <a href="nasmdoc4.html#section-4.3.5">section 4.3.5</a> for why might want
  619 to disable this warning.</p>
  620 <p>Enabled by default.</p>
  621 </li>
  622 <li>
  623 <p><code>macro-params</code> is a group alias for all warning classes
  624 prefixed by <code>macro-params-</code>; currently
  625 <code>macro-params-legacy</code>, <code>macro-params-multi</code>, and
  626 <code>macro-params-single</code>.</p>
  627 </li>
  628 <li>
  629 <p><code>macro-params-legacy</code> warns about multi-line macros being
  630 invoked with the wrong number of parameters, but for bug-compatibility with
  631 NASM versions older than 2.15, NASM tried to fix up the parameters to match
  632 the legacy behavior and call the macro anyway. This can happen in certain
  633 cases where there are empty arguments without braces, sometimes as a result
  634 of macro expansion.</p>
  635 <p>The legacy behavior is quite strange and highly context-dependent, and
  636 can be disabled with:</p>
  637 <pre>
  638      %pragma preproc sane_empty_expansion true
  639 </pre>
  640 <p>It is highly recommended to use this option in new code.</p>
  641 <p>Enabled by default.</p>
  642 </li>
  643 <li>
  644 <p><code>macro-params-multi</code> warns about multi-line macros being
  645 invoked with the wrong number of parameters. See
  646 <a href="nasmdoc4.html#section-4.3.1">section 4.3.1</a> for an example of
  647 why you might want to disable this warning.</p>
  648 <p>Enabled by default.</p>
  649 </li>
  650 <li>
  651 <p><code>macro-params-single</code> warns about single-line macros being
  652 invoked with the wrong number of parameters.</p>
  653 <p>Enabled by default.</p>
  654 </li>
  655 <li>
  656 <p><code>negative-rep</code> warns about negative counts given to the
  657 <code>%rep</code> preprocessor directive.</p>
  658 <p>Enabled by default.</p>
  659 </li>
  660 <li>
  661 <p><code>not-my-pragma</code> is a backwards compatibility alias for
  662 <code>pragma-na</code>.</p>
  663 </li>
  664 <li>
  665 <p><code>number-overflow</code> covers warnings about numeric constants
  666 which don't fit in 64 bits.</p>
  667 <p>Enabled by default.</p>
  668 </li>
  669 <li>
  670 <p><code>obsolete</code> is a group alias for all warning classes prefixed
  671 by <code>obsolete-</code>; currently <code>obsolete-nop</code>,
  672 <code>obsolete-removed</code>, and <code>obsolete-valid</code>.</p>
  673 </li>
  674 <li>
  675 <p><code>obsolete-nop</code> warns for an instruction which has been
  676 removed from the architecture, but has been architecturally defined to be a
  677 noop for future CPUs.</p>
  678 <p>Enabled by default.</p>
  679 </li>
  680 <li>
  681 <p><code>obsolete-removed</code> warns for an instruction which has been
  682 removed from the architecture, and is no longer included in the CPU
  683 definition given in the <code>[CPU]</code> directive, for example
  684 <code>POP CS</code>, the opcode for which, <code>0Fh</code>, instead is an
  685 opcode prefix on CPUs newer than the first generation 8086.</p>
  686 <p>Enabled by default.</p>
  687 </li>
  688 <li>
  689 <p><code>obsolete-valid</code> warns for an instruction which has been
  690 removed from the architecture, but is still valid on the specific CPU given
  691 in the <code>CPU</code> directive. Code using these instructions is most
  692 likely not forward compatible.</p>
  693 <p>Enabled by default.</p>
  694 </li>
  695 <li>
  696 <p><code>orphan-labels</code> is a backwards compatibility alias for
  697 <code>label-orphan</code>.</p>
  698 </li>
  699 <li>
  700 <p><code>other</code> specifies any warning not included in any specific
  701 warning class.</p>
  702 <p>Enabled by default.</p>
  703 </li>
  704 <li>
  705 <p><code>phase</code> warns about symbols having changed values during the
  706 second-to-last assembly pass. This is not inherently fatal, but may be a
  707 source of bugs.</p>
  708 <p>Disabled by default.</p>
  709 </li>
  710 <li>
  711 <p><code>pragma</code> is a group alias for all warning classes prefixed by
  712 <code>pragma-</code>; currently <code>pragma-bad</code>,
  713 <code>pragma-empty</code>, <code>pragma-na</code>, and
  714 <code>pragma-unknown</code>.</p>
  715 </li>
  716 <li>
  717 <p><code>pragma-bad</code> warns about a malformed or otherwise unparsable
  718 <code>%pragma</code> directive.</p>
  719 <p>Disabled by default.</p>
  720 </li>
  721 <li>
  722 <p><code>pragma-empty</code> warns about a <code>%pragma</code> directive
  723 containing nothing. This is treated identically to
  724 <code>%pragma ignore</code> except for this optional warning.</p>
  725 <p>Disabled by default.</p>
  726 </li>
  727 <li>
  728 <p><code>pragma-na</code> warns about a <code>%pragma</code> directive
  729 which is not applicable to this particular assembly session. This is not
  730 yet implemented.</p>
  731 <p>Disabled by default.</p>
  732 </li>
  733 <li>
  734 <p><code>pragma-unknown</code> warns about an unknown <code>%pragma</code>
  735 directive. This is not yet implemented for most cases.</p>
  736 <p>Disabled by default.</p>
  737 </li>
  738 <li>
  739 <p><code>ptr</code> warns about keywords used in other assemblers that
  740 might indicate a mistake in the source code. Currently only the MASM
  741 <code>PTR</code> keyword is recognized. See also
  742 <a href="nasmdoc6.html#section-6.5">section 6.5</a>.</p>
  743 <p>Enabled by default.</p>
  744 </li>
  745 <li>
  746 <p><code>regsize</code> warns about a register with implicit size (such as
  747 <code>EAX</code>, which is always 32 bits) been given an explicit size
  748 specification which is inconsistent with the size of the named register,
  749 e.g. <code>WORD EAX</code>. <code>DWORD EAX</code> or <code>WORD AX</code>
  750 are permitted, and do not trigger this warning. Some registers which <em>do
  751 not</em> imply a specific size, such as <code>K0</code>, may need this
  752 specification unless the instruction itself implies the instruction size:</p>
  753 <pre>
  754      KMOVW K0,[foo]          ; Permitted, KMOVW implies 16 bits 
  755      KMOV  WORD K0,[foo]     ; Permitted, WORD K0 specifies instruction size 
  756      KMOV  K0,WORD [foo]     ; Permitted, WORD [foo] specifies instruction size 
  757      KMOV  K0,[foo]          ; Not permitted, instruction size ambiguous
  758 </pre>
  759 <p>Enabled by default.</p>
  760 </li>
  761 <li>
  762 <p><code>unknown-pragma</code> is a backwards compatibility alias for
  763 <code>pragma-unknown</code>.</p>
  764 </li>
  765 <li>
  766 <p><code>unknown-warning</code> warns about a <code>-w</code> or
  767 <code>-W</code> option or a <code>[WARNING]</code> directive that contains
  768 an unknown warning name or is otherwise not possible to process.</p>
  769 <p>Disabled by default.</p>
  770 </li>
  771 <li>
  772 <p><code>user</code> controls output of <code>%warning</code> directives
  773 (see <a href="nasmdoc4.html#section-4.9">section 4.9</a>).</p>
  774 <p>Enabled by default.</p>
  775 </li>
  776 <li>
  777 <p><code>warn-stack-empty</code> a [WARNING POP] directive was executed
  778 when the warning stack is empty. This is treated as a [WARNING *all]
  779 directive.</p>
  780 <p>Enabled by default.</p>
  781 </li>
  782 <li>
  783 <p><code>zeroing</code> a <code>RESx</code> directive was used in a section
  784 which contains initialized data, and the output format does not support
  785 this. Instead, this will be replaced with explicit zero content, which may
  786 produce a large output file.</p>
  787 <p>Enabled by default.</p>
  788 </li>
  789 <li>
  790 <p><code>zext-reloc</code> warns that a relocation has been zero-extended
  791 due to limitations in the output format.</p>
  792 <p>Enabled by default.</p>
  793 </li>
  794 </ul>
  795 <p>Since version 2.15, NASM has group aliases for all prefixed warnings, so
  796 they can be used to enable or disable all warnings in the group. For
  797 example, &ndash;w+float enables all warnings with names starting with
  798 float-*.</p>
  799 <p>Since version 2.00, NASM has also supported the
  800 <code>gcc</code>&ndash;like syntax <code>-Wwarning-class</code> and
  801 <code>-Wno-warning-class</code> instead of <code>-w+warning-class</code>
  802 and <code>-w-warning-class</code>, respectively; both syntaxes work
  803 identically.</p>
  804 <p>The option <code>-w+error</code> or <code>-Werror</code> can be used to
  805 treat warnings as errors. This can be controlled on a per warning class
  806 basis (<code>-w+error=</code><em>warning-class</em> or
  807 <code>-Werror=</code><em>warning-class</em>); if no <em>warning-class</em>
  808 is specified NASM treats it as <code>-w+error=all</code>; the same applies
  809 to <code>-w-error</code> or <code>-Wno-error</code>, of course.</p>
  810 <p>In addition, you can control warnings in the source code itself, using
  811 the <code>[WARNING]</code> directive. See
  812 <a href="nasmdoc7.html#section-7.13">section 7.13</a>.</p>
  813 <h4 id="section-2.1.27">2.1.27 The <code>-v</code> Option: Display Version Info</h4>
  814 <p>Typing <code>NASM -v</code> will display the version of NASM which you
  815 are using, and the date on which it was compiled.</p>
  816 <p>You will need the version number if you report a bug.</p>
  817 <p>For command-line compatibility with Yasm, the form <code>--v</code> is
  818 also accepted for this option starting in NASM version 2.11.05.</p>
  819 <h4 id="section-2.1.28">2.1.28 The <code>--(g|l)prefix</code>, <code>--(g|l)postfix</code> Options.</h4>
  820 <p>The <code>--(g)prefix</code> options prepend the given argument to all
  821 <code>extern</code>, <code>common</code>, <code>static</code>, and
  822 <code>global</code> symbols, and the <code>--lprefix</code> option prepends
  823 to all other symbols. Similarly, <code>--(g)postfix</code> and
  824 <code>--lpostfix</code> options append the argument in the exactly same way
  825 as the <code>--xxprefix</code> options does.</p>
  826 <p>Running this:</p>
  827 <pre>
  828 nasm -f macho --gprefix _
  829 </pre>
  830 <p>is equivalent to place the directive with
  831 <code>%pragma macho gprefix _</code> at the start of the file
  832 (<a href="nasmdoc7.html#section-7.10">section 7.10</a>). It will prepend
  833 the underscore to all global and external variables, as C requires it in
  834 some, but not all, system calling conventions.</p>
  835 <h4 id="section-2.1.29">2.1.29 The <code>--pragma</code> Option</h4>
  836 <p>NASM accepts an argument as <code>%pragma</code> option, which is like
  837 placing a <code>%pragma</code> preprocess statement at the beginning of the
  838 source. Running this:</p>
  839 <pre>
  840 nasm -f macho --pragma "macho gprefix _"
  841 </pre>
  842 <p>is equivalent to the example in <a href="#section-2.1.28">section
  843 2.1.28</a>. See <a href="nasmdoc4.html#section-4.10">section 4.10</a>.</p>
  844 <h4 id="section-2.1.30">2.1.30 The <code>--before</code> Option</h4>
  845 <p>A preprocess statement can be accepted with this option. The example
  846 shown in <a href="#section-2.1.29">section 2.1.29</a> is the same as
  847 running this:</p>
  848 <pre>
  849 nasm -f macho --before "%pragma macho gprefix _"
  850 </pre>
  851 <h4 id="section-2.1.31">2.1.31 The <code>--limit-X</code> Option</h4>
  852 <p>This option allows user to setup various maximum values after which NASM
  853 will terminate with a fatal error rather than consume arbitrary amount of
  854 compute time. Each limit can be set to a positive number or
  855 <code>unlimited</code>.</p>
  856 <ul>
  857 <li>
  858 <p><code>--limit-passes</code>: Number of maximum allowed passes. Default
  859 is <code>unlimited</code>.</p>
  860 </li>
  861 <li>
  862 <p><code>--limit-stalled-passes</code>: Maximum number of allowed
  863 unfinished passes. Default is 1000.</p>
  864 </li>
  865 <li>
  866 <p><code>--limit-macro-levels</code>: Define maximum depth of macro
  867 expansion (in preprocess). Default is 10000</p>
  868 </li>
  869 <li>
  870 <p><code>--limit-macro-tokens</code>: Maximum number of tokens processed
  871 during single-line macro expansion. Default is 10000000.</p>
  872 </li>
  873 <li>
  874 <p><code>--limit-mmacros</code>: Maximum number of multi-line macros
  875 processed before returning to the top-level input. Default is 100000.</p>
  876 </li>
  877 <li>
  878 <p><code>--limit-rep</code>: Maximum number of allowed preprocessor loop,
  879 defined under <code>%rep</code>. Default is 1000000.</p>
  880 </li>
  881 <li>
  882 <p><code>--limit-eval</code>: This number sets the boundary condition of
  883 allowed expression length. Default is 8192 on most systems.</p>
  884 </li>
  885 <li>
  886 <p><code>--limit-lines</code>: Total number of source lines allowed to be
  887 processed. Default is 2000000000.</p>
  888 </li>
  889 </ul>
  890 <p>For example, set the maximum line count to 1000:</p>
  891 <pre>
  892 nasm --limit-lines 1000
  893 </pre>
  894 <p>Limits can also be set via the directive <code>%pragma limit</code>, for
  895 example:</p>
  896 <pre>
  897 %pragma limit lines 1000
  898 </pre>
  899 <h4 id="section-2.1.32">2.1.32 The <code>--keep-all</code> Option</h4>
  900 <p>This option prevents NASM from deleting any output files even if an
  901 error happens.</p>
  902 <h4 id="section-2.1.33">2.1.33 The <code>--no-line</code> Option</h4>
  903 <p>If this option is given, all <code>%line</code> directives in the source
  904 code are ignored. This can be useful for debugging already preprocessed
  905 code. See <a href="nasmdoc4.html#section-4.11.1">section 4.11.1</a>.</p>
  906 <h4 id="section-2.1.34">2.1.34 The <code>--reproducible</code> Option</h4>
  907 <p>If this option is given, NASM will not emit information that is
  908 inherently dependent on the NASM version or different from run to run (such
  909 as timestamps) into the output file.</p>
  910 <h4 id="section-2.1.35">2.1.35 The <code>NASMENV</code> Environment Variable</h4>
  911 <p>If you define an environment variable called <code>NASMENV</code>, the
  912 program will interpret it as a list of extra command-line options, which
  913 are processed before the real command line. You can use this to define
  914 standard search directories for include files, by putting <code>-i</code>
  915 options in the <code>NASMENV</code> variable.</p>
  916 <p>The value of the variable is split up at white space, so that the value
  917 <code>-s -ic:\nasmlib\</code> will be treated as two separate options.
  918 However, that means that the value <code>-dNAME="my name"</code> won't do
  919 what you might want, because it will be split at the space and the NASM
  920 command-line processing will get confused by the two nonsensical words
  921 <code>-dNAME="my</code> and <code>name"</code>.</p>
  922 <p>To get round this, NASM provides a feature whereby, if you begin the
  923 <code>NASMENV</code> environment variable with some character that isn't a
  924 minus sign, then NASM will treat this character as the separator character
  925 for options. So setting the <code>NASMENV</code> variable to the value
  926 <code>!-s!-ic:\nasmlib\</code> is equivalent to setting it to
  927 <code>-s -ic:\nasmlib\</code>, but <code>!-dNAME="my name"</code> will
  928 work.</p>
  929 <p>This environment variable was previously called <code>NASM</code>. This
  930 was changed with version 0.98.31.</p>
  931 <h3 id="section-2.2">2.2 Quick Start for MASM Users</h3>
  932 <p>If you're used to writing programs with MASM, or with TASM in
  933 MASM-compatible (non-Ideal) mode, or with <code>a86</code>, this section
  934 attempts to outline the major differences between MASM's syntax and NASM's.
  935 If you're not already used to MASM, it's probably worth skipping this
  936 section.</p>
  937 <h4 id="section-2.2.1">2.2.1 NASM Is Case-Sensitive</h4>
  938 <p>One simple difference is that NASM is case-sensitive. It makes a
  939 difference whether you call your label <code>foo</code>, <code>Foo</code>
  940 or <code>FOO</code>. If you're assembling to <code>DOS</code> or
  941 <code>OS/2</code> <code>.OBJ</code> files, you can invoke the
  942 <code>UPPERCASE</code> directive (documented in
  943 <a href="nasmdoc8.html#section-8.4">section 8.4</a>) to ensure that all
  944 symbols exported to other code modules are forced to be upper case; but
  945 even then, <em>within</em> a single module, NASM will distinguish between
  946 labels differing only in case.</p>
  947 <h4 id="section-2.2.2">2.2.2 NASM Requires Square Brackets For Memory References</h4>
  948 <p>NASM was designed with simplicity of syntax in mind. One of the design
  949 goals of NASM is that it should be possible, as far as is practical, for
  950 the user to look at a single line of NASM code and tell what opcode is
  951 generated by it. You can't do this in MASM: if you declare, for example,</p>
  952 <pre>
  953 foo     equ     1 
  954 bar     dw      2
  955 </pre>
  956 <p>then the two lines of code</p>
  957 <pre>
  958         mov     ax,foo 
  959         mov     ax,bar
  960 </pre>
  961 <p>generate completely different opcodes, despite having identical-looking
  962 syntaxes.</p>
  963 <p>NASM avoids this undesirable situation by having a much simpler syntax
  964 for memory references. The rule is simply that any access to the
  965 <em>contents</em> of a memory location requires square brackets around the
  966 address, and any access to the <em>address</em> of a variable doesn't. So
  967 an instruction of the form <code>mov ax,foo</code> will <em>always</em>
  968 refer to a compile-time constant, whether it's an <code>EQU</code> or the
  969 address of a variable; and to access the <em>contents</em> of the variable
  970 <code>bar</code>, you must code <code>mov ax,[bar]</code>.</p>
  971 <p>This also means that NASM has no need for MASM's <code>OFFSET</code>
  972 keyword, since the MASM code <code>mov ax,offset bar</code> means exactly
  973 the same thing as NASM's <code>mov ax,bar</code>. If you're trying to get
  974 large amounts of MASM code to assemble sensibly under NASM, you can always
  975 code <code>%idefine offset</code> to make the preprocessor treat the
  976 <code>OFFSET</code> keyword as a no-op.</p>
  977 <p>This issue is even more confusing in <code>a86</code>, where declaring a
  978 label with a trailing colon defines it to be a `label' as opposed to a
  979 `variable' and causes <code>a86</code> to adopt NASM-style semantics; so in
  980 <code>a86</code>, <code>mov ax,var</code> has different behaviour depending
  981 on whether <code>var</code> was declared as <code>var: dw 0</code> (a
  982 label) or <code>var dw 0</code> (a word-size variable). NASM is very simple
  983 by comparison: <em>everything</em> is a label.</p>
  984 <p>NASM, in the interests of simplicity, also does not support the hybrid
  985 syntaxes supported by MASM and its clones, such as
  986 <code>mov ax,table[bx]</code>, where a memory reference is denoted by one
  987 portion outside square brackets and another portion inside. The correct
  988 syntax for the above is <code>mov ax,[table+bx]</code>. Likewise,
  989 <code>mov ax,es:[di]</code> is wrong and <code>mov ax,[es:di]</code> is
  990 right.</p>
  991 <h4 id="section-2.2.3">2.2.3 NASM Doesn't Store Variable Types</h4>
  992 <p>NASM, by design, chooses not to remember the types of variables you
  993 declare. Whereas MASM will remember, on seeing <code>var dw 0</code>, that
  994 you declared <code>var</code> as a word-size variable, and will then be
  995 able to fill in the ambiguity in the size of the instruction
  996 <code>mov var,2</code>, NASM will deliberately remember nothing about the
  997 symbol <code>var</code> except where it begins, and so you must explicitly
  998 code <code>mov word [var],2</code>.</p>
  999 <p>For this reason, NASM doesn't support the <code>LODS</code>,
 1000 <code>MOVS</code>, <code>STOS</code>, <code>SCAS</code>, <code>CMPS</code>,
 1001 <code>INS</code>, or <code>OUTS</code> instructions, but only supports the
 1002 forms such as <code>LODSB</code>, <code>MOVSW</code>, and
 1003 <code>SCASD</code>, which explicitly specify the size of the components of
 1004 the strings being manipulated.</p>
 1005 <h4 id="section-2.2.4">2.2.4 NASM Doesn't <code>ASSUME</code></h4>
 1006 <p>As part of NASM's drive for simplicity, it also does not support the
 1007 <code>ASSUME</code> directive. NASM will not keep track of what values you
 1008 choose to put in your segment registers, and will never
 1009 <em>automatically</em> generate a segment override prefix.</p>
 1010 <h4 id="section-2.2.5">2.2.5 NASM Doesn't Support Memory Models</h4>
 1011 <p>NASM also does not have any directives to support different 16-bit
 1012 memory models. The programmer has to keep track of which functions are
 1013 supposed to be called with a far call and which with a near call, and is
 1014 responsible for putting the correct form of <code>RET</code> instruction
 1015 (<code>RETN</code> or <code>RETF</code>; NASM accepts <code>RET</code>
 1016 itself as an alternate form for <code>RETN</code>); in addition, the
 1017 programmer is responsible for coding CALL FAR instructions where necessary
 1018 when calling <em>external</em> functions, and must also keep track of which
 1019 external variable definitions are far and which are near.</p>
 1020 <h4 id="section-2.2.6">2.2.6 Floating-Point Differences</h4>
 1021 <p>NASM uses different names to refer to floating-point registers from
 1022 MASM: where MASM would call them <code>ST(0)</code>, <code>ST(1)</code> and
 1023 so on, and <code>a86</code> would call them simply <code>0</code>,
 1024 <code>1</code> and so on, NASM chooses to call them <code>st0</code>,
 1025 <code>st1</code> etc.</p>
 1026 <p>As of version 0.96, NASM now treats the instructions with `nowait' forms
 1027 in the same way as MASM-compatible assemblers. The idiosyncratic treatment
 1028 employed by 0.95 and earlier was based on a misunderstanding by the
 1029 authors.</p>
 1030 <h4 id="section-2.2.7">2.2.7 Other Differences</h4>
 1031 <p>For historical reasons, NASM uses the keyword <code>TWORD</code> where
 1032 MASM and compatible assemblers use <code>TBYTE</code>.</p>
 1033 <p>Historically, NASM does not declare uninitialized storage in the same
 1034 way as MASM: where a MASM programmer might use
 1035 <code>stack db 64 dup (?)</code>, NASM requires <code>stack resb 64</code>,
 1036 intended to be read as `reserve 64 bytes'. For a limited amount of
 1037 compatibility, since NASM treats <code>?</code> as a valid character in
 1038 symbol names, you can code <code>? equ 0</code> and then writing
 1039 <code>dw ?</code> will at least do something vaguely useful.</p>
 1040 <p>As of NASM 2.15, the MASM syntax is also supported.</p>
 1041 <p>In addition to all of this, macros and directives work completely
 1042 differently to MASM. See <a href="nasmdoc4.html">chapter 4</a> and
 1043 <a href="nasmdoc7.html">chapter 7</a> for further details.</p>
 1044 <h4 id="section-2.2.8">2.2.8 MASM compatibility package</h4>
 1045 <p>See <a href="nasmdoc6.html#section-6.5">section 6.5</a>.</p>
 1046 </div>
 1047 </body>
 1048 </html>