diff options
Diffstat (limited to 'doc/html/nasmdoc2.html')
| -rw-r--r-- | doc/html/nasmdoc2.html | 650 |
1 files changed, 650 insertions, 0 deletions
diff --git a/doc/html/nasmdoc2.html b/doc/html/nasmdoc2.html new file mode 100644 index 0000000..a639a4a --- /dev/null +++ b/doc/html/nasmdoc2.html @@ -0,0 +1,650 @@ +<html><head><title>NASM Manual</title></head> +<body><h1 align=center>The Netwide Assembler: NASM</h1> + +<p align=center><a href="nasmdoc3.html">Next Chapter</a> | +<a href="nasmdoc1.html">Previous Chapter</a> | +<a href="nasmdoc0.html">Contents</a> | +<a href="nasmdoci.html">Index</a> +<h2><a name="chapter-2">Chapter 2: Running NASM</a></h2> +<h3><a name="section-2.1">2.1 NASM Command-Line Syntax</a></h3> +<p>To assemble a file, you issue a command of the form +<p><pre> +nasm -f <format> <filename> [-o <output>] +</pre> +<p>For example, +<p><pre> +nasm -f elf myfile.asm +</pre> +<p>will assemble <code><nobr>myfile.asm</nobr></code> into an +<code><nobr>ELF</nobr></code> object file +<code><nobr>myfile.o</nobr></code>. And +<p><pre> +nasm -f bin myfile.asm -o myfile.com +</pre> +<p>will assemble <code><nobr>myfile.asm</nobr></code> into a raw binary +file <code><nobr>myfile.com</nobr></code>. +<p>To produce a listing file, with the hex codes output from NASM displayed +on the left of the original sources, use the <code><nobr>-l</nobr></code> +option to give a listing file name, for example: +<p><pre> +nasm -f coff myfile.asm -l myfile.lst +</pre> +<p>To get further usage instructions from NASM, try typing +<p><pre> +nasm -h +</pre> +<p>As <code><nobr>-hf</nobr></code>, this will also list the available +output file formats, and what they are. +<p>If you use Linux but aren't sure whether your system is +<code><nobr>a.out</nobr></code> or <code><nobr>ELF</nobr></code>, type +<p><pre> +file nasm +</pre> +<p>(in the directory in which you put the NASM binary when you installed +it). If it says something like +<p><pre> +nasm: ELF 32-bit LSB executable i386 (386 and up) Version 1 +</pre> +<p>then your system is <code><nobr>ELF</nobr></code>, and you should use +the option <code><nobr>-f elf</nobr></code> when you want NASM to produce +Linux object files. If it says +<p><pre> +nasm: Linux/i386 demand-paged executable (QMAGIC) +</pre> +<p>or something similar, your system is <code><nobr>a.out</nobr></code>, +and you should use <code><nobr>-f aout</nobr></code> instead (Linux +<code><nobr>a.out</nobr></code> systems have long been obsolete, and are +rare these days.) +<p>Like Unix compilers and assemblers, NASM is silent unless it goes wrong: +you won't see any output at all, unless it gives error messages. +<h4><a name="section-2.1.1">2.1.1 The <code><nobr>-o</nobr></code> Option: Specifying the Output File Name</a></h4> +<p>NASM will normally choose the name of your output file for you; +precisely how it does this is dependent on the object file format. For +Microsoft object file formats (<code><nobr>obj</nobr></code>, +<code><nobr>win32</nobr></code> and <code><nobr>win64</nobr></code>), it +will remove the <code><nobr>.asm</nobr></code> extension (or whatever +extension you like to use - NASM doesn't care) from your source file name +and substitute <code><nobr>.obj</nobr></code>. For Unix object file formats +(<code><nobr>aout</nobr></code>, <code><nobr>as86</nobr></code>, +<code><nobr>coff</nobr></code>, <code><nobr>elf32</nobr></code>, +<code><nobr>elf64</nobr></code>, <code><nobr>ieee</nobr></code>, +<code><nobr>macho32</nobr></code> and <code><nobr>macho64</nobr></code>) it +will substitute <code><nobr>.o</nobr></code>. For +<code><nobr>dbg</nobr></code>, <code><nobr>rdf</nobr></code>, +<code><nobr>ith</nobr></code> and <code><nobr>srec</nobr></code>, it will +use <code><nobr>.dbg</nobr></code>, <code><nobr>.rdf</nobr></code>, +<code><nobr>.ith</nobr></code> and <code><nobr>.srec</nobr></code>, +respectively, and for the <code><nobr>bin</nobr></code> format it will +simply remove the extension, so that <code><nobr>myfile.asm</nobr></code> +produces the output file <code><nobr>myfile</nobr></code>. +<p>If the output file already exists, NASM will overwrite it, unless it has +the same name as the input file, in which case it will give a warning and +use <code><nobr>nasm.out</nobr></code> as the output file name instead. +<p>For situations in which this behaviour is unacceptable, NASM provides +the <code><nobr>-o</nobr></code> command-line option, which allows you to +specify your desired output file name. You invoke +<code><nobr>-o</nobr></code> by following it with the name you wish for the +output file, either with or without an intervening space. For example: +<p><pre> +nasm -f bin program.asm -o program.com +nasm -f bin driver.asm -odriver.sys +</pre> +<p>Note that this is a small o, and is different from a capital O , which +is used to specify the number of optimisation passes required. See +<a href="#section-2.1.22">section 2.1.22</a>. +<h4><a name="section-2.1.2">2.1.2 The <code><nobr>-f</nobr></code> Option: Specifying the Output File Format</a></h4> +<p>If you do not supply the <code><nobr>-f</nobr></code> option to NASM, it +will choose an output file format for you itself. In the distribution +versions of NASM, the default is always <code><nobr>bin</nobr></code>; if +you've compiled your own copy of NASM, you can redefine +<code><nobr>OF_DEFAULT</nobr></code> at compile time and choose what you +want the default to be. +<p>Like <code><nobr>-o</nobr></code>, the intervening space between +<code><nobr>-f</nobr></code> and the output file format is optional; so +<code><nobr>-f elf</nobr></code> and <code><nobr>-felf</nobr></code> are +both valid. +<p>A complete list of the available output file formats can be given by +issuing the command <code><nobr>nasm -hf</nobr></code>. +<h4><a name="section-2.1.3">2.1.3 The <code><nobr>-l</nobr></code> Option: Generating a Listing File</a></h4> +<p>If you supply the <code><nobr>-l</nobr></code> option to NASM, followed +(with the usual optional space) by a file name, NASM will generate a +source-listing file for you, in which addresses and generated code are +listed on the left, and the actual source code, with expansions of +multi-line macros (except those which specifically request no expansion in +source listings: see <a href="nasmdoc4.html#section-4.3.10">section +4.3.10</a>) on the right. For example: +<p><pre> +nasm -f elf myfile.asm -l myfile.lst +</pre> +<p>If a list file is selected, you may turn off listing for a section of +your source with <code><nobr>[list -]</nobr></code>, and turn it back on +with <code><nobr>[list +]</nobr></code>, (the default, obviously). There is +no "user form" (without the brackets). This can be used to list only +sections of interest, avoiding excessively long listings. +<h4><a name="section-2.1.4">2.1.4 The <code><nobr>-M</nobr></code> Option: Generate Makefile Dependencies</a></h4> +<p>This option can be used to generate makefile dependencies on stdout. +This can be redirected to a file for further processing. For example: +<p><pre> +nasm -M myfile.asm > myfile.dep +</pre> +<h4><a name="section-2.1.5">2.1.5 The <code><nobr>-MG</nobr></code> Option: Generate Makefile Dependencies</a></h4> +<p>This option can be used to generate makefile dependencies on stdout. +This differs from the <code><nobr>-M</nobr></code> option in that if a +nonexisting file is encountered, it is assumed to be a generated file and +is added to the dependency list without a prefix. +<h4><a name="section-2.1.6">2.1.6 The <code><nobr>-MF</nobr></code> Option: Set Makefile Dependency File</a></h4> +<p>This option can be used with the <code><nobr>-M</nobr></code> or +<code><nobr>-MG</nobr></code> options to send the output to a file, rather +than to stdout. For example: +<p><pre> +nasm -M -MF myfile.dep myfile.asm +</pre> +<h4><a name="section-2.1.7">2.1.7 The <code><nobr>-MD</nobr></code> Option: Assemble and Generate Dependencies</a></h4> +<p>The <code><nobr>-MD</nobr></code> option acts as the combination of the +<code><nobr>-M</nobr></code> and <code><nobr>-MF</nobr></code> options +(i.e. a filename has to be specified.) However, unlike the +<code><nobr>-M</nobr></code> or <code><nobr>-MG</nobr></code> options, +<code><nobr>-MD</nobr></code> does <em>not</em> inhibit the normal +operation of the assembler. Use this to automatically generate updated +dependencies with every assembly session. For example: +<p><pre> +nasm -f elf -o myfile.o -MD myfile.dep myfile.asm +</pre> +<h4><a name="section-2.1.8">2.1.8 The <code><nobr>-MT</nobr></code> Option: Dependency Target Name</a></h4> +<p>The <code><nobr>-MT</nobr></code> option can be used to override the +default name of the dependency target. This is normally the same as the +output filename, specified by the <code><nobr>-o</nobr></code> option. +<h4><a name="section-2.1.9">2.1.9 The <code><nobr>-MQ</nobr></code> Option: Dependency Target Name (Quoted)</a></h4> +<p>The <code><nobr>-MQ</nobr></code> option acts as the +<code><nobr>-MT</nobr></code> option, except it tries to quote characters +that have special meaning in Makefile syntax. This is not foolproof, as not +all characters with special meaning are quotable in Make. +<h4><a name="section-2.1.10">2.1.10 The <code><nobr>-MP</nobr></code> Option: Emit phony targets</a></h4> +<p>When used with any of the dependency generation options, the +<code><nobr>-MP</nobr></code> option causes NASM to emit a phony target +without dependencies for each header file. This prevents Make from +complaining if a header file has been removed. +<h4><a name="section-2.1.11">2.1.11 The <code><nobr>-F</nobr></code> Option: Selecting a Debug Information Format</a></h4> +<p>This option is used to select the format of the debug information +emitted into the output file, to be used by a debugger (or <em>will</em> +be). Prior to version 2.03.01, the use of this switch did <em>not</em> +enable output of the selected debug info format. Use +<code><nobr>-g</nobr></code>, see <a href="#section-2.1.12">section +2.1.12</a>, to enable output. Versions 2.03.01 and later automatically +enable <code><nobr>-g</nobr></code> if <code><nobr>-F</nobr></code> is +specified. +<p>A complete list of the available debug file formats for an output format +can be seen by issuing the command +<code><nobr>nasm -f <format> -y</nobr></code>. Not all output formats +currently support debugging output. See <a href="#section-2.1.26">section +2.1.26</a>. +<p>This should not be confused with the <code><nobr>-f dbg</nobr></code> +output format option which is not built into NASM by default. For +information on how to enable it when building from the sources, see +<a href="nasmdoc7.html#section-7.14">section 7.14</a>. +<h4><a name="section-2.1.12">2.1.12 The <code><nobr>-g</nobr></code> Option: Enabling Debug Information.</a></h4> +<p>This option can be used to generate debugging information in the +specified format. See <a href="#section-2.1.11">section 2.1.11</a>. Using +<code><nobr>-g</nobr></code> without <code><nobr>-F</nobr></code> results +in emitting debug info in the default format, if any, for the selected +output format. If no debug information is currently implemented in the +selected output format, <code><nobr>-g</nobr></code> is <em>silently +ignored</em>. +<h4><a name="section-2.1.13">2.1.13 The <code><nobr>-X</nobr></code> Option: Selecting an Error Reporting Format</a></h4> +<p>This option can be used to select an error reporting format for any +error messages that might be produced by NASM. +<p>Currently, two error reporting formats may be selected. They are the +<code><nobr>-Xvc</nobr></code> option and the +<code><nobr>-Xgnu</nobr></code> option. The GNU format is the default and +looks like this: +<p><pre> +filename.asm:65: error: specific error message +</pre> +<p>where <code><nobr>filename.asm</nobr></code> is the name of the source +file in which the error was detected, <code><nobr>65</nobr></code> is the +source file line number on which the error was detected, +<code><nobr>error</nobr></code> is the severity of the error (this could be +<code><nobr>warning</nobr></code>), and +<code><nobr>specific error message</nobr></code> is a more detailed text +message which should help pinpoint the exact problem. +<p>The other format, specified by <code><nobr>-Xvc</nobr></code> is the +style used by Microsoft Visual C++ and some other programs. It looks like +this: +<p><pre> +filename.asm(65) : error: specific error message +</pre> +<p>where the only difference is that the line number is in parentheses +instead of being delimited by colons. +<p>See also the <code><nobr>Visual C++</nobr></code> output format, +<a href="nasmdoc7.html#section-7.5">section 7.5</a>. +<h4><a name="section-2.1.14">2.1.14 The <code><nobr>-Z</nobr></code> Option: Send Errors to a File</a></h4> +<p>Under <code><nobr>MS-DOS</nobr></code> it can be difficult (though there +are ways) to redirect the standard-error output of a program to a file. +Since NASM usually produces its warning and error messages on +<code><nobr>stderr</nobr></code>, this can make it hard to capture the +errors if (for example) you want to load them into an editor. +<p>NASM therefore provides the <code><nobr>-Z</nobr></code> option, taking +a filename argument which causes errors to be sent to the specified files +rather than standard error. Therefore you can redirect the errors into a +file by typing +<p><pre> +nasm -Z myfile.err -f obj myfile.asm +</pre> +<p>In earlier versions of NASM, this option was called +<code><nobr>-E</nobr></code>, but it was changed since +<code><nobr>-E</nobr></code> is an option conventionally used for +preprocessing only, with disastrous results. See +<a href="#section-2.1.20">section 2.1.20</a>. +<h4><a name="section-2.1.15">2.1.15 The <code><nobr>-s</nobr></code> Option: Send Errors to <code><nobr>stdout</nobr></code></a></h4> +<p>The <code><nobr>-s</nobr></code> option redirects error messages to +<code><nobr>stdout</nobr></code> rather than +<code><nobr>stderr</nobr></code>, so it can be redirected under +<code><nobr>MS-DOS</nobr></code>. To assemble the file +<code><nobr>myfile.asm</nobr></code> and pipe its output to the +<code><nobr>more</nobr></code> program, you can type: +<p><pre> +nasm -s -f obj myfile.asm | more +</pre> +<p>See also the <code><nobr>-Z</nobr></code> option, +<a href="#section-2.1.14">section 2.1.14</a>. +<h4><a name="section-2.1.16">2.1.16 The <code><nobr>-i</nobr></code> Option: Include File Search Directories</a></h4> +<p>When NASM sees the <code><nobr>%include</nobr></code> or +<code><nobr>%pathsearch</nobr></code> directive in a source file (see +<a href="nasmdoc4.html#section-4.6.1">section 4.6.1</a>, +<a href="nasmdoc4.html#section-4.6.2">section 4.6.2</a> or +<a href="nasmdoc3.html#section-3.2.3">section 3.2.3</a>), it will search +for the given file not only in the current directory, but also in any +directories specified on the command line by the use of the +<code><nobr>-i</nobr></code> option. Therefore you can include files from a +macro library, for example, by typing +<p><pre> +nasm -ic:\macrolib\ -f obj myfile.asm +</pre> +<p>(As usual, a space between <code><nobr>-i</nobr></code> and the path +name is allowed, and optional). +<p>NASM, in the interests of complete source-code portability, does not +understand the file naming conventions of the OS it is running on; the +string you provide as an argument to the <code><nobr>-i</nobr></code> +option will be prepended exactly as written to the name of the include +file. Therefore the trailing backslash in the above example is necessary. +Under Unix, a trailing forward slash is similarly necessary. +<p>(You can use this to your advantage, if you're really perverse, by +noting that the option <code><nobr>-ifoo</nobr></code> will cause +<code><nobr>%include "bar.i"</nobr></code> to search for the file +<code><nobr>foobar.i</nobr></code>...) +<p>If you want to define a <em>standard</em> include search path, similar +to <code><nobr>/usr/include</nobr></code> on Unix systems, you should place +one or more <code><nobr>-i</nobr></code> directives in the +<code><nobr>NASMENV</nobr></code> environment variable (see +<a href="#section-2.1.28">section 2.1.28</a>). +<p>For Makefile compatibility with many C compilers, this option can also +be specified as <code><nobr>-I</nobr></code>. +<h4><a name="section-2.1.17">2.1.17 The <code><nobr>-p</nobr></code> Option: Pre-Include a File</a></h4> +<p>NASM allows you to specify files to be <em>pre-included</em> into your +source file, by the use of the <code><nobr>-p</nobr></code> option. So +running +<p><pre> +nasm myfile.asm -p myinc.inc +</pre> +<p>is equivalent to running <code><nobr>nasm myfile.asm</nobr></code> and +placing the directive <code><nobr>%include "myinc.inc"</nobr></code> at the +start of the file. +<p>For consistency with the <code><nobr>-I</nobr></code>, +<code><nobr>-D</nobr></code> and <code><nobr>-U</nobr></code> options, this +option can also be specified as <code><nobr>-P</nobr></code>. +<h4><a name="section-2.1.18">2.1.18 The <code><nobr>-d</nobr></code> Option: Pre-Define a Macro</a></h4> +<p>Just as the <code><nobr>-p</nobr></code> option gives an alternative to +placing <code><nobr>%include</nobr></code> directives at the start of a +source file, the <code><nobr>-d</nobr></code> option gives an alternative +to placing a <code><nobr>%define</nobr></code> directive. You could code +<p><pre> +nasm myfile.asm -dFOO=100 +</pre> +<p>as an alternative to placing the directive +<p><pre> +%define FOO 100 +</pre> +<p>at the start of the file. You can miss off the macro value, as well: the +option <code><nobr>-dFOO</nobr></code> is equivalent to coding +<code><nobr>%define FOO</nobr></code>. This form of the directive may be +useful for selecting assembly-time options which are then tested using +<code><nobr>%ifdef</nobr></code>, for example +<code><nobr>-dDEBUG</nobr></code>. +<p>For Makefile compatibility with many C compilers, this option can also +be specified as <code><nobr>-D</nobr></code>. +<h4><a name="section-2.1.19">2.1.19 The <code><nobr>-u</nobr></code> Option: Undefine a Macro</a></h4> +<p>The <code><nobr>-u</nobr></code> option undefines a macro that would +otherwise have been pre-defined, either automatically or by a +<code><nobr>-p</nobr></code> or <code><nobr>-d</nobr></code> option +specified earlier on the command lines. +<p>For example, the following command line: +<p><pre> +nasm myfile.asm -dFOO=100 -uFOO +</pre> +<p>would result in <code><nobr>FOO</nobr></code> <em>not</em> being a +predefined macro in the program. This is useful to override options +specified at a different point in a Makefile. +<p>For Makefile compatibility with many C compilers, this option can also +be specified as <code><nobr>-U</nobr></code>. +<h4><a name="section-2.1.20">2.1.20 The <code><nobr>-E</nobr></code> Option: Preprocess Only</a></h4> +<p>NASM allows the preprocessor to be run on its own, up to a point. Using +the <code><nobr>-E</nobr></code> option (which requires no arguments) will +cause NASM to preprocess its input file, expand all the macro references, +remove all the comments and preprocessor directives, and print the +resulting file on standard output (or save it to a file, if the +<code><nobr>-o</nobr></code> option is also used). +<p>This option cannot be applied to programs which require the preprocessor +to evaluate expressions which depend on the values of symbols: so code such +as +<p><pre> +%assign tablesize ($-tablestart) +</pre> +<p>will cause an error in preprocess-only mode. +<p>For compatiblity with older version of NASM, this option can also be +written <code><nobr>-e</nobr></code>. <code><nobr>-E</nobr></code> in older +versions of NASM was the equivalent of the current +<code><nobr>-Z</nobr></code> option, <a href="#section-2.1.14">section +2.1.14</a>. +<h4><a name="section-2.1.21">2.1.21 The <code><nobr>-a</nobr></code> Option: Don't Preprocess At All</a></h4> +<p>If NASM is being used as the back end to a compiler, it might be +desirable to suppress preprocessing completely and assume the compiler has +already done it, to save time and increase compilation speeds. The +<code><nobr>-a</nobr></code> option, requiring no argument, instructs NASM +to replace its powerful preprocessor with a stub preprocessor which does +nothing. +<h4><a name="section-2.1.22">2.1.22 The <code><nobr>-O</nobr></code> Option: Specifying Multipass Optimization</a></h4> +<p>NASM defaults to not optimizing operands which can fit into a signed +byte. This means that if you want the shortest possible object code, you +have to enable optimization. +<p>Using the <code><nobr>-O</nobr></code> option, you can tell NASM to +carry out different levels of optimization. The syntax is: +<ul> +<li><code><nobr>-O0</nobr></code>: No optimization. All operands take their +long forms, if a short form is not specified, except conditional jumps. +This is intended to match NASM 0.98 behavior. +<li><code><nobr>-O1</nobr></code>: Minimal optimization. As above, but +immediate operands which will fit in a signed byte are optimized, unless +the long form is specified. Conditional jumps default to the long form +unless otherwise specified. +<li><code><nobr>-Ox</nobr></code> (where <code><nobr>x</nobr></code> is the +actual letter <code><nobr>x</nobr></code>): Multipass optimization. +Minimize branch offsets and signed immediate bytes, overriding size +specification unless the <code><nobr>strict</nobr></code> keyword has been +used (see <a href="nasmdoc3.html#section-3.7">section 3.7</a>). For +compatability with earlier releases, the letter <code><nobr>x</nobr></code> +may also be any number greater than one. This number has no effect on the +actual number of passes. +</ul> +<p>The <code><nobr>-Ox</nobr></code> mode is recommended for most uses. +<p>Note that this is a capital <code><nobr>O</nobr></code>, and is +different from a small <code><nobr>o</nobr></code>, which is used to +specify the output file name. See <a href="#section-2.1.1">section +2.1.1</a>. +<h4><a name="section-2.1.23">2.1.23 The <code><nobr>-t</nobr></code> Option: Enable TASM Compatibility Mode</a></h4> +<p>NASM includes a limited form of compatibility with Borland's +<code><nobr>TASM</nobr></code>. When NASM's <code><nobr>-t</nobr></code> +option is used, the following changes are made: +<ul> +<li>local labels may be prefixed with <code><nobr>@@</nobr></code> instead +of <code><nobr>.</nobr></code> +<li>size override is supported within brackets. In TASM compatible mode, a +size override inside square brackets changes the size of the operand, and +not the address type of the operand as it does in NASM syntax. E.g. +<code><nobr>mov eax,[DWORD val]</nobr></code> is valid syntax in TASM +compatibility mode. Note that you lose the ability to override the default +address type for the instruction. +<li>unprefixed forms of some directives supported +(<code><nobr>arg</nobr></code>, <code><nobr>elif</nobr></code>, +<code><nobr>else</nobr></code>, <code><nobr>endif</nobr></code>, +<code><nobr>if</nobr></code>, <code><nobr>ifdef</nobr></code>, +<code><nobr>ifdifi</nobr></code>, <code><nobr>ifndef</nobr></code>, +<code><nobr>include</nobr></code>, <code><nobr>local</nobr></code>) +</ul> +<h4><a name="section-2.1.24">2.1.24 The <code><nobr>-w</nobr></code> and <code><nobr>-W</nobr></code> Options: Enable or Disable Assembly Warnings</a></h4> +<p>NASM can observe many conditions during the course of assembly which are +worth mentioning to the user, but not a sufficiently severe error to +justify NASM refusing to generate an output file. These conditions are +reported like errors, but come up with the word `warning' before the +message. Warnings do not prevent NASM from generating an output file and +returning a success status to the operating system. +<p>Some conditions are even less severe than that: they are only sometimes +worth mentioning to the user. Therefore NASM supports the +<code><nobr>-w</nobr></code> command-line option, which enables or disables +certain classes of assembly warning. Such warning classes are described by +a name, for example <code><nobr>orphan-labels</nobr></code>; you can enable +warnings of this class by the command-line option +<code><nobr>-w+orphan-labels</nobr></code> and disable it by +<code><nobr>-w-orphan-labels</nobr></code>. +<p>The suppressible warning classes are: +<ul> +<li><code><nobr>macro-params</nobr></code> covers warnings about multi-line +macros being invoked with the wrong number of parameters. This warning +class is enabled by default; see +<a href="nasmdoc4.html#section-4.3.2">section 4.3.2</a> for an example of +why you might want to disable it. +<li><code><nobr>macro-selfref</nobr></code> warns if a macro references +itself. This warning class is disabled by default. +<li><code><nobr>macro-defaults</nobr></code> warns when a macro has more +default parameters than optional parameters. This warning class is enabled +by default; see <a href="nasmdoc4.html#section-4.3.5">section 4.3.5</a> for +why you might want to disable it. +<li><code><nobr>orphan-labels</nobr></code> covers warnings about source +lines which contain no instruction but define a label without a trailing +colon. NASM warns about this somewhat obscure condition by default; see +<a href="nasmdoc3.html#section-3.1">section 3.1</a> for more information. +<li><code><nobr>number-overflow</nobr></code> covers warnings about numeric +constants which don't fit in 64 bits. This warning class is enabled by +default. +<li><code><nobr>gnu-elf-extensions</nobr></code> warns if 8-bit or 16-bit +relocations are used in <code><nobr>-f elf</nobr></code> format. The GNU +extensions allow this. This warning class is disabled by default. +<li><code><nobr>float-overflow</nobr></code> warns about floating point +overflow. Enabled by default. +<li><code><nobr>float-denorm</nobr></code> warns about floating point +denormals. Disabled by default. +<li><code><nobr>float-underflow</nobr></code> warns about floating point +underflow. Disabled by default. +<li><code><nobr>float-toolong</nobr></code> warns about too many digits in +floating-point numbers. Enabled by default. +<li><code><nobr>user</nobr></code> controls +<code><nobr>%warning</nobr></code> directives (see +<a href="nasmdoc4.html#section-4.9">section 4.9</a>). Enabled by default. +<li><code><nobr>error</nobr></code> causes warnings to be treated as +errors. Disabled by default. +<li><code><nobr>all</nobr></code> is an alias for <em>all</em> suppressible +warning classes (not including <code><nobr>error</nobr></code>). Thus, +<code><nobr>-w+all</nobr></code> enables all available warnings. +</ul> +<p>In addition, you can set warning classes across sections. Warning +classes may be enabled with +<code><nobr>[warning +warning-name]</nobr></code>, disabled with +<code><nobr>[warning -warning-name]</nobr></code> or reset to their +original value with <code><nobr>[warning *warning-name]</nobr></code>. No +"user form" (without the brackets) exists. +<p>Since version 2.00, NASM has also supported the gcc-like syntax +<code><nobr>-Wwarning</nobr></code> and +<code><nobr>-Wno-warning</nobr></code> instead of +<code><nobr>-w+warning</nobr></code> and +<code><nobr>-w-warning</nobr></code>, respectively. +<h4><a name="section-2.1.25">2.1.25 The <code><nobr>-v</nobr></code> Option: Display Version Info</a></h4> +<p>Typing <code><nobr>NASM -v</nobr></code> will display the version of +NASM which you are using, and the date on which it was compiled. +<p>You will need the version number if you report a bug. +<h4><a name="section-2.1.26">2.1.26 The <code><nobr>-y</nobr></code> Option: Display Available Debug Info Formats</a></h4> +<p>Typing <code><nobr>nasm -f <option> -y</nobr></code> will display +a list of the available debug info formats for the given output format. The +default format is indicated by an asterisk. For example: +<p><pre> +nasm -f elf -y +</pre> +<p><pre> +valid debug formats for 'elf32' output format are + ('*' denotes default): + * stabs ELF32 (i386) stabs debug format for Linux + dwarf elf32 (i386) dwarf debug format for Linux +</pre> +<h4><a name="section-2.1.27">2.1.27 The <code><nobr>--prefix</nobr></code> and <code><nobr>--postfix</nobr></code> Options.</a></h4> +<p>The <code><nobr>--prefix</nobr></code> and +<code><nobr>--postfix</nobr></code> options prepend or append +(respectively) the given argument to all <code><nobr>global</nobr></code> +or <code><nobr>extern</nobr></code> variables. E.g. +<code><nobr>--prefix _</nobr></code> will prepend the underscore to all +global and external variables, as C sometimes (but not always) likes it. +<h4><a name="section-2.1.28">2.1.28 The <code><nobr>NASMENV</nobr></code> Environment Variable</a></h4> +<p>If you define an environment variable called +<code><nobr>NASMENV</nobr></code>, the program will interpret it as a list +of extra command-line options, which are processed before the real command +line. You can use this to define standard search directories for include +files, by putting <code><nobr>-i</nobr></code> options in the +<code><nobr>NASMENV</nobr></code> variable. +<p>The value of the variable is split up at white space, so that the value +<code><nobr>-s -ic:\nasmlib\</nobr></code> will be treated as two separate +options. However, that means that the value +<code><nobr>-dNAME="my name"</nobr></code> won't do what you might want, +because it will be split at the space and the NASM command-line processing +will get confused by the two nonsensical words +<code><nobr>-dNAME="my</nobr></code> and <code><nobr>name"</nobr></code>. +<p>To get round this, NASM provides a feature whereby, if you begin the +<code><nobr>NASMENV</nobr></code> environment variable with some character +that isn't a minus sign, then NASM will treat this character as the +separator character for options. So setting the +<code><nobr>NASMENV</nobr></code> variable to the value +<code><nobr>!-s!-ic:\nasmlib\</nobr></code> is equivalent to setting it to +<code><nobr>-s -ic:\nasmlib\</nobr></code>, but +<code><nobr>!-dNAME="my name"</nobr></code> will work. +<p>This environment variable was previously called +<code><nobr>NASM</nobr></code>. This was changed with version 0.98.31. +<h3><a name="section-2.2">2.2 Quick Start for MASM Users</a></h3> +<p>If you're used to writing programs with MASM, or with TASM in +MASM-compatible (non-Ideal) mode, or with <code><nobr>a86</nobr></code>, +this section attempts to outline the major differences between MASM's +syntax and NASM's. If you're not already used to MASM, it's probably worth +skipping this section. +<h4><a name="section-2.2.1">2.2.1 NASM Is Case-Sensitive</a></h4> +<p>One simple difference is that NASM is case-sensitive. It makes a +difference whether you call your label <code><nobr>foo</nobr></code>, +<code><nobr>Foo</nobr></code> or <code><nobr>FOO</nobr></code>. If you're +assembling to <code><nobr>DOS</nobr></code> or +<code><nobr>OS/2</nobr></code> <code><nobr>.OBJ</nobr></code> files, you +can invoke the <code><nobr>UPPERCASE</nobr></code> directive (documented in +<a href="nasmdoc7.html#section-7.4">section 7.4</a>) to ensure that all +symbols exported to other code modules are forced to be upper case; but +even then, <em>within</em> a single module, NASM will distinguish between +labels differing only in case. +<h4><a name="section-2.2.2">2.2.2 NASM Requires Square Brackets For Memory References</a></h4> +<p>NASM was designed with simplicity of syntax in mind. One of the design +goals of NASM is that it should be possible, as far as is practical, for +the user to look at a single line of NASM code and tell what opcode is +generated by it. You can't do this in MASM: if you declare, for example, +<p><pre> +foo equ 1 +bar dw 2 +</pre> +<p>then the two lines of code +<p><pre> + mov ax,foo + mov ax,bar +</pre> +<p>generate completely different opcodes, despite having identical-looking +syntaxes. +<p>NASM avoids this undesirable situation by having a much simpler syntax +for memory references. The rule is simply that any access to the +<em>contents</em> of a memory location requires square brackets around the +address, and any access to the <em>address</em> of a variable doesn't. So +an instruction of the form <code><nobr>mov ax,foo</nobr></code> will +<em>always</em> refer to a compile-time constant, whether it's an +<code><nobr>EQU</nobr></code> or the address of a variable; and to access +the <em>contents</em> of the variable <code><nobr>bar</nobr></code>, you +must code <code><nobr>mov ax,[bar]</nobr></code>. +<p>This also means that NASM has no need for MASM's +<code><nobr>OFFSET</nobr></code> keyword, since the MASM code +<code><nobr>mov ax,offset bar</nobr></code> means exactly the same thing as +NASM's <code><nobr>mov ax,bar</nobr></code>. If you're trying to get large +amounts of MASM code to assemble sensibly under NASM, you can always code +<code><nobr>%idefine offset</nobr></code> to make the preprocessor treat +the <code><nobr>OFFSET</nobr></code> keyword as a no-op. +<p>This issue is even more confusing in <code><nobr>a86</nobr></code>, +where declaring a label with a trailing colon defines it to be a `label' as +opposed to a `variable' and causes <code><nobr>a86</nobr></code> to adopt +NASM-style semantics; so in <code><nobr>a86</nobr></code>, +<code><nobr>mov ax,var</nobr></code> has different behaviour depending on +whether <code><nobr>var</nobr></code> was declared as +<code><nobr>var: dw 0</nobr></code> (a label) or +<code><nobr>var dw 0</nobr></code> (a word-size variable). NASM is very +simple by comparison: <em>everything</em> is a label. +<p>NASM, in the interests of simplicity, also does not support the hybrid +syntaxes supported by MASM and its clones, such as +<code><nobr>mov ax,table[bx]</nobr></code>, where a memory reference is +denoted by one portion outside square brackets and another portion inside. +The correct syntax for the above is +<code><nobr>mov ax,[table+bx]</nobr></code>. Likewise, +<code><nobr>mov ax,es:[di]</nobr></code> is wrong and +<code><nobr>mov ax,[es:di]</nobr></code> is right. +<h4><a name="section-2.2.3">2.2.3 NASM Doesn't Store Variable Types</a></h4> +<p>NASM, by design, chooses not to remember the types of variables you +declare. Whereas MASM will remember, on seeing +<code><nobr>var dw 0</nobr></code>, that you declared +<code><nobr>var</nobr></code> as a word-size variable, and will then be +able to fill in the ambiguity in the size of the instruction +<code><nobr>mov var,2</nobr></code>, NASM will deliberately remember +nothing about the symbol <code><nobr>var</nobr></code> except where it +begins, and so you must explicitly code +<code><nobr>mov word [var],2</nobr></code>. +<p>For this reason, NASM doesn't support the +<code><nobr>LODS</nobr></code>, <code><nobr>MOVS</nobr></code>, +<code><nobr>STOS</nobr></code>, <code><nobr>SCAS</nobr></code>, +<code><nobr>CMPS</nobr></code>, <code><nobr>INS</nobr></code>, or +<code><nobr>OUTS</nobr></code> instructions, but only supports the forms +such as <code><nobr>LODSB</nobr></code>, <code><nobr>MOVSW</nobr></code>, +and <code><nobr>SCASD</nobr></code>, which explicitly specify the size of +the components of the strings being manipulated. +<h4><a name="section-2.2.4">2.2.4 NASM Doesn't <code><nobr>ASSUME</nobr></code></a></h4> +<p>As part of NASM's drive for simplicity, it also does not support the +<code><nobr>ASSUME</nobr></code> directive. NASM will not keep track of +what values you choose to put in your segment registers, and will never +<em>automatically</em> generate a segment override prefix. +<h4><a name="section-2.2.5">2.2.5 NASM Doesn't Support Memory Models</a></h4> +<p>NASM also does not have any directives to support different 16-bit +memory models. The programmer has to keep track of which functions are +supposed to be called with a far call and which with a near call, and is +responsible for putting the correct form of <code><nobr>RET</nobr></code> +instruction (<code><nobr>RETN</nobr></code> or +<code><nobr>RETF</nobr></code>; NASM accepts <code><nobr>RET</nobr></code> +itself as an alternate form for <code><nobr>RETN</nobr></code>); in +addition, the programmer is responsible for coding CALL FAR instructions +where necessary when calling <em>external</em> functions, and must also +keep track of which external variable definitions are far and which are +near. +<h4><a name="section-2.2.6">2.2.6 Floating-Point Differences</a></h4> +<p>NASM uses different names to refer to floating-point registers from +MASM: where MASM would call them <code><nobr>ST(0)</nobr></code>, +<code><nobr>ST(1)</nobr></code> and so on, and +<code><nobr>a86</nobr></code> would call them simply +<code><nobr>0</nobr></code>, <code><nobr>1</nobr></code> and so on, NASM +chooses to call them <code><nobr>st0</nobr></code>, +<code><nobr>st1</nobr></code> etc. +<p>As of version 0.96, NASM now treats the instructions with `nowait' forms +in the same way as MASM-compatible assemblers. The idiosyncratic treatment +employed by 0.95 and earlier was based on a misunderstanding by the +authors. +<h4><a name="section-2.2.7">2.2.7 Other Differences</a></h4> +<p>For historical reasons, NASM uses the keyword +<code><nobr>TWORD</nobr></code> where MASM and compatible assemblers use +<code><nobr>TBYTE</nobr></code>. +<p>NASM does not declare uninitialized storage in the same way as MASM: +where a MASM programmer might use +<code><nobr>stack db 64 dup (?)</nobr></code>, NASM requires +<code><nobr>stack resb 64</nobr></code>, intended to be read as `reserve 64 +bytes'. For a limited amount of compatibility, since NASM treats +<code><nobr>?</nobr></code> as a valid character in symbol names, you can +code <code><nobr>? equ 0</nobr></code> and then writing +<code><nobr>dw ?</nobr></code> will at least do something vaguely useful. +<code><nobr>DUP</nobr></code> is still not a supported syntax, however. +<p>In addition to all of this, macros and directives work completely +differently to MASM. See <a href="nasmdoc4.html">chapter 4</a> and +<a href="nasmdoc6.html">chapter 6</a> for further details. +<p align=center><a href="nasmdoc3.html">Next Chapter</a> | +<a href="nasmdoc1.html">Previous Chapter</a> | +<a href="nasmdoc0.html">Contents</a> | +<a href="nasmdoci.html">Index</a> +</body></html> |