"Fossies" - the Fresh Open Source Software Archive

Member "nasm-2.15.05/doc/html/nasmdoc4.html" (28 Aug 2020, 80179 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="nasmdoc3.html">Chapter 3</a></li>
   12 <li><a class="next" href="nasmdoc5.html">Chapter 5</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-4">Chapter 4: The NASM Preprocessor</h2>
   23 <p>NASM contains a powerful macro processor, which supports conditional
   24 assembly, multi-level file inclusion, two forms of macro (single-line and
   25 multi-line), and a `context stack' mechanism for extra macro power.
   26 Preprocessor directives all begin with a <code>%</code> sign.</p>
   27 <p>The preprocessor collapses all lines which end with a backslash (\)
   28 character into a single line. Thus:</p>
   29 <pre>
   31         THIS_VALUE
   32 </pre>
   33 <p>will work like a single-line macro without the backslash-newline
   34 sequence.</p>
   35 <h3 id="section-4.1">4.1 Single-Line Macros</h3>
   36 <h4 id="section-4.1.1">4.1.1 The Normal Way: <code>%define</code></h4>
   37 <p>Single-line macros are defined using the <code>%define</code>
   38 preprocessor directive. The definitions work in a similar way to C; so you
   39 can do things like</p>
   40 <pre>
   41 %define ctrl    0x1F &amp; 
   42 %define param(a,b) ((a)+(a)*(b)) 
   44         mov     byte [param(2,ebx)], ctrl 'D'
   45 </pre>
   46 <p>which will expand to</p>
   47 <pre>
   48         mov     byte [(2)+(2)*(ebx)], 0x1F &amp; 'D'
   49 </pre>
   50 <p>When the expansion of a single-line macro contains tokens which invoke
   51 another macro, the expansion is performed at invocation time, not at
   52 definition time. Thus the code</p>
   53 <pre>
   54 %define a(x)    1+b(x) 
   55 %define b(x)    2*x 
   57         mov     ax,a(8)
   58 </pre>
   59 <p>will evaluate in the expected way to <code>mov ax,1+2*8</code>, even
   60 though the macro <code>b</code> wasn't defined at the time of definition of
   61 <code>a</code>.</p>
   62 <p>Note that single-line macro argument list cannot be preceded by
   63 whitespace. Otherwise it will be treated as an expansion. For example:</p>
   64 <pre>
   65    %define foo (a,b)               ; no arguments, (a,b) is the expansion 
   66    %define bar(a,b)                ; two arguments, empty expansion
   67 </pre>
   68 <p>Macros defined with <code>%define</code> are case sensitive: after
   69 <code>%define foo bar</code>, only <code>foo</code> will expand to
   70 <code>bar</code>: <code>Foo</code> or <code>FOO</code> will not. By using
   71 <code>%idefine</code> instead of <code>%define</code> (the `i' stands for
   72 `insensitive') you can define all the case variants of a macro at once, so
   73 that <code>%idefine foo bar</code> would cause <code>foo</code>,
   74 <code>Foo</code>, <code>FOO</code>, <code>fOO</code> and so on all to
   75 expand to <code>bar</code>.</p>
   76 <p>There is a mechanism which detects when a macro call has occurred as a
   77 result of a previous expansion of the same macro, to guard against circular
   78 references and infinite loops. If this happens, the preprocessor will only
   79 expand the first occurrence of the macro. Hence, if you code</p>
   80 <pre>
   81 %define a(x)    1+a(x) 
   83         mov     ax,a(3)
   84 </pre>
   85 <p>the macro <code>a(3)</code> will expand once, becoming
   86 <code>1+a(3)</code>, and will then expand no further. This behaviour can be
   87 useful: see <a href="nasmdo10.html#section-10.1">section 10.1</a> for an
   88 example of its use.</p>
   89 <p>You can overload single-line macros: if you write</p>
   90 <pre>
   91 %define foo(x)   1+x 
   92 %define foo(x,y) 1+x*y
   93 </pre>
   94 <p>the preprocessor will be able to handle both types of macro call, by
   95 counting the parameters you pass; so <code>foo(3)</code> will become
   96 <code>1+3</code> whereas <code>foo(ebx,2)</code> will become
   97 <code>1+ebx*2</code>. However, if you define</p>
   98 <pre>
   99 %define foo bar
  100 </pre>
  101 <p>then no other definition of <code>foo</code> will be accepted: a macro
  102 with no parameters prohibits the definition of the same name as a macro
  103 <em>with</em> parameters, and vice versa.</p>
  104 <p>This doesn't prevent single-line macros being <em>redefined</em>: you
  105 can perfectly well define a macro with</p>
  106 <pre>
  107 %define foo bar
  108 </pre>
  109 <p>and then re-define it later in the same source file with</p>
  110 <pre>
  111 %define foo baz
  112 </pre>
  113 <p>Then everywhere the macro <code>foo</code> is invoked, it will be
  114 expanded according to the most recent definition. This is particularly
  115 useful when defining single-line macros with <code>%assign</code> (see
  116 <a href="#section-4.1.8">section 4.1.8</a>).</p>
  117 <p>The following additional features were added in NASM 2.15:</p>
  118 <p>It is possible to define an empty string instead of an argument name if
  119 the argument is never used. For example:</p>
  120 <pre>
  121    %define ereg(foo,) e %+ foo 
  122      mov eax,ereg(dx,cx)
  123 </pre>
  124 <p>A single pair of parentheses is a subcase of a single, unused argument:</p>
  125 <pre>
  126    %define myreg() eax 
  127      mov edx,myreg()
  128 </pre>
  129 <p>This is similar to the behavior of the C preprocessor.</p>
  130 <ul>
  131 <li>
  132 <p>If declared with an <code>=</code>, NASM will evaluate the argument as
  133 an expression after expansion.</p>
  134 </li>
  135 <li>
  136 <p>If an argument declared with an <code>&amp;</code>, a macro parameter
  137 will be turned into a quoted string after expansion.</p>
  138 </li>
  139 <li>
  140 <p>If declared with a <code>+</code>, it is a greedy or variadic parameter;
  141 it includes any subsequent commas and parameters.</p>
  142 </li>
  143 <li>
  144 <p>If declared with an <code>!</code>, NASM will not strip whitespace and
  145 braces (useful in conjunction with <code>&amp;</code>).</p>
  146 </li>
  147 </ul>
  148 <p>For example:</p>
  149 <pre>
  150     %define xyzzy(=expr,&amp;val) expr, str 
  151     %define plugh(x) xyzzy(x,x) 
  152     db plugh(3+5), `\0` ; Expands to: db 8, "3+5", `\0`
  153 </pre>
  154 <p>You can pre-define single-line macros using the `-d' option on the NASM
  155 command line: see <a href="nasmdoc2.html#section-2.1.20">section
  156 2.1.20</a>.</p>
  157 <h4 id="section-4.1.2">4.1.2 Resolving <code>%define</code>: <code>%xdefine</code></h4>
  158 <p>To have a reference to an embedded single-line macro resolved at the
  159 time that the embedding macro is <em>defined</em>, as opposed to when the
  160 embedding macro is <em>expanded</em>, you need a different mechanism to the
  161 one offered by <code>%define</code>. The solution is to use
  162 <code>%xdefine</code>, or it's case-insensitive counterpart
  163 <code>%ixdefine</code>.</p>
  164 <p>Suppose you have the following code:</p>
  165 <pre>
  166 %define  isTrue  1 
  167 %define  isFalse isTrue 
  168 %define  isTrue  0 
  170 val1:    db      isFalse 
  172 %define  isTrue  1 
  174 val2:    db      isFalse
  175 </pre>
  176 <p>In this case, <code>val1</code> is equal to 0, and <code>val2</code> is
  177 equal to 1. This is because, when a single-line macro is defined using
  178 <code>%define</code>, it is expanded only when it is called. As
  179 <code>isFalse</code> expands to <code>isTrue</code>, the expansion will be
  180 the current value of <code>isTrue</code>. The first time it is called that
  181 is 0, and the second time it is 1.</p>
  182 <p>If you wanted <code>isFalse</code> to expand to the value assigned to
  183 the embedded macro <code>isTrue</code> at the time that
  184 <code>isFalse</code> was defined, you need to change the above code to use
  185 <code>%xdefine</code>.</p>
  186 <pre>
  187 %xdefine isTrue  1 
  188 %xdefine isFalse isTrue 
  189 %xdefine isTrue  0 
  191 val1:    db      isFalse 
  193 %xdefine isTrue  1 
  195 val2:    db      isFalse
  196 </pre>
  197 <p>Now, each time that <code>isFalse</code> is called, it expands to 1, as
  198 that is what the embedded macro <code>isTrue</code> expanded to at the time
  199 that <code>isFalse</code> was defined.</p>
  200 <p><code>%xdefine</code> and <code>%ixdefine</code> supports argument
  201 expansion exactly the same way that <code>%define</code> and
  202 <code>%idefine</code> does.</p>
  203 <h4 id="section-4.1.3">4.1.3 Macro Indirection: <code>%[...]</code></h4>
  204 <p>The <code>%[...]</code> construct can be used to expand macros in
  205 contexts where macro expansion would otherwise not occur, including in the
  206 names other macros. For example, if you have a set of macros named
  207 <code>Foo16</code>, <code>Foo32</code> and <code>Foo64</code>, you could
  208 write:</p>
  209 <pre>
  210      mov ax,Foo%[__?BITS?__] ; The Foo value
  211 </pre>
  212 <p>to use the builtin macro <code>__?BITS?__</code> (see
  213 <a href="nasmdoc5.html#section-5.3">section 5.3</a>) to automatically
  214 select between them. Similarly, the two statements:</p>
  215 <pre>
  216 %xdefine Bar         Quux    ; Expands due to %xdefine 
  217 %define  Bar         %[Quux] ; Expands due to %[...]
  218 </pre>
  219 <p>have, in fact, exactly the same effect.</p>
  220 <p><code>%[...]</code> concatenates to adjacent tokens in the same way that
  221 multi-line macro parameters do, see <a href="#section-4.3.9">section
  222 4.3.9</a> for details.</p>
  223 <h4 id="section-4.1.4">4.1.4 Concatenating Single Line Macro Tokens: <code>%+</code></h4>
  224 <p>Individual tokens in single line macros can be concatenated, to produce
  225 longer tokens for later processing. This can be useful if there are several
  226 similar macros that perform similar functions.</p>
  227 <p>Please note that a space is required after <code>%+</code>, in order to
  228 disambiguate it from the syntax <code>%+1</code> used in multiline macros.</p>
  229 <p>As an example, consider the following:</p>
  230 <pre>
  231 %define BDASTART 400h                ; Start of BIOS data area
  233 struc   tBIOSDA                      ; its structure 
  234         .COM1addr       RESW    1 
  235         .COM2addr       RESW    1 
  236         ; ..and so on 
  237 endstruc
  238 </pre>
  239 <p>Now, if we need to access the elements of tBIOSDA in different places,
  240 we can end up with:</p>
  241 <pre>
  242         mov     ax,BDASTART + tBIOSDA.COM1addr 
  243         mov     bx,BDASTART + tBIOSDA.COM2addr
  244 </pre>
  245 <p>This will become pretty ugly (and tedious) if used in many places, and
  246 can be reduced in size significantly by using the following macro:</p>
  247 <pre>
  248 ; Macro to access BIOS variables by their names (from tBDA):
  250 %define BDA(x)  BDASTART + tBIOSDA. %+ x
  251 </pre>
  252 <p>Now the above code can be written as:</p>
  253 <pre>
  254         mov     ax,BDA(COM1addr) 
  255         mov     bx,BDA(COM2addr)
  256 </pre>
  257 <p>Using this feature, we can simplify references to a lot of macros (and,
  258 in turn, reduce typing errors).</p>
  259 <h4 id="section-4.1.5">4.1.5 The Macro Name Itself: <code>%?</code> and <code>%??</code></h4>
  260 <p>The special symbols <code>%?</code> and <code>%??</code> can be used to
  261 reference the macro name itself inside a macro expansion, this is supported
  262 for both single-and multi-line macros. <code>%?</code> refers to the macro
  263 name as <em>invoked</em>, whereas <code>%??</code> refers to the macro name
  264 as <em>declared</em>. The two are always the same for case-sensitive
  265 macros, but for case-insensitive macros, they can differ.</p>
  266 <p>For example:</p>
  267 <pre>
  268 %imacro Foo 0 
  269         mov %?,%?? 
  270 %endmacro 
  272         foo 
  273         FOO
  274 </pre>
  275 <p>will expand to:</p>
  276 <pre>
  277         mov foo,Foo 
  278         mov FOO,Foo
  279 </pre>
  280 <p>These tokens can be used for single-line macros <em>if defined outside
  281 any multi-line macros.</em> See below.</p>
  282 <h4 id="section-4.1.6">4.1.6 The Single-Line Macro Name: <code>%*?</code> and <code>%*??</code></h4>
  283 <p>If the tokens <code>%?</code> and <code>%??</code> are used inside a
  284 multi-line macro, they are expanded before any directives are processed. As
  285 a result,</p>
  286 <pre>
  287 %imacro Foo 0 
  288       %idefine Bar _%? 
  289       mov BAR,bAr 
  290 %endmacro 
  292       foo 
  293       mov eax,bar
  294 </pre>
  295 <p>will expand to:</p>
  296 <pre>
  297       mov _foo,_foo 
  298       mov eax,_foo
  299 </pre>
  300 <p>which may or may not be what you expected. The tokens <code>%*?</code>
  301 and <code>%*??</code> behave like <code>%?</code> and <code>%??</code> but
  302 are only expanded inside single-line macros. Thus:</p>
  303 <pre>
  304 %imacro Foo 0 
  305       %idefine Bar _%*? 
  306       mov BAR,bAr 
  307 %endmacro 
  309       foo 
  310       mov eax,bar
  311 </pre>
  312 <p>will expand to:</p>
  313 <pre>
  314       mov _BAR,_bAr 
  315       mov eax,_bar
  316 </pre>
  317 <p>The <code>%*?</code> can be used to make a keyword "disappear", for
  318 example in case a new instruction has been used as a label in older code.
  319 For example:</p>
  320 <pre>
  321 %idefine pause $%*?                 ; Hide the PAUSE instruction
  322 </pre>
  323 <p><code>%*?</code> and <code>%*??</code> were introduced in NASM 2.15.04.</p>
  324 <h4 id="section-4.1.7">4.1.7 Undefining Single-Line Macros: <code>%undef</code></h4>
  325 <p>Single-line macros can be removed with the <code>%undef</code>
  326 directive. For example, the following sequence:</p>
  327 <pre>
  328 %define foo bar 
  329 %undef  foo 
  331         mov     eax, foo
  332 </pre>
  333 <p>will expand to the instruction <code>mov eax, foo</code>, since after
  334 <code>%undef</code> the macro <code>foo</code> is no longer defined.</p>
  335 <p>Macros that would otherwise be pre-defined can be undefined on the
  336 command-line using the `-u' option on the NASM command line: see
  337 <a href="nasmdoc2.html#section-2.1.21">section 2.1.21</a>.</p>
  338 <h4 id="section-4.1.8">4.1.8 Preprocessor Variables: <code>%assign</code></h4>
  339 <p>An alternative way to define single-line macros is by means of the
  340 <code>%assign</code> command (and its case-insensitive counterpart
  341 <code>%iassign</code>, which differs from <code>%assign</code> in exactly
  342 the same way that <code>%idefine</code> differs from <code>%define</code>).</p>
  343 <p><code>%assign</code> is used to define single-line macros which take no
  344 parameters and have a numeric value. This value can be specified in the
  345 form of an expression, and it will be evaluated once, when the
  346 <code>%assign</code> directive is processed.</p>
  347 <p>Like <code>%define</code>, macros defined using <code>%assign</code> can
  348 be re-defined later, so you can do things like</p>
  349 <pre>
  350 %assign i i+1
  351 </pre>
  352 <p>to increment the numeric value of a macro.</p>
  353 <p><code>%assign</code> is useful for controlling the termination of
  354 <code>%rep</code> preprocessor loops: see <a href="#section-4.5">section
  355 4.5</a> for an example of this. Another use for <code>%assign</code> is
  356 given in <a href="nasmdoc9.html#section-9.4">section 9.4</a> and
  357 <a href="nasmdo10.html#section-10.1">section 10.1</a>.</p>
  358 <p>The expression passed to <code>%assign</code> is a critical expression
  359 (see <a href="nasmdoc3.html#section-3.8">section 3.8</a>), and must also
  360 evaluate to a pure number (rather than a relocatable reference such as a
  361 code or data address, or anything involving a register).</p>
  362 <h4 id="section-4.1.9">4.1.9 Defining Strings: <code>%defstr</code></h4>
  363 <p><code>%defstr</code>, and its case-insensitive counterpart
  364 <code>%idefstr</code>, define or redefine a single-line macro without
  365 parameters but converts the entire right-hand side, after macro expansion,
  366 to a quoted string before definition.</p>
  367 <p>For example:</p>
  368 <pre>
  369 %defstr test TEST
  370 </pre>
  371 <p>is equivalent to</p>
  372 <pre>
  373 %define test 'TEST'
  374 </pre>
  375 <p>This can be used, for example, with the <code>%!</code> construct (see
  376 <a href="#section-4.11.2">section 4.11.2</a>):</p>
  377 <pre>
  378 %defstr PATH %!PATH          ; The operating system PATH variable
  379 </pre>
  380 <h4 id="section-4.1.10">4.1.10 Defining Tokens: <code>%deftok</code></h4>
  381 <p><code>%deftok</code>, and its case-insensitive counterpart
  382 <code>%ideftok</code>, define or redefine a single-line macro without
  383 parameters but converts the second parameter, after string conversion, to a
  384 sequence of tokens.</p>
  385 <p>For example:</p>
  386 <pre>
  387 %deftok test 'TEST'
  388 </pre>
  389 <p>is equivalent to</p>
  390 <pre>
  391 %define test TEST
  392 </pre>
  393 <h4 id="section-4.1.11">4.1.11 Defining Aliases: <code>%defalias</code></h4>
  394 <p><code>%defalias</code>, and its case-insensitive counterpart
  395 <code>%idefalias</code>, define an alias to a macro, i.e. equivalent of a
  396 symbolic link.</p>
  397 <p>When used with various macro defining and undefining directives, it
  398 affects the aliased macro. This functionality is intended for being able to
  399 rename macros while retaining the legacy names.</p>
  400 <p>When an alias is defined, but the aliased macro is then undefined, the
  401 aliases can legitimately point to nonexistent macros.</p>
  402 <p>The alias can be undefined using the <code>%undefalias</code> directive.
  403 <em>All</em> aliases can be undefined using the
  404 <code>%clear defalias</code> directive. This includes backwards
  405 compatibility aliases defined by NASM itself.</p>
  406 <p>To disable aliases without undefining them, use the
  407 <code>%aliases off</code> directive.</p>
  408 <p>To check whether an alias is defined, regardless of the existence of the
  409 aliased macro, use <code>%ifdefalias</code>.</p>
  410 <p>For example:</p>
  411 <pre>
  412 %defalias OLD NEW 
  413    ; OLD and NEW both undefined 
  414 %define NEW 123 
  415    ; OLD and NEW both 123 
  416 %undef OLD 
  417    ; OLD and NEW both undefined 
  418 %define OLD 456 
  419    ; OLD and NEW both 456 
  420 %undefalias OLD 
  421    ; OLD undefined, NEW defined to 456
  422 </pre>
  423 <h4 id="section-4.1.12">4.1.12 Conditional Comma Operator: <code>%,</code></h4>
  424 <p>As of version 2.15, NASM has a conditional comma operator
  425 <code>%,</code> that expands to a comma <em>unless</em> followed by a null
  426 expansion, which allows suppressing the comma before an empty argument.
  427 This is especially useful with greedy single-line macros.</p>
  428 <p>For example, all the expressions below are valid:</p>
  429 <pre>
  430 %define greedy(a,b,c+) a + 66 %, b * 3 %, c 
  432        db greedy(1,2)          ; db 1 + 66, 2 * 3 
  433        db greedy(1,2,3)        ; db 1 + 66, 2 * 3, 3 
  434        db greedy(1,2,3,4)      ; db 1 + 66, 2 * 3, 3, 4 
  435        db greedy(1,2,3,4,5)    ; db 1 + 66, 2 * 3, 3, 4, 5
  436 </pre>
  437 <h3 id="section-4.2">4.2 String Manipulation in Macros</h3>
  438 <p>It's often useful to be able to handle strings in macros. NASM supports
  439 a few simple string handling macro operators from which more complex
  440 operations can be constructed.</p>
  441 <p>All the string operators define or redefine a value (either a string or
  442 a numeric value) to a single-line macro. When producing a string value, it
  443 may change the style of quoting of the input string or strings, and
  444 possibly use <code>\</code>&ndash;escapes inside
  445 <code>`</code>&ndash;quoted strings.</p>
  446 <h4 id="section-4.2.1">4.2.1 Concatenating Strings: <code>%strcat</code></h4>
  447 <p>The <code>%strcat</code> operator concatenates quoted strings and assign
  448 them to a single-line macro.</p>
  449 <p>For example:</p>
  450 <pre>
  451 %strcat alpha "Alpha: ", '12" screen'
  452 </pre>
  453 <p>... would assign the value <code>'Alpha: 12" screen'</code> to
  454 <code>alpha</code>. Similarly:</p>
  455 <pre>
  456 %strcat beta '"foo"\', "'bar'"
  457 </pre>
  458 <p>... would assign the value <code>`"foo"\\'bar'`</code> to
  459 <code>beta</code>.</p>
  460 <p>The use of commas to separate strings is permitted but optional.</p>
  461 <h4 id="section-4.2.2">4.2.2 String Length: <code>%strlen</code></h4>
  462 <p>The <code>%strlen</code> operator assigns the length of a string to a
  463 macro. For example:</p>
  464 <pre>
  465 %strlen charcnt 'my string'
  466 </pre>
  467 <p>In this example, <code>charcnt</code> would receive the value 9, just as
  468 if an <code>%assign</code> had been used. In this example,
  469 <code>'my string'</code> was a literal string but it could also have been a
  470 single-line macro that expands to a string, as in the following example:</p>
  471 <pre>
  472 %define sometext 'my string' 
  473 %strlen charcnt sometext
  474 </pre>
  475 <p>As in the first case, this would result in <code>charcnt</code> being
  476 assigned the value of 9.</p>
  477 <h4 id="section-4.2.3">4.2.3 Extracting Substrings: <code>%substr</code></h4>
  478 <p>Individual letters or substrings in strings can be extracted using the
  479 <code>%substr</code> operator. An example of its use is probably more
  480 useful than the description:</p>
  481 <pre>
  482 %substr mychar 'xyzw' 1       ; equivalent to %define mychar 'x' 
  483 %substr mychar 'xyzw' 2       ; equivalent to %define mychar 'y' 
  484 %substr mychar 'xyzw' 3       ; equivalent to %define mychar 'z' 
  485 %substr mychar 'xyzw' 2,2     ; equivalent to %define mychar 'yz' 
  486 %substr mychar 'xyzw' 2,-1    ; equivalent to %define mychar 'yzw' 
  487 %substr mychar 'xyzw' 2,-2    ; equivalent to %define mychar 'yz'
  488 </pre>
  489 <p>As with <code>%strlen</code> (see <a href="#section-4.2.2">section
  490 4.2.2</a>), the first parameter is the single-line macro to be created and
  491 the second is the string. The third parameter specifies the first character
  492 to be selected, and the optional fourth parameter preceeded by comma) is
  493 the length. Note that the first index is 1, not 0 and the last index is
  494 equal to the value that <code>%strlen</code> would assign given the same
  495 string. Index values out of range result in an empty string. A negative
  496 length means "until N-1 characters before the end of string", i.e.
  497 <code>-1</code> means until end of string, <code>-2</code> until one
  498 character before, etc.</p>
  499 <h3 id="section-4.3">4.3 Multi-Line Macros: <code>%macro</code></h3>
  500 <p>Multi-line macros are much more like the type of macro seen in MASM and
  501 TASM: a multi-line macro definition in NASM looks something like this.</p>
  502 <pre>
  503 %macro  prologue 1 
  505         push    ebp 
  506         mov     ebp,esp 
  507         sub     esp,%1 
  509 %endmacro
  510 </pre>
  511 <p>This defines a C-like function prologue as a macro: so you would invoke
  512 the macro with a call such as:</p>
  513 <pre>
  514 myfunc:   prologue 12
  515 </pre>
  516 <p>which would expand to the three lines of code</p>
  517 <pre>
  518 myfunc: push    ebp 
  519         mov     ebp,esp 
  520         sub     esp,12
  521 </pre>
  522 <p>The number <code>1</code> after the macro name in the
  523 <code>%macro</code> line defines the number of parameters the macro
  524 <code>prologue</code> expects to receive. The use of <code>%1</code> inside
  525 the macro definition refers to the first parameter to the macro call. With
  526 a macro taking more than one parameter, subsequent parameters would be
  527 referred to as <code>%2</code>, <code>%3</code> and so on.</p>
  528 <p>Multi-line macros, like single-line macros, are case-sensitive, unless
  529 you define them using the alternative directive <code>%imacro</code>.</p>
  530 <p>If you need to pass a comma as <em>part</em> of a parameter to a
  531 multi-line macro, you can do that by enclosing the entire parameter in
  532 braces. So you could code things like:</p>
  533 <pre>
  534 %macro  silly 2 
  536     %2: db      %1 
  538 %endmacro 
  540         silly 'a', letter_a             ; letter_a:  db 'a' 
  541         silly 'ab', string_ab           ; string_ab: db 'ab' 
  542         silly {13,10}, crlf             ; crlf:      db 13,10
  543 </pre>
  544 <p>The behavior with regards to empty arguments at the end of multi-line
  545 macros before NASM 2.15 was often very strange. For backwards
  546 compatibility, NASM attempts to recognize cases where the legacy behavior
  547 would give unexpected results, and issues a warning, but largely tries to
  548 match the legacy behavior. This can be disabled with the
  549 <code>%pragma</code> (see <a href="#section-4.10.1">section 4.10.1</a>):</p>
  550 <pre>
  551 %pragma preproc sane_empty_expansion
  552 </pre>
  553 <h4 id="section-4.3.1">4.3.1 Overloading Multi-Line Macros</h4>
  554 <p>As with single-line macros, multi-line macros can be overloaded by
  555 defining the same macro name several times with different numbers of
  556 parameters. This time, no exception is made for macros with no parameters
  557 at all. So you could define</p>
  558 <pre>
  559 %macro  prologue 0 
  561         push    ebp 
  562         mov     ebp,esp 
  564 %endmacro
  565 </pre>
  566 <p>to define an alternative form of the function prologue which allocates
  567 no local stack space.</p>
  568 <p>Sometimes, however, you might want to `overload' a machine instruction;
  569 for example, you might want to define</p>
  570 <pre>
  571 %macro  push 2 
  573         push    %1 
  574         push    %2 
  576 %endmacro
  577 </pre>
  578 <p>so that you could code</p>
  579 <pre>
  580         push    ebx             ; this line is not a macro call 
  581         push    eax,ecx         ; but this one is
  582 </pre>
  583 <p>Ordinarily, NASM will give a warning for the first of the above two
  584 lines, since <code>push</code> is now defined to be a macro, and is being
  585 invoked with a number of parameters for which no definition has been given.
  586 The correct code will still be generated, but the assembler will give a
  587 warning. This warning can be disabled by the use of the
  588 <code>-w-macro-params</code> command-line option (see
  589 <a href="nasmdoc2.html#section-2.1.26">section 2.1.26</a>).</p>
  590 <h4 id="section-4.3.2">4.3.2 Macro-Local Labels</h4>
  591 <p>NASM allows you to define labels within a multi-line macro definition in
  592 such a way as to make them local to the macro call: so calling the same
  593 macro multiple times will use a different label each time. You do this by
  594 prefixing <code>%%</code> to the label name. So you can invent an
  595 instruction which executes a <code>RET</code> if the <code>Z</code> flag is
  596 set by doing this:</p>
  597 <pre>
  598 %macro  retz 0 
  600         jnz     %%skip 
  601         ret 
  602     %%skip: 
  604 %endmacro
  605 </pre>
  606 <p>You can call this macro as many times as you want, and every time you
  607 call it NASM will make up a different `real' name to substitute for the
  608 label <code>%%skip</code>. The names NASM invents are of the form
  609 <code>..@2345.skip</code>, where the number 2345 changes with every macro
  610 call. The <code>..@</code> prefix prevents macro-local labels from
  611 interfering with the local label mechanism, as described in
  612 <a href="nasmdoc3.html#section-3.9">section 3.9</a>. You should avoid
  613 defining your own labels in this form (the <code>..@</code> prefix, then a
  614 number, then another period) in case they interfere with macro-local
  615 labels.</p>
  616 <p>These labels are really macro-local <em>tokens</em>, and can be used for
  617 other purposes where a token unique to each macro invocation is desired,
  618 e.g. to name single-line macros without using the context feature
  619 (<a href="#section-4.7.2">section 4.7.2</a>).</p>
  620 <h4 id="section-4.3.3">4.3.3 Greedy Macro Parameters</h4>
  621 <p>Occasionally it is useful to define a macro which lumps its entire
  622 command line into one parameter definition, possibly after extracting one
  623 or two smaller parameters from the front. An example might be a macro to
  624 write a text string to a file in MS-DOS, where you might want to be able to
  625 write</p>
  626 <pre>
  627         writefile [filehandle],"hello, world",13,10
  628 </pre>
  629 <p>NASM allows you to define the last parameter of a macro to be
  630 <em>greedy</em>, meaning that if you invoke the macro with more parameters
  631 than it expects, all the spare parameters get lumped into the last defined
  632 one along with the separating commas. So if you code:</p>
  633 <pre>
  634 %macro  writefile 2+ 
  636         jmp     %%endstr 
  637   %%str:        db      %2 
  638   %%endstr: 
  639         mov     dx,%%str 
  640         mov     cx,%%endstr-%%str 
  641         mov     bx,%1 
  642         mov     ah,0x40 
  643         int     0x21 
  645 %endmacro
  646 </pre>
  647 <p>then the example call to <code>writefile</code> above will work as
  648 expected: the text before the first comma, <code>[filehandle]</code>, is
  649 used as the first macro parameter and expanded when <code>%1</code> is
  650 referred to, and all the subsequent text is lumped into <code>%2</code> and
  651 placed after the <code>db</code>.</p>
  652 <p>The greedy nature of the macro is indicated to NASM by the use of the
  653 <code>+</code> sign after the parameter count on the <code>%macro</code>
  654 line.</p>
  655 <p>If you define a greedy macro, you are effectively telling NASM how it
  656 should expand the macro given <em>any</em> number of parameters from the
  657 actual number specified up to infinity; in this case, for example, NASM now
  658 knows what to do when it sees a call to <code>writefile</code> with 2, 3, 4
  659 or more parameters. NASM will take this into account when overloading
  660 macros, and will not allow you to define another form of
  661 <code>writefile</code> taking 4 parameters (for example).</p>
  662 <p>Of course, the above macro could have been implemented as a non-greedy
  663 macro, in which case the call to it would have had to look like</p>
  664 <pre>
  665           writefile [filehandle], {"hello, world",13,10}
  666 </pre>
  667 <p>NASM provides both mechanisms for putting commas in macro parameters,
  668 and you choose which one you prefer for each macro definition.</p>
  669 <p>See <a href="nasmdoc7.html#section-7.3.1">section 7.3.1</a> for a better
  670 way to write the above macro.</p>
  671 <h4 id="section-4.3.4">4.3.4 Macro Parameters Range</h4>
  672 <p>NASM allows you to expand parameters via special construction
  673 <code>%{x:y}</code> where <code>x</code> is the first parameter index and
  674 <code>y</code> is the last. Any index can be either negative or positive
  675 but must never be zero.</p>
  676 <p>For example</p>
  677 <pre>
  678 %macro mpar 1-* 
  679      db %{3:5} 
  680 %endmacro 
  682 mpar 1,2,3,4,5,6
  683 </pre>
  684 <p>expands to <code>3,4,5</code> range.</p>
  685 <p>Even more, the parameters can be reversed so that</p>
  686 <pre>
  687 %macro mpar 1-* 
  688      db %{5:3} 
  689 %endmacro 
  691 mpar 1,2,3,4,5,6
  692 </pre>
  693 <p>expands to <code>5,4,3</code> range.</p>
  694 <p>But even this is not the last. The parameters can be addressed via
  695 negative indices so NASM will count them reversed. The ones who know Python
  696 may see the analogue here.</p>
  697 <pre>
  698 %macro mpar 1-* 
  699      db %{-1:-3} 
  700 %endmacro 
  702 mpar 1,2,3,4,5,6
  703 </pre>
  704 <p>expands to <code>6,5,4</code> range.</p>
  705 <p>Note that NASM uses comma to separate parameters being expanded.</p>
  706 <p>By the way, here is a trick &ndash; you might use the index
  707 <code>%{-1:-1</code>} which gives you the last argument passed to a macro.</p>
  708 <h4 id="section-4.3.5">4.3.5 Default Macro Parameters</h4>
  709 <p>NASM also allows you to define a multi-line macro with a <em>range</em>
  710 of allowable parameter counts. If you do this, you can specify defaults for
  711 omitted parameters. So, for example:</p>
  712 <pre>
  713 %macro  die 0-1 "Painful program death has occurred." 
  715         writefile 2,%1 
  716         mov     ax,0x4c01 
  717         int     0x21 
  719 %endmacro
  720 </pre>
  721 <p>This macro (which makes use of the <code>writefile</code> macro defined
  722 in <a href="#section-4.3.3">section 4.3.3</a>) can be called with an
  723 explicit error message, which it will display on the error output stream
  724 before exiting, or it can be called with no parameters, in which case it
  725 will use the default error message supplied in the macro definition.</p>
  726 <p>In general, you supply a minimum and maximum number of parameters for a
  727 macro of this type; the minimum number of parameters are then required in
  728 the macro call, and then you provide defaults for the optional ones. So if
  729 a macro definition began with the line</p>
  730 <pre>
  731 %macro foobar 1-3 eax,[ebx+2]
  732 </pre>
  733 <p>then it could be called with between one and three parameters, and
  734 <code>%1</code> would always be taken from the macro call. <code>%2</code>,
  735 if not specified by the macro call, would default to <code>eax</code>, and
  736 <code>%3</code> if not specified would default to <code>[ebx+2]</code>.</p>
  737 <p>You can provide extra information to a macro by providing too many
  738 default parameters:</p>
  739 <pre>
  740 %macro quux 1 something
  741 </pre>
  742 <p>This will trigger a warning by default; see
  743 <a href="nasmdoc2.html#section-2.1.26">section 2.1.26</a> for more
  744 information. When <code>quux</code> is invoked, it receives not one but two
  745 parameters. <code>something</code> can be referred to as <code>%2</code>.
  746 The difference between passing <code>something</code> this way and writing
  747 <code>something</code> in the macro body is that with this way
  748 <code>something</code> is evaluated when the macro is defined, not when it
  749 is expanded.</p>
  750 <p>You may omit parameter defaults from the macro definition, in which case
  751 the parameter default is taken to be blank. This can be useful for macros
  752 which can take a variable number of parameters, since the <code>%0</code>
  753 token (see <a href="#section-4.3.6">section 4.3.6</a>) allows you to
  754 determine how many parameters were really passed to the macro call.</p>
  755 <p>This defaulting mechanism can be combined with the greedy-parameter
  756 mechanism; so the <code>die</code> macro above could be made more powerful,
  757 and more useful, by changing the first line of the definition to</p>
  758 <pre>
  759 %macro die 0-1+ "Painful program death has occurred.",13,10
  760 </pre>
  761 <p>The maximum parameter count can be infinite, denoted by <code>*</code>.
  762 In this case, of course, it is impossible to provide a <em>full</em> set of
  763 default parameters. Examples of this usage are shown in
  764 <a href="#section-4.3.8">section 4.3.8</a>.</p>
  765 <h4 id="section-4.3.6">4.3.6 <code>%0</code>: Macro Parameter Counter</h4>
  766 <p>The parameter reference <code>%0</code> will return a numeric constant
  767 giving the number of parameters received, that is, if <code>%0</code> is n
  768 then <code>%</code>n is the last parameter. <code>%0</code> is mostly
  769 useful for macros that can take a variable number of parameters. It can be
  770 used as an argument to <code>%rep</code> (see
  771 <a href="#section-4.5">section 4.5</a>) in order to iterate through all the
  772 parameters of a macro. Examples are given in
  773 <a href="#section-4.3.8">section 4.3.8</a>.</p>
  774 <h4 id="section-4.3.7">4.3.7 <code>%00</code>: Label Preceeding Macro</h4>
  775 <p><code>%00</code> will return the label preceeding the macro invocation,
  776 if any. The label must be on the same line as the macro invocation, may be
  777 a local label (see <a href="nasmdoc3.html#section-3.9">section 3.9</a>),
  778 and need not end in a colon.</p>
  779 <p>If <code>%00</code> is present anywhere in the macro body, the label
  780 itself will not be emitted by NASM. You can, of course, put
  781 <code>%00:</code> explicitly at the beginning of your macro.</p>
  782 <h4 id="section-4.3.8">4.3.8 <code>%rotate</code>: Rotating Macro Parameters</h4>
  783 <p>Unix shell programmers will be familiar with the <code>shift</code>
  784 shell command, which allows the arguments passed to a shell script
  785 (referenced as <code>$1</code>, <code>$2</code> and so on) to be moved left
  786 by one place, so that the argument previously referenced as <code>$2</code>
  787 becomes available as <code>$1</code>, and the argument previously
  788 referenced as <code>$1</code> is no longer available at all.</p>
  789 <p>NASM provides a similar mechanism, in the form of <code>%rotate</code>.
  790 As its name suggests, it differs from the Unix <code>shift</code> in that
  791 no parameters are lost: parameters rotated off the left end of the argument
  792 list reappear on the right, and vice versa.</p>
  793 <p><code>%rotate</code> is invoked with a single numeric argument (which
  794 may be an expression). The macro parameters are rotated to the left by that
  795 many places. If the argument to <code>%rotate</code> is negative, the macro
  796 parameters are rotated to the right.</p>
  797 <p>So a pair of macros to save and restore a set of registers might work as
  798 follows:</p>
  799 <pre>
  800 %macro  multipush 1-* 
  802   %rep  %0 
  803         push    %1 
  804   %rotate 1 
  805   %endrep 
  807 %endmacro
  808 </pre>
  809 <p>This macro invokes the <code>PUSH</code> instruction on each of its
  810 arguments in turn, from left to right. It begins by pushing its first
  811 argument, <code>%1</code>, then invokes <code>%rotate</code> to move all
  812 the arguments one place to the left, so that the original second argument
  813 is now available as <code>%1</code>. Repeating this procedure as many times
  814 as there were arguments (achieved by supplying <code>%0</code> as the
  815 argument to <code>%rep</code>) causes each argument in turn to be pushed.</p>
  816 <p>Note also the use of <code>*</code> as the maximum parameter count,
  817 indicating that there is no upper limit on the number of parameters you may
  818 supply to the <code>multipush</code> macro.</p>
  819 <p>It would be convenient, when using this macro, to have a
  820 <code>POP</code> equivalent, which <em>didn't</em> require the arguments to
  821 be given in reverse order. Ideally, you would write the
  822 <code>multipush</code> macro call, then cut-and-paste the line to where the
  823 pop needed to be done, and change the name of the called macro to
  824 <code>multipop</code>, and the macro would take care of popping the
  825 registers in the opposite order from the one in which they were pushed.</p>
  826 <p>This can be done by the following definition:</p>
  827 <pre>
  828 %macro  multipop 1-* 
  830   %rep %0 
  831   %rotate -1 
  832         pop     %1 
  833   %endrep 
  835 %endmacro
  836 </pre>
  837 <p>This macro begins by rotating its arguments one place to the
  838 <em>right</em>, so that the original <em>last</em> argument appears as
  839 <code>%1</code>. This is then popped, and the arguments are rotated right
  840 again, so the second-to-last argument becomes <code>%1</code>. Thus the
  841 arguments are iterated through in reverse order.</p>
  842 <h4 id="section-4.3.9">4.3.9 Concatenating Macro Parameters</h4>
  843 <p>NASM can concatenate macro parameters and macro indirection constructs
  844 on to other text surrounding them. This allows you to declare a family of
  845 symbols, for example, in a macro definition. If, for example, you wanted to
  846 generate a table of key codes along with offsets into the table, you could
  847 code something like</p>
  848 <pre>
  849 %macro keytab_entry 2 
  851     keypos%1    equ     $-keytab 
  852                 db      %2 
  854 %endmacro 
  856 keytab: 
  857           keytab_entry F1,128+1 
  858           keytab_entry F2,128+2 
  859           keytab_entry Return,13
  860 </pre>
  861 <p>which would expand to</p>
  862 <pre>
  863 keytab: 
  864 keyposF1        equ     $-keytab 
  865                 db     128+1 
  866 keyposF2        equ     $-keytab 
  867                 db      128+2 
  868 keyposReturn    equ     $-keytab 
  869                 db      13
  870 </pre>
  871 <p>You can just as easily concatenate text on to the other end of a macro
  872 parameter, by writing <code>%1foo</code>.</p>
  873 <p>If you need to append a <em>digit</em> to a macro parameter, for example
  874 defining labels <code>foo1</code> and <code>foo2</code> when passed the
  875 parameter <code>foo</code>, you can't code <code>%11</code> because that
  876 would be taken as the eleventh macro parameter. Instead, you must code
  877 <code>%{1}1</code>, which will separate the first <code>1</code> (giving
  878 the number of the macro parameter) from the second (literal text to be
  879 concatenated to the parameter).</p>
  880 <p>This concatenation can also be applied to other preprocessor in-line
  881 objects, such as macro-local labels (<a href="#section-4.3.2">section
  882 4.3.2</a>) and context-local labels (<a href="#section-4.7.2">section
  883 4.7.2</a>). In all cases, ambiguities in syntax can be resolved by
  884 enclosing everything after the <code>%</code> sign and before the literal
  885 text in braces: so <code>%{%foo}bar</code> concatenates the text
  886 <code>bar</code> to the end of the real name of the macro-local label
  887 <code>%%foo</code>. (This is unnecessary, since the form NASM uses for the
  888 real names of macro-local labels means that the two usages
  889 <code>%{%foo}bar</code> and <code>%%foobar</code> would both expand to the
  890 same thing anyway; nevertheless, the capability is there.)</p>
  891 <p>The single-line macro indirection construct, <code>%[...]</code>
  892 (<a href="#section-4.1.3">section 4.1.3</a>), behaves the same way as macro
  893 parameters for the purpose of concatenation.</p>
  894 <p>See also the <code>%+</code> operator, <a href="#section-4.1.4">section
  895 4.1.4</a>.</p>
  896 <h4 id="section-4.3.10">4.3.10 Condition Codes as Macro Parameters</h4>
  897 <p>NASM can give special treatment to a macro parameter which contains a
  898 condition code. For a start, you can refer to the macro parameter
  899 <code>%1</code> by means of the alternative syntax <code>%+1</code>, which
  900 informs NASM that this macro parameter is supposed to contain a condition
  901 code, and will cause the preprocessor to report an error message if the
  902 macro is called with a parameter which is <em>not</em> a valid condition
  903 code.</p>
  904 <p>Far more usefully, though, you can refer to the macro parameter by means
  905 of <code>%-1</code>, which NASM will expand as the <em>inverse</em>
  906 condition code. So the <code>retz</code> macro defined in
  907 <a href="#section-4.3.2">section 4.3.2</a> can be replaced by a general
  908 conditional-return macro like this:</p>
  909 <pre>
  910 %macro  retc 1 
  912         j%-1    %%skip 
  913         ret 
  914   %%skip: 
  916 %endmacro
  917 </pre>
  918 <p>This macro can now be invoked using calls like <code>retc ne</code>,
  919 which will cause the conditional-jump instruction in the macro expansion to
  920 come out as <code>JE</code>, or <code>retc po</code> which will make the
  921 jump a <code>JPE</code>.</p>
  922 <p>The <code>%+1</code> macro-parameter reference is quite happy to
  923 interpret the arguments <code>CXZ</code> and <code>ECXZ</code> as valid
  924 condition codes; however, <code>%-1</code> will report an error if passed
  925 either of these, because no inverse condition code exists.</p>
  926 <h4 id="section-4.3.11">4.3.11 Disabling Listing Expansion</h4>
  927 <p>When NASM is generating a listing file from your program, it will
  928 generally expand multi-line macros by means of writing the macro call and
  929 then listing each line of the expansion. This allows you to see which
  930 instructions in the macro expansion are generating what code; however, for
  931 some macros this clutters the listing up unnecessarily.</p>
  932 <p>NASM therefore provides the <code>.nolist</code> qualifier, which you
  933 can include in a macro definition to inhibit the expansion of the macro in
  934 the listing file. The <code>.nolist</code> qualifier comes directly after
  935 the number of parameters, like this:</p>
  936 <pre>
  937 %macro foo 1.nolist
  938 </pre>
  939 <p>Or like this:</p>
  940 <pre>
  941 %macro bar 1-5+.nolist a,b,c,d,e,f,g,h
  942 </pre>
  943 <h4 id="section-4.3.12">4.3.12 Undefining Multi-Line Macros: <code>%unmacro</code></h4>
  944 <p>Multi-line macros can be removed with the <code>%unmacro</code>
  945 directive. Unlike the <code>%undef</code> directive, however,
  946 <code>%unmacro</code> takes an argument specification, and will only remove
  947 exact matches with that argument specification.</p>
  948 <p>For example:</p>
  949 <pre>
  950 %macro foo 1-3 
  951         ; Do something 
  952 %endmacro 
  953 %unmacro foo 1-3
  954 </pre>
  955 <p>removes the previously defined macro <code>foo</code>, but</p>
  956 <pre>
  957 %macro bar 1-3 
  958         ; Do something 
  959 %endmacro 
  960 %unmacro bar 1
  961 </pre>
  962 <p>does <em>not</em> remove the macro <code>bar</code>, since the argument
  963 specification does not match exactly.</p>
  964 <h3 id="section-4.4">4.4 Conditional Assembly</h3>
  965 <p>Similarly to the C preprocessor, NASM allows sections of a source file
  966 to be assembled only if certain conditions are met. The general syntax of
  967 this feature looks like this:</p>
  968 <pre>
  969 %if&lt;condition&gt; 
  970     ; some code which only appears if &lt;condition&gt; is met 
  971 %elif&lt;condition2&gt; 
  972     ; only appears if &lt;condition&gt; is not met but &lt;condition2&gt; is 
  973 %else 
  974     ; this appears if neither &lt;condition&gt; nor &lt;condition2&gt; was met 
  975 %endif
  976 </pre>
  977 <p>The inverse forms <code>%ifn</code> and <code>%elifn</code> are also
  978 supported.</p>
  979 <p>The <code>%else</code> clause is optional, as is the <code>%elif</code>
  980 clause. You can have more than one <code>%elif</code> clause as well.</p>
  981 <p>There are a number of variants of the <code>%if</code> directive. Each
  982 has its corresponding <code>%elif</code>, <code>%ifn</code>, and
  983 <code>%elifn</code> directives; for example, the equivalents to the
  984 <code>%ifdef</code> directive are <code>%elifdef</code>,
  985 <code>%ifndef</code>, and <code>%elifndef</code>.</p>
  986 <h4 id="section-4.4.1">4.4.1 <code>%ifdef</code>: Testing Single-Line Macro Existence</h4>
  987 <p>Beginning a conditional-assembly block with the line
  988 <code>%ifdef MACRO</code> will assemble the subsequent code if, and only
  989 if, a single-line macro called <code>MACRO</code> is defined. If not, then
  990 the <code>%elif</code> and <code>%else</code> blocks (if any) will be
  991 processed instead.</p>
  992 <p>For example, when debugging a program, you might want to write code such
  993 as</p>
  994 <pre>
  995           ; perform some function 
  996 %ifdef DEBUG 
  997           writefile 2,"Function performed successfully",13,10 
  998 %endif 
  999           ; go and do something else
 1000 </pre>
 1001 <p>Then you could use the command-line option <code>-dDEBUG</code> to
 1002 create a version of the program which produced debugging messages, and
 1003 remove the option to generate the final release version of the program.</p>
 1004 <p>You can test for a macro <em>not</em> being defined by using
 1005 <code>%ifndef</code> instead of <code>%ifdef</code>. You can also test for
 1006 macro definitions in <code>%elif</code> blocks by using
 1007 <code>%elifdef</code> and <code>%elifndef</code>.</p>
 1008 <h4 id="section-4.4.2">4.4.2 <code>%ifmacro</code>: Testing Multi-Line Macro Existence</h4>
 1009 <p>The <code>%ifmacro</code> directive operates in the same way as the
 1010 <code>%ifdef</code> directive, except that it checks for the existence of a
 1011 multi-line macro.</p>
 1012 <p>For example, you may be working with a large project and not have
 1013 control over the macros in a library. You may want to create a macro with
 1014 one name if it doesn't already exist, and another name if one with that
 1015 name does exist.</p>
 1016 <p>The <code>%ifmacro</code> is considered true if defining a macro with
 1017 the given name and number of arguments would cause a definitions conflict.
 1018 For example:</p>
 1019 <pre>
 1020 %ifmacro MyMacro 1-3 
 1022      %error "MyMacro 1-3" causes a conflict with an existing macro. 
 1024 %else 
 1026      %macro MyMacro 1-3 
 1028              ; insert code to define the macro 
 1030      %endmacro 
 1032 %endif
 1033 </pre>
 1034 <p>This will create the macro "MyMacro 1-3" if no macro already exists
 1035 which would conflict with it, and emits a warning if there would be a
 1036 definition conflict.</p>
 1037 <p>You can test for the macro not existing by using the
 1038 <code>%ifnmacro</code> instead of <code>%ifmacro</code>. Additional tests
 1039 can be performed in <code>%elif</code> blocks by using
 1040 <code>%elifmacro</code> and <code>%elifnmacro</code>.</p>
 1041 <h4 id="section-4.4.3">4.4.3 <code>%ifctx</code>: Testing the Context Stack</h4>
 1042 <p>The conditional-assembly construct <code>%ifctx</code> will cause the
 1043 subsequent code to be assembled if and only if the top context on the
 1044 preprocessor's context stack has the same name as one of the arguments. As
 1045 with <code>%ifdef</code>, the inverse and <code>%elif</code> forms
 1046 <code>%ifnctx</code>, <code>%elifctx</code> and <code>%elifnctx</code> are
 1047 also supported.</p>
 1048 <p>For more details of the context stack, see
 1049 <a href="#section-4.7">section 4.7</a>. For a sample use of
 1050 <code>%ifctx</code>, see <a href="#section-4.7.6">section 4.7.6</a>.</p>
 1051 <h4 id="section-4.4.4">4.4.4 <code>%if</code>: Testing Arbitrary Numeric Expressions</h4>
 1052 <p>The conditional-assembly construct <code>%if expr</code> will cause the
 1053 subsequent code to be assembled if and only if the value of the numeric
 1054 expression <code>expr</code> is non-zero. An example of the use of this
 1055 feature is in deciding when to break out of a <code>%rep</code>
 1056 preprocessor loop: see <a href="#section-4.5">section 4.5</a> for a
 1057 detailed example.</p>
 1058 <p>The expression given to <code>%if</code>, and its counterpart
 1059 <code>%elif</code>, is a critical expression (see
 1060 <a href="nasmdoc3.html#section-3.8">section 3.8</a>).</p>
 1061 <p>Like other <code>%if</code> constructs, <code>%if</code> has a
 1062 counterpart <code>%elif</code>, and negative forms <code>%ifn</code> and
 1063 <code>%elifn</code>.</p>
 1064 <h4 id="section-4.4.5">4.4.5 <code>%ifidn</code> and <code>%ifidni</code>: Testing Exact Text Identity</h4>
 1065 <p>The construct <code>%ifidn text1,text2</code> will cause the subsequent
 1066 code to be assembled if and only if <code>text1</code> and
 1067 <code>text2</code>, after expanding single-line macros, are identical
 1068 pieces of text. Differences in white space are not counted.</p>
 1069 <p><code>%ifidni</code> is similar to <code>%ifidn</code>, but is
 1070 case-insensitive.</p>
 1071 <p>For example, the following macro pushes a register or number on the
 1072 stack, and allows you to treat <code>IP</code> as a real register:</p>
 1073 <pre>
 1074 %macro  pushparam 1 
 1076   %ifidni %1,ip 
 1077         call    %%label 
 1078   %%label: 
 1079   %else 
 1080         push    %1 
 1081   %endif 
 1083 %endmacro
 1084 </pre>
 1085 <p>Like other <code>%if</code> constructs, <code>%ifidn</code> has a
 1086 counterpart <code>%elifidn</code>, and negative forms <code>%ifnidn</code>
 1087 and <code>%elifnidn</code>. Similarly, <code>%ifidni</code> has
 1088 counterparts <code>%elifidni</code>, <code>%ifnidni</code> and
 1089 <code>%elifnidni</code>.</p>
 1090 <h4 id="section-4.4.6">4.4.6 <code>%ifid</code>, <code>%ifnum</code>, <code>%ifstr</code>: Testing Token Types</h4>
 1091 <p>Some macros will want to perform different tasks depending on whether
 1092 they are passed a number, a string, or an identifier. For example, a string
 1093 output macro might want to be able to cope with being passed either a
 1094 string constant or a pointer to an existing string.</p>
 1095 <p>The conditional assembly construct <code>%ifid</code>, taking one
 1096 parameter (which may be blank), assembles the subsequent code if and only
 1097 if the first token in the parameter exists and is an identifier.
 1098 <code>%ifnum</code> works similarly, but tests for the token being a
 1099 numeric constant; <code>%ifstr</code> tests for it being a string.</p>
 1100 <p>For example, the <code>writefile</code> macro defined in
 1101 <a href="#section-4.3.3">section 4.3.3</a> can be extended to take
 1102 advantage of <code>%ifstr</code> in the following fashion:</p>
 1103 <pre>
 1104 %macro writefile 2-3+ 
 1106   %ifstr %2 
 1107         jmp     %%endstr 
 1108     %if %0 = 3 
 1109       %%str:    db      %2,%3 
 1110     %else 
 1111       %%str:    db      %2 
 1112     %endif 
 1113       %%endstr: mov     dx,%%str 
 1114                 mov     cx,%%endstr-%%str 
 1115   %else 
 1116                 mov     dx,%2 
 1117                 mov     cx,%3 
 1118   %endif 
 1119                 mov     bx,%1 
 1120                 mov     ah,0x40 
 1121                 int     0x21 
 1123 %endmacro
 1124 </pre>
 1125 <p>Then the <code>writefile</code> macro can cope with being called in
 1126 either of the following two ways:</p>
 1127 <pre>
 1128         writefile [file], strpointer, length 
 1129         writefile [file], "hello", 13, 10
 1130 </pre>
 1131 <p>In the first, <code>strpointer</code> is used as the address of an
 1132 already-declared string, and <code>length</code> is used as its length; in
 1133 the second, a string is given to the macro, which therefore declares it
 1134 itself and works out the address and length for itself.</p>
 1135 <p>Note the use of <code>%if</code> inside the <code>%ifstr</code>: this is
 1136 to detect whether the macro was passed two arguments (so the string would
 1137 be a single string constant, and <code>db %2</code> would be adequate) or
 1138 more (in which case, all but the first two would be lumped together into
 1139 <code>%3</code>, and <code>db %2,%3</code> would be required).</p>
 1140 <p>The usual <code>%elif</code>..., <code>%ifn</code>..., and
 1141 <code>%elifn</code>... versions exist for each of <code>%ifid</code>,
 1142 <code>%ifnum</code> and <code>%ifstr</code>.</p>
 1143 <h4 id="section-4.4.7">4.4.7 <code>%iftoken</code>: Test for a Single Token</h4>
 1144 <p>Some macros will want to do different things depending on if it is
 1145 passed a single token (e.g. paste it to something else using
 1146 <code>%+</code>) versus a multi-token sequence.</p>
 1147 <p>The conditional assembly construct <code>%iftoken</code> assembles the
 1148 subsequent code if and only if the expanded parameters consist of exactly
 1149 one token, possibly surrounded by whitespace.</p>
 1150 <p>For example:</p>
 1151 <pre>
 1152 %iftoken 1
 1153 </pre>
 1154 <p>will assemble the subsequent code, but</p>
 1155 <pre>
 1156 %iftoken -1
 1157 </pre>
 1158 <p>will not, since <code>-1</code> contains two tokens: the unary minus
 1159 operator <code>-</code>, and the number <code>1</code>.</p>
 1160 <p>The usual <code>%eliftoken</code>, <code>%ifntoken</code>, and
 1161 <code>%elifntoken</code> variants are also provided.</p>
 1162 <h4 id="section-4.4.8">4.4.8 <code>%ifempty</code>: Test for Empty Expansion</h4>
 1163 <p>The conditional assembly construct <code>%ifempty</code> assembles the
 1164 subsequent code if and only if the expanded parameters do not contain any
 1165 tokens at all, whitespace excepted.</p>
 1166 <p>The usual <code>%elifempty</code>, <code>%ifnempty</code>, and
 1167 <code>%elifnempty</code> variants are also provided.</p>
 1168 <h4 id="section-4.4.9">4.4.9 <code>%ifenv</code>: Test If Environment Variable Exists</h4>
 1169 <p>The conditional assembly construct <code>%ifenv</code> assembles the
 1170 subsequent code if and only if the environment variable referenced by the
 1171 <code>%!</code><em>variable</em> directive exists.</p>
 1172 <p>The usual <code>%elifenv</code>, <code>%ifnenv</code>, and
 1173 <code>%elifnenv</code> variants are also provided.</p>
 1174 <p>Just as for <code>%!</code><em>variable</em> the argument should be
 1175 written as a string if it contains characters that would not be legal in an
 1176 identifier. See <a href="#section-4.11.2">section 4.11.2</a>.</p>
 1177 <h3 id="section-4.5">4.5 Preprocessor Loops: <code>%rep</code></h3>
 1178 <p>NASM's <code>TIMES</code> prefix, though useful, cannot be used to
 1179 invoke a multi-line macro multiple times, because it is processed by NASM
 1180 after macros have already been expanded. Therefore NASM provides another
 1181 form of loop, this time at the preprocessor level: <code>%rep</code>.</p>
 1182 <p>The directives <code>%rep</code> and <code>%endrep</code>
 1183 (<code>%rep</code> takes a numeric argument, which can be an expression;
 1184 <code>%endrep</code> takes no arguments) can be used to enclose a chunk of
 1185 code, which is then replicated as many times as specified by the
 1186 preprocessor:</p>
 1187 <pre>
 1188 %assign i 0 
 1189 %rep    64 
 1190         inc     word [table+2*i] 
 1191 %assign i i+1 
 1192 %endrep
 1193 </pre>
 1194 <p>This will generate a sequence of 64 <code>INC</code> instructions,
 1195 incrementing every word of memory from <code>[table]</code> to
 1196 <code>[table+126]</code>.</p>
 1197 <p>For more complex termination conditions, or to break out of a repeat
 1198 loop part way along, you can use the <code>%exitrep</code> directive to
 1199 terminate the loop, like this:</p>
 1200 <pre>
 1201 fibonacci: 
 1202 %assign i 0 
 1203 %assign j 1 
 1204 %rep 100 
 1205 %if j &gt; 65535 
 1206     %exitrep 
 1207 %endif 
 1208         dw j 
 1209 %assign k j+i 
 1210 %assign i j 
 1211 %assign j k 
 1212 %endrep 
 1214 fib_number equ ($-fibonacci)/2
 1215 </pre>
 1216 <p>This produces a list of all the Fibonacci numbers that will fit in 16
 1217 bits. Note that a maximum repeat count must still be given to
 1218 <code>%rep</code>. This is to prevent the possibility of NASM getting into
 1219 an infinite loop in the preprocessor, which (on multitasking or multi-user
 1220 systems) would typically cause all the system memory to be gradually used
 1221 up and other applications to start crashing.</p>
 1222 <p>Note the maximum repeat count is limited to the value specified by the
 1223 <code>--limit-rep</code> option or <code>%pragma limit rep</code>, see
 1224 <a href="nasmdoc2.html#section-2.1.31">section 2.1.31</a>.</p>
 1225 <h3 id="section-4.6">4.6 Source Files and Dependencies</h3>
 1226 <p>These commands allow you to split your sources into multiple files.</p>
 1227 <h4 id="section-4.6.1">4.6.1 <code>%include</code>: Including Other Files</h4>
 1228 <p>Using, once again, a very similar syntax to the C preprocessor, NASM's
 1229 preprocessor lets you include other source files into your code. This is
 1230 done by the use of the <code>%include</code> directive:</p>
 1231 <pre>
 1232 %include "macros.mac"
 1233 </pre>
 1234 <p>will include the contents of the file <code>macros.mac</code> into the
 1235 source file containing the <code>%include</code> directive.</p>
 1236 <p>Include files are searched for in the current directory (the directory
 1237 you're in when you run NASM, as opposed to the location of the NASM
 1238 executable or the location of the source file), plus any directories
 1239 specified on the NASM command line using the <code>-i</code> option.</p>
 1240 <p>The standard C idiom for preventing a file being included more than once
 1241 is just as applicable in NASM: if the file <code>macros.mac</code> has the
 1242 form</p>
 1243 <pre>
 1244 %ifndef MACROS_MAC 
 1245     %define MACROS_MAC 
 1246     ; now define some macros 
 1247 %endif
 1248 </pre>
 1249 <p>then including the file more than once will not cause errors, because
 1250 the second time the file is included nothing will happen because the macro
 1251 <code>MACROS_MAC</code> will already be defined.</p>
 1252 <p>You can force a file to be included even if there is no
 1253 <code>%include</code> directive that explicitly includes it, by using the
 1254 <code>-p</code> option on the NASM command line (see
 1255 <a href="nasmdoc2.html#section-2.1.19">section 2.1.19</a>).</p>
 1256 <h4 id="section-4.6.2">4.6.2 <code>%pathsearch</code>: Search the Include Path</h4>
 1257 <p>The <code>%pathsearch</code> directive takes a single-line macro name
 1258 and a filename, and declare or redefines the specified single-line macro to
 1259 be the include-path-resolved version of the filename, if the file exists
 1260 (otherwise, it is passed unchanged.)</p>
 1261 <p>For example,</p>
 1262 <pre>
 1263 %pathsearch MyFoo "foo.bin"
 1264 </pre>
 1265 <p>... with <code>-Ibins/</code> in the include path may end up defining
 1266 the macro <code>MyFoo</code> to be <code>"bins/foo.bin"</code>.</p>
 1267 <h4 id="section-4.6.3">4.6.3 <code>%depend</code>: Add Dependent Files</h4>
 1268 <p>The <code>%depend</code> directive takes a filename and adds it to the
 1269 list of files to be emitted as dependency generation when the
 1270 <code>-M</code> options and its relatives (see
 1271 <a href="nasmdoc2.html#section-2.1.5">section 2.1.5</a>) are used. It
 1272 produces no output.</p>
 1273 <p>This is generally used in conjunction with <code>%pathsearch</code>. For
 1274 example, a simplified version of the standard macro wrapper for the
 1275 <code>INCBIN</code> directive looks like:</p>
 1276 <pre>
 1277 %imacro incbin 1-2+ 0 
 1278 %pathsearch dep %1 
 1279 %depend dep 
 1280         incbin dep,%2 
 1281 %endmacro
 1282 </pre>
 1283 <p>This first resolves the location of the file into the macro
 1284 <code>dep</code>, then adds it to the dependency lists, and finally issues
 1285 the assembler-level <code>INCBIN</code> directive.</p>
 1286 <h4 id="section-4.6.4">4.6.4 <code>%use</code>: Include Standard Macro Package</h4>
 1287 <p>The <code>%use</code> directive is similar to <code>%include</code>, but
 1288 rather than including the contents of a file, it includes a named standard
 1289 macro package. The standard macro packages are part of NASM, and are
 1290 described in <a href="nasmdoc6.html">chapter 6</a>.</p>
 1291 <p>Unlike the <code>%include</code> directive, package names for the
 1292 <code>%use</code> directive do not require quotes, but quotes are
 1293 permitted. In NASM 2.04 and 2.05 the unquoted form would be macro-expanded;
 1294 this is no longer true. Thus, the following lines are equivalent:</p>
 1295 <pre>
 1296 %use altreg 
 1297 %use 'altreg'
 1298 </pre>
 1299 <p>Standard macro packages are protected from multiple inclusion. When a
 1300 standard macro package is used, a testable single-line macro of the form
 1301 <code>__?USE_</code><em>package</em><code>?__</code> is also defined, see
 1302 <a href="nasmdoc5.html#section-5.7">section 5.7</a>.</p>
 1303 <h3 id="section-4.7">4.7 The Context Stack</h3>
 1304 <p>Having labels that are local to a macro definition is sometimes not
 1305 quite powerful enough: sometimes you want to be able to share labels
 1306 between several macro calls. An example might be a <code>REPEAT</code> ...
 1307 <code>UNTIL</code> loop, in which the expansion of the <code>REPEAT</code>
 1308 macro would need to be able to refer to a label which the
 1309 <code>UNTIL</code> macro had defined. However, for such a macro you would
 1310 also want to be able to nest these loops.</p>
 1311 <p>NASM provides this level of power by means of a <em>context stack</em>.
 1312 The preprocessor maintains a stack of <em>contexts</em>, each of which is
 1313 characterized by a name. You add a new context to the stack using the
 1314 <code>%push</code> directive, and remove one using <code>%pop</code>. You
 1315 can define labels that are local to a particular context on the stack.</p>
 1316 <h4 id="section-4.7.1">4.7.1 <code>%push</code> and <code>%pop</code>: Creating and Removing Contexts</h4>
 1317 <p>The <code>%push</code> directive is used to create a new context and
 1318 place it on the top of the context stack. <code>%push</code> takes an
 1319 optional argument, which is the name of the context. For example:</p>
 1320 <pre>
 1321 %push    foobar
 1322 </pre>
 1323 <p>This pushes a new context called <code>foobar</code> on the stack. You
 1324 can have several contexts on the stack with the same name: they can still
 1325 be distinguished. If no name is given, the context is unnamed (this is
 1326 normally used when both the <code>%push</code> and the <code>%pop</code>
 1327 are inside a single macro definition.)</p>
 1328 <p>The directive <code>%pop</code>, taking one optional argument, removes
 1329 the top context from the context stack and destroys it, along with any
 1330 labels associated with it. If an argument is given, it must match the name
 1331 of the current context, otherwise it will issue an error.</p>
 1332 <h4 id="section-4.7.2">4.7.2 Context-Local Labels</h4>
 1333 <p>Just as the usage <code>%%foo</code> defines a label which is local to
 1334 the particular macro call in which it is used, the usage <code>%$foo</code>
 1335 is used to define a label which is local to the context on the top of the
 1336 context stack. So the <code>REPEAT</code> and <code>UNTIL</code> example
 1337 given above could be implemented by means of:</p>
 1338 <pre>
 1339 %macro repeat 0 
 1341     %push   repeat 
 1342     %$begin: 
 1344 %endmacro 
 1346 %macro until 1 
 1348         j%-1    %$begin 
 1349     %pop 
 1351 %endmacro
 1352 </pre>
 1353 <p>and invoked by means of, for example,</p>
 1354 <pre>
 1355         mov     cx,string 
 1356         repeat 
 1357         add     cx,3 
 1358         scasb 
 1359         until   e
 1360 </pre>
 1361 <p>which would scan every fourth byte of a string in search of the byte in
 1362 <code>AL</code>.</p>
 1363 <p>If you need to define, or access, labels local to the context
 1364 <em>below</em> the top one on the stack, you can use <code>%$$foo</code>,
 1365 or <code>%$$$foo</code> for the context below that, and so on.</p>
 1366 <h4 id="section-4.7.3">4.7.3 Context-Local Single-Line Macros</h4>
 1367 <p>NASM also allows you to define single-line macros which are local to a
 1368 particular context, in just the same way:</p>
 1369 <pre>
 1370 %define %$localmac 3
 1371 </pre>
 1372 <p>will define the single-line macro <code>%$localmac</code> to be local to
 1373 the top context on the stack. Of course, after a subsequent
 1374 <code>%push</code>, it can then still be accessed by the name
 1375 <code>%$$localmac</code>.</p>
 1376 <h4 id="section-4.7.4">4.7.4 Context Fall-Through Lookup <em>(deprecated)</em></h4>
 1377 <p>Context fall-through lookup (automatic searching of outer contexts) is a
 1378 feature that was added in NASM version 0.98.03. Unfortunately, this feature
 1379 is unintuitive and can result in buggy code that would have otherwise been
 1380 prevented by NASM's error reporting. As a result, this feature has been
 1381 <em>deprecated</em>. NASM version 2.09 will issue a warning when usage of
 1382 this <em>deprecated</em> feature is detected. Starting with NASM version
 1383 2.10, usage of this <em>deprecated</em> feature will simply result in an
 1384 <em>expression syntax error</em>.</p>
 1385 <p>An example usage of this <em>deprecated</em> feature follows:</p>
 1386 <pre>
 1387 %macro ctxthru 0 
 1388 %push ctx1 
 1389     %assign %$external 1 
 1390         %push ctx2 
 1391             %assign %$internal 1 
 1392             mov eax, %$external 
 1393             mov eax, %$internal 
 1394         %pop 
 1395 %pop 
 1396 %endmacro
 1397 </pre>
 1398 <p>As demonstrated, <code>%$external</code> is being defined in the
 1399 <code>ctx1</code> context and referenced within the <code>ctx2</code>
 1400 context. With context fall-through lookup, referencing an undefined
 1401 context-local macro like this implicitly searches through all outer
 1402 contexts until a match is made or isn't found in any context. As a result,
 1403 <code>%$external</code> referenced within the <code>ctx2</code> context
 1404 would implicitly use <code>%$external</code> as defined in
 1405 <code>ctx1</code>. Most people would expect NASM to issue an error in this
 1406 situation because <code>%$external</code> was never defined within
 1407 <code>ctx2</code> and also isn't qualified with the proper context depth,
 1408 <code>%$$external</code>.</p>
 1409 <p>Here is a revision of the above example with proper context depth:</p>
 1410 <pre>
 1411 %macro ctxthru 0 
 1412 %push ctx1 
 1413     %assign %$external 1 
 1414         %push ctx2 
 1415             %assign %$internal 1 
 1416             mov eax, %$$external 
 1417             mov eax, %$internal 
 1418         %pop 
 1419 %pop 
 1420 %endmacro
 1421 </pre>
 1422 <p>As demonstrated, <code>%$external</code> is still being defined in the
 1423 <code>ctx1</code> context and referenced within the <code>ctx2</code>
 1424 context. However, the reference to <code>%$external</code> within
 1425 <code>ctx2</code> has been fully qualified with the proper context depth,
 1426 <code>%$$external</code>, and thus is no longer ambiguous, unintuitive or
 1427 erroneous.</p>
 1428 <h4 id="section-4.7.5">4.7.5 <code>%repl</code>: Renaming a Context</h4>
 1429 <p>If you need to change the name of the top context on the stack (in
 1430 order, for example, to have it respond differently to <code>%ifctx</code>),
 1431 you can execute a <code>%pop</code> followed by a <code>%push</code>; but
 1432 this will have the side effect of destroying all context-local labels and
 1433 macros associated with the context that was just popped.</p>
 1434 <p>NASM provides the directive <code>%repl</code>, which <em>replaces</em>
 1435 a context with a different name, without touching the associated macros and
 1436 labels. So you could replace the destructive code</p>
 1437 <pre>
 1438 %pop 
 1439 %push   newname
 1440 </pre>
 1441 <p>with the non-destructive version <code>%repl newname</code>.</p>
 1442 <h4 id="section-4.7.6">4.7.6 Example Use of the Context Stack: Block IFs</h4>
 1443 <p>This example makes use of almost all the context-stack features,
 1444 including the conditional-assembly construct <code>%ifctx</code>, to
 1445 implement a block IF statement as a set of macros.</p>
 1446 <pre>
 1447 %macro if 1 
 1449     %push if 
 1450     j%-1  %$ifnot 
 1452 %endmacro 
 1454 %macro else 0 
 1456   %ifctx if 
 1457         %repl   else 
 1458         jmp     %$ifend 
 1459         %$ifnot: 
 1460   %else 
 1461         %error  "expected `if' before `else'" 
 1462   %endif 
 1464 %endmacro 
 1466 %macro endif 0 
 1468   %ifctx if 
 1469         %$ifnot: 
 1470         %pop 
 1471   %elifctx      else 
 1472         %$ifend: 
 1473         %pop 
 1474   %else 
 1475         %error  "expected `if' or `else' before `endif'" 
 1476   %endif 
 1478 %endmacro
 1479 </pre>
 1480 <p>This code is more robust than the <code>REPEAT</code> and
 1481 <code>UNTIL</code> macros given in <a href="#section-4.7.2">section
 1482 4.7.2</a>, because it uses conditional assembly to check that the macros
 1483 are issued in the right order (for example, not calling <code>endif</code>
 1484 before <code>if</code>) and issues a <code>%error</code> if they're not.</p>
 1485 <p>In addition, the <code>endif</code> macro has to be able to cope with
 1486 the two distinct cases of either directly following an <code>if</code>, or
 1487 following an <code>else</code>. It achieves this, again, by using
 1488 conditional assembly to do different things depending on whether the
 1489 context on top of the stack is <code>if</code> or <code>else</code>.</p>
 1490 <p>The <code>else</code> macro has to preserve the context on the stack, in
 1491 order to have the <code>%$ifnot</code> referred to by the <code>if</code>
 1492 macro be the same as the one defined by the <code>endif</code> macro, but
 1493 has to change the context's name so that <code>endif</code> will know there
 1494 was an intervening <code>else</code>. It does this by the use of
 1495 <code>%repl</code>.</p>
 1496 <p>A sample usage of these macros might look like:</p>
 1497 <pre>
 1498         cmp     ax,bx 
 1500         if ae 
 1501                cmp     bx,cx 
 1503                if ae 
 1504                        mov     ax,cx 
 1505                else 
 1506                        mov     ax,bx 
 1507                endif 
 1509         else 
 1510                cmp     ax,cx 
 1512                if ae 
 1513                        mov     ax,cx 
 1514                endif 
 1516         endif
 1517 </pre>
 1518 <p>The block-<code>IF</code> macros handle nesting quite happily, by means
 1519 of pushing another context, describing the inner <code>if</code>, on top of
 1520 the one describing the outer <code>if</code>; thus <code>else</code> and
 1521 <code>endif</code> always refer to the last unmatched <code>if</code> or
 1522 <code>else</code>.</p>
 1523 <h3 id="section-4.8">4.8 Stack Relative Preprocessor Directives</h3>
 1524 <p>The following preprocessor directives provide a way to use labels to
 1525 refer to local variables allocated on the stack.</p>
 1526 <ul>
 1527 <li>
 1528 <p><code>%arg</code> (see <a href="#section-4.8.1">section 4.8.1</a>)</p>
 1529 </li>
 1530 <li>
 1531 <p><code>%stacksize</code> (see <a href="#section-4.8.2">section 4.8.2</a>)</p>
 1532 </li>
 1533 <li>
 1534 <p><code>%local</code> (see <a href="#section-4.8.3">section 4.8.3</a>)</p>
 1535 </li>
 1536 </ul>
 1537 <h4 id="section-4.8.1">4.8.1 <code>%arg</code> Directive</h4>
 1538 <p>The <code>%arg</code> directive is used to simplify the handling of
 1539 parameters passed on the stack. Stack based parameter passing is used by
 1540 many high level languages, including C, C++ and Pascal.</p>
 1541 <p>While NASM has macros which attempt to duplicate this functionality (see
 1542 <a href="nasmdoc9.html#section-9.4.5">section 9.4.5</a>), the syntax is not
 1543 particularly convenient to use and is not TASM compatible. Here is an
 1544 example which shows the use of <code>%arg</code> without any external
 1545 macros:</p>
 1546 <pre>
 1547 some_function: 
 1549     %push     mycontext        ; save the current context 
 1550     %stacksize large           ; tell NASM to use bp 
 1551     %arg      i:word, j_ptr:word 
 1553         mov     ax,[i] 
 1554         mov     bx,[j_ptr] 
 1555         add     ax,[bx] 
 1556         ret 
 1558     %pop                       ; restore original context
 1559 </pre>
 1560 <p>This is similar to the procedure defined in
 1561 <a href="nasmdoc9.html#section-9.4.5">section 9.4.5</a> and adds the value
 1562 in i to the value pointed to by j_ptr and returns the sum in the ax
 1563 register. See <a href="#section-4.7.1">section 4.7.1</a> for an explanation
 1564 of <code>push</code> and <code>pop</code> and the use of context stacks.</p>
 1565 <h4 id="section-4.8.2">4.8.2 <code>%stacksize</code> Directive</h4>
 1566 <p>The <code>%stacksize</code> directive is used in conjunction with the
 1567 <code>%arg</code> (see <a href="#section-4.8.1">section 4.8.1</a>) and the
 1568 <code>%local</code> (see <a href="#section-4.8.3">section 4.8.3</a>)
 1569 directives. It tells NASM the default size to use for subsequent
 1570 <code>%arg</code> and <code>%local</code> directives. The
 1571 <code>%stacksize</code> directive takes one required argument which is one
 1572 of <code>flat</code>, <code>flat64</code>, <code>large</code> or
 1573 <code>small</code>.</p>
 1574 <pre>
 1575 %stacksize flat
 1576 </pre>
 1577 <p>This form causes NASM to use stack-based parameter addressing relative
 1578 to <code>ebp</code> and it assumes that a near form of call was used to get
 1579 to this label (i.e. that <code>eip</code> is on the stack).</p>
 1580 <pre>
 1581 %stacksize flat64
 1582 </pre>
 1583 <p>This form causes NASM to use stack-based parameter addressing relative
 1584 to <code>rbp</code> and it assumes that a near form of call was used to get
 1585 to this label (i.e. that <code>rip</code> is on the stack).</p>
 1586 <pre>
 1587 %stacksize large
 1588 </pre>
 1589 <p>This form uses <code>bp</code> to do stack-based parameter addressing
 1590 and assumes that a far form of call was used to get to this address (i.e.
 1591 that <code>ip</code> and <code>cs</code> are on the stack).</p>
 1592 <pre>
 1593 %stacksize small
 1594 </pre>
 1595 <p>This form also uses <code>bp</code> to address stack parameters, but it
 1596 is different from <code>large</code> because it also assumes that the old
 1597 value of bp is pushed onto the stack (i.e. it expects an <code>ENTER</code>
 1598 instruction). In other words, it expects that <code>bp</code>,
 1599 <code>ip</code> and <code>cs</code> are on the top of the stack, underneath
 1600 any local space which may have been allocated by <code>ENTER</code>. This
 1601 form is probably most useful when used in combination with the
 1602 <code>%local</code> directive (see <a href="#section-4.8.3">section
 1603 4.8.3</a>).</p>
 1604 <h4 id="section-4.8.3">4.8.3 <code>%local</code> Directive</h4>
 1605 <p>The <code>%local</code> directive is used to simplify the use of local
 1606 temporary stack variables allocated in a stack frame. Automatic local
 1607 variables in C are an example of this kind of variable. The
 1608 <code>%local</code> directive is most useful when used with the
 1609 <code>%stacksize</code> (see <a href="#section-4.8.2">section 4.8.2</a> and
 1610 is also compatible with the <code>%arg</code> directive (see
 1611 <a href="#section-4.8.1">section 4.8.1</a>). It allows simplified reference
 1612 to variables on the stack which have been allocated typically by using the
 1613 <code>ENTER</code> instruction. An example of its use is the following:</p>
 1614 <pre>
 1615 silly_swap: 
 1617     %push mycontext             ; save the current context 
 1618     %stacksize small            ; tell NASM to use bp 
 1619     %assign %$localsize 0       ; see text for explanation 
 1620     %local old_ax:word, old_dx:word 
 1622         enter   %$localsize,0   ; see text for explanation 
 1623         mov     [old_ax],ax     ; swap ax &amp; bx 
 1624         mov     [old_dx],dx     ; and swap dx &amp; cx 
 1625         mov     ax,bx 
 1626         mov     dx,cx 
 1627         mov     bx,[old_ax] 
 1628         mov     cx,[old_dx] 
 1629         leave                   ; restore old bp 
 1630         ret                     ; 
 1632     %pop                        ; restore original context
 1633 </pre>
 1634 <p>The <code>%$localsize</code> variable is used internally by the
 1635 <code>%local</code> directive and <em>must</em> be defined within the
 1636 current context before the <code>%local</code> directive may be used.
 1637 Failure to do so will result in one expression syntax error for each
 1638 <code>%local</code> variable declared. It then may be used in the
 1639 construction of an appropriately sized ENTER instruction as shown in the
 1640 example.</p>
 1641 <h3 id="section-4.9">4.9 Reporting User-Defined Errors: <code>%error</code>, <code>%warning</code>, <code>%fatal</code></h3>
 1642 <p>The preprocessor directive <code>%error</code> will cause NASM to report
 1643 an error if it occurs in assembled code. So if other users are going to try
 1644 to assemble your source files, you can ensure that they define the right
 1645 macros by means of code like this:</p>
 1646 <pre>
 1647 %ifdef F1 
 1648     ; do some setup 
 1649 %elifdef F2 
 1650     ; do some different setup 
 1651 %else 
 1652     %error "Neither F1 nor F2 was defined." 
 1653 %endif
 1654 </pre>
 1655 <p>Then any user who fails to understand the way your code is supposed to
 1656 be assembled will be quickly warned of their mistake, rather than having to
 1657 wait until the program crashes on being run and then not knowing what went
 1658 wrong.</p>
 1659 <p>Similarly, <code>%warning</code> issues a warning, but allows assembly
 1660 to continue:</p>
 1661 <pre>
 1662 %ifdef F1 
 1663     ; do some setup 
 1664 %elifdef F2 
 1665     ; do some different setup 
 1666 %else 
 1667     %warning "Neither F1 nor F2 was defined, assuming F1." 
 1668     %define F1 
 1669 %endif
 1670 </pre>
 1671 <p><code>%error</code> and <code>%warning</code> are issued only on the
 1672 final assembly pass. This makes them safe to use in conjunction with tests
 1673 that depend on symbol values.</p>
 1674 <p><code>%fatal</code> terminates assembly immediately, regardless of pass.
 1675 This is useful when there is no point in continuing the assembly further,
 1676 and doing so is likely just going to cause a spew of confusing error
 1677 messages.</p>
 1678 <p>It is optional for the message string after <code>%error</code>,
 1679 <code>%warning</code> or <code>%fatal</code> to be quoted. If it is
 1680 <em>not</em>, then single-line macros are expanded in it, which can be used
 1681 to display more information to the user. For example:</p>
 1682 <pre>
 1683 %if foo &gt; 64 
 1684     %assign foo_over foo-64 
 1685     %error foo is foo_over bytes too large 
 1686 %endif
 1687 </pre>
 1688 <h3 id="section-4.10">4.10 <code>%pragma</code>: Setting Options</h3>
 1689 <p>The <code>%pragma</code> directive controls a number of options in NASM.
 1690 Pragmas are intended to remain backwards compatible, and therefore an
 1691 unknown <code>%pragma</code> directive is not an error.</p>
 1692 <p>The various pragmas are documented with the options they affect.</p>
 1693 <p>The general structure of a NASM pragma is:</p>
 1694 <p><code>%pragma</code> <em>namespace</em> <em>directive</em>
 1695 [<em>arguments...</em>]</p>
 1696 <p>Currently defined namespaces are:</p>
 1697 <ul>
 1698 <li>
 1699 <p><code>ignore</code>: this <code>%pragma</code> is unconditionally
 1700 ignored.</p>
 1701 </li>
 1702 <li>
 1703 <p><code>preproc</code>: preprocessor, see
 1704 <a href="#section-4.10.1">section 4.10.1</a>.</p>
 1705 </li>
 1706 <li>
 1707 <p><code>limit</code>: resource limits, see
 1708 <a href="nasmdoc2.html#section-2.1.31">section 2.1.31</a>.</p>
 1709 </li>
 1710 <li>
 1711 <p><code>asm</code>: the parser and assembler proper. Currently no such
 1712 pragmas are defined.</p>
 1713 </li>
 1714 <li>
 1715 <p><code>list</code>: listing options, see
 1716 <a href="nasmdoc2.html#section-2.1.4">section 2.1.4</a>.</p>
 1717 </li>
 1718 <li>
 1719 <p><code>file</code>: general file handling options. Currently no such
 1720 pragmas are defined.</p>
 1721 </li>
 1722 <li>
 1723 <p><code>input</code>: input file handling options. Currently no such
 1724 pragmas are defined.</p>
 1725 </li>
 1726 <li>
 1727 <p><code>output</code>: output format options.</p>
 1728 </li>
 1729 <li>
 1730 <p><code>debug</code>: debug format options.</p>
 1731 </li>
 1732 </ul>
 1733 <p>In addition, the name of any output or debug format, and sometimes
 1734 groups thereof, also constitue <code>%pragma</code> namespaces. The
 1735 namespaces <code>output</code> and <code>debug</code> simply refer to
 1736 <em>any</em> output or debug format, respectively.</p>
 1737 <p>For example, to prepend an underscore to global symbols regardless of
 1738 the output format (see <a href="nasmdoc7.html#section-7.10">section
 1739 7.10</a>):</p>
 1740 <pre>
 1741 %pragma output gprefix _
 1742 </pre>
 1743 <p>... whereas to prepend an underscore to global symbols only when the
 1744 output is either <code>win32</code> or <code>win64</code>:</p>
 1745 <pre>
 1746 %pragma win gprefix _
 1747 </pre>
 1748 <h4 id="section-4.10.1">4.10.1 Preprocessor Pragmas</h4>
 1749 <p>The only preprocessor <code>%pragma</code> defined in NASM 2.15 is:</p>
 1750 <ul>
 1751 <li>
 1752 <p><code>%pragma preproc sane_empty_expansion</code>: disables legacy
 1753 compatibility handling of braceless empty arguments to multi-line macros.
 1754 See <a href="#section-4.3">section 4.3</a> and
 1755 <a href="nasmdoc2.html#section-2.1.26">section 2.1.26</a>.</p>
 1756 </li>
 1757 </ul>
 1758 <h3 id="section-4.11">4.11 Other Preprocessor Directives</h3>
 1759 <h4 id="section-4.11.1">4.11.1 <code>%line</code> Directive</h4>
 1760 <p>The <code>%line</code> directive is used to notify NASM that the input
 1761 line corresponds to a specific line number in another file. Typically this
 1762 other file would be an original source file, with the current NASM input
 1763 being the output of a pre-processor. The <code>%line</code> directive
 1764 allows NASM to output messages which indicate the line number of the
 1765 original source file, instead of the file that is being read by NASM.</p>
 1766 <p>This preprocessor directive is not generally used directly by
 1767 programmers, but may be of interest to preprocessor authors. The usage of
 1768 the <code>%line</code> preprocessor directive is as follows:</p>
 1769 <pre>
 1770 %line nnn[+mmm] [filename]
 1771 </pre>
 1772 <p>In this directive, <code>nnn</code> identifies the line of the original
 1773 source file which this line corresponds to. <code>mmm</code> is an optional
 1774 parameter which specifies a line increment value; each line of the input
 1775 file read in is considered to correspond to <code>mmm</code> lines of the
 1776 original source file. Finally, <code>filename</code> is an optional
 1777 parameter which specifies the file name of the original source file. It may
 1778 be a quoted string, in which case any additional argument after the quoted
 1779 string will be ignored.</p>
 1780 <p>After reading a <code>%line</code> preprocessor directive, NASM will
 1781 report all file name and line numbers relative to the values specified
 1782 therein.</p>
 1783 <p>If the command line option <code>--no-line</code> is given, all
 1784 <code>%line</code> directives are ignored. This may be useful for debugging
 1785 preprocessed code. See <a href="nasmdoc2.html#section-2.1.33">section
 1786 2.1.33</a>.</p>
 1787 <p>Starting in NASM 2.15, <code>%line</code> directives are processed
 1788 before any other processing takes place.</p>
 1789 <p>For compatibility with the output from some other preprocessors,
 1790 including many C preprocessors, a <code>#</code> character followed by
 1791 whitespace <em>at the very beginning of a line</em> is also treated as a
 1792 <code>%line</code> directive, except that double quotes surrounding the
 1793 filename are treated like NASM backquotes, with
 1794 <code>\</code>&ndash;escaped sequences decoded.</p>
 1795 <h4 id="section-4.11.2">4.11.2 <code>%!</code><em>variable</em>: Read an Environment Variable.</h4>
 1796 <p>The <code>%!</code><em>variable</em> directive makes it possible to read
 1797 the value of an environment variable at assembly time. This could, for
 1798 example, be used to store the contents of an environment variable into a
 1799 string, which could be used at some other point in your code.</p>
 1800 <p>For example, suppose that you have an environment variable
 1801 <code>FOO</code>, and you want the contents of <code>FOO</code> to be
 1802 embedded in your program as a quoted string. You could do that as follows:</p>
 1803 <pre>
 1804 %defstr FOO          %!FOO
 1805 </pre>
 1806 <p>See <a href="#section-4.1.9">section 4.1.9</a> for notes on the
 1807 <code>%defstr</code> directive.</p>
 1808 <p>If the name of the environment variable contains non-identifier
 1809 characters, you can use string quotes to surround the name of the variable,
 1810 for example:</p>
 1811 <pre>
 1812 %defstr C_colon      %!'C:'
 1813 </pre>
 1814 <h4 id="section-4.11.3">4.11.3 <code>%clear</code>: Clear All Macro Definitions</h4>
 1815 <p>The directive <code>%clear</code> clears all definitions of a certain
 1816 type, <em>including the ones defined by NASM itself.</em> This can be
 1817 useful when preprocessing non-NASM code, or to drop backwards compatibility
 1818 aliases.</p>
 1819 <p>The syntax is:</p>
 1820 <pre>
 1821    %clear [global|context] type...
 1822 </pre>
 1823 <p>... where <code>context</code> indicates that this applies to
 1824 context-local macros only; the default is <code>global</code>.</p>
 1825 <p><code>type</code> can be one or more of:</p>
 1826 <ul>
 1827 <li>
 1828 <p><code>define</code> single-line macros</p>
 1829 </li>
 1830 <li>
 1831 <p><code>defalias</code> single-line macro aliases (useful to remove
 1832 backwards compatibility aliases)</p>
 1833 </li>
 1834 <li>
 1835 <p><code>alldefine</code> same as <code>define defalias</code></p>
 1836 </li>
 1837 <li>
 1838 <p><code>macro</code> multi-line macros</p>
 1839 </li>
 1840 <li>
 1841 <p><code>all</code> same as <code>alldefine macro</code> (default)</p>
 1842 </li>
 1843 </ul>
 1844 <p>In NASM 2.14 and earlier, only the single syntax <code>%clear</code> was
 1845 supported, which is equivalent to <code>%clear global all</code>.</p>
 1846 </div>
 1847 </body>
 1848 </html>