The Netwide Assembler: NASM

Next Chapter | Previous Chapter | Contents | Index

Chapter 4: The NASM Preprocessor

NASM contains a powerful macro processor, which supports conditional assembly, multi-level file inclusion, two forms of macro (single-line and multi-line), and a `context stack' mechanism for extra macro power. Preprocessor directives all begin with a % sign.

The preprocessor collapses all lines which end with a backslash (\) character into a single line. Thus:

%define THIS_VERY_LONG_MACRO_NAME_IS_DEFINED_TO \ 
        THIS_VALUE

will work as expected.

4.1 Single-Line Macros

4.1.1 The Normal Way: `%define`

Single-line macros are defined using the %define preprocessor directive. The definitions work in a similar way to C; so you can do things like

%define ctrl 0x1F & 
%define param(a,b) ((a)+(a)*(b)) 
          mov byte [param(2,ebx)], ctrl 'D'

which will expand to

          mov byte [(2)+(2)*(ebx)], 0x1F & 'D'

When the expansion of a single-line macro contains tokens which invoke another macro, the expansion is performed at invocation time, not at definition time. Thus the code

%define a(x) 1+b(x) 
%define b(x) 2*x 
          mov ax,a(8)

will evaluate in the expected way to mov ax,1+2*8, even though the macro b wasn't defined at the time of definition of a.

Macros defined with %define are case sensitive: after %define foo bar, only foo will expand to bar: Foo or FOO will not. By using %idefine instead of %define (the `i' stands for `insensitive') you can define all the case variants of a macro at once, so that %idefine foo bar would cause foo, Foo, FOO, fOO and so on all to expand to bar.

There is a mechanism which detects when a macro call has occurred as a result of a previous expansion of the same macro, to guard against circular references and infinite loops. If this happens, the preprocessor will only expand the first occurrence of the macro. Hence, if you code

%define a(x) 1+a(x) 
          mov ax,a(3)

the macro a(3) will expand once, becoming 1+a(3), and will then expand no further. This behaviour can be useful: see section 8.1 for an example of its use.

You can overload single-line macros: if you write

%define foo(x) 1+x 
%define foo(x,y) 1+x*y

the preprocessor will be able to handle both types of macro call, by counting the parameters you pass; so foo(3) will become 1+3 whereas foo(ebx,2) will become 1+ebx*2. However, if you define

%define foo bar

then no other definition of foo will be accepted: a macro with no parameters prohibits the definition of the same name as a macro with parameters, and vice versa.

This doesn't prevent single-line macros being redefined: you can perfectly well define a macro with

%define foo bar

and then re-define it later in the same source file with

%define foo baz

Then everywhere the macro foo is invoked, it will be expanded according to the most recent definition. This is particularly useful when defining single-line macros with %assign (see section 4.1.3).

You can pre-define single-line macros using the `-d' option on the NASM command line: see section 2.1.11.

4.1.2 Undefining macros: `%undef`

Single-line macros can be removed with the %undef command. For example, the following sequence:

%define foo bar 
%undef foo 
		mov eax, foo

will expand to the instruction mov eax, foo, since after %undef the macro foo is no longer defined.

Macros that would otherwise be pre-defined can be undefined on the command-line using the `-u' option on the NASM command line: see section 2.1.12.

4.1.3 Preprocessor Variables: `%assign`

An alternative way to define single-line macros is by means of the %assign command (and its case sensitivecase-insensitive counterpart %iassign, which differs from %assign in exactly the same way that %idefine differs from %define).

%assign is used to define single-line macros which take no parameters and have a numeric value. This value can be specified in the form of an expression, and it will be evaluated once, when the %assign directive is processed.

Like %define, macros defined using %assign can be re-defined later, so you can do things like

%assign i i+1

to increment the numeric value of a macro.

%assign is useful for controlling the termination of %rep preprocessor loops: see section 4.5 for an example of this. Another use for %assign is given in section 7.4 and section 8.1.

The expression passed to %assign is a critical expression (see section 3.7), and must also evaluate to a pure number (rather than a relocatable reference such as a code or data address, or anything involving a register).

4.2 String Handling in Macros: `%strlen` and `%substr`

It's often useful to be able to handle strings in macros. NASM supports two simple string handling macro operators from which more complex operations can be constructed.

4.2.1 String Length: `%strlen`

The %strlen macro is like %assign macro in that it creates (or redefines) a numeric value to a macro. The difference is that with %strlen, the numeric value is the length of a string. An example of the use of this would be:

%strlen charcnt 'my string'

In this example, charcnt would receive the value 8, just as if an %assign had been used. In this example, 'my string' was a literal string but it could also have been a single-line macro that expands to a string, as in the following example:

%define sometext 'my string' 
%strlen charcnt sometext

As in the first case, this would result in charcnt being assigned the value of 8.

4.2.2 Sub-strings: `%substr`

Individual letters in strings can be extracted using %substr. An example of its use is probably more useful than the description:

%substr mychar 'xyz' 1  ; equivalent to %define mychar 'x' 
%substr mychar 'xyz' 2  ; equivalent to %define mychar 'y' 
%substr mychar 'xyz' 3  ; equivalent to %define mychar 'z'

In this example, mychar gets the value of 'y'. As with %strlen (see section 4.2.1), the first parameter is the single-line macro to be created and the second is the string. The third parameter specifies which character is to be selected. Note that the first index is 1, not 0 and the last index is equal to the value that %strlen would assign given the same string. Index values out of range result in an empty string.

4.3 Multi-Line Macros: `%macro`

Multi-line macros are much more like the type of macro seen in MASM and TASM: a multi-line macro definition in NASM looks something like this.

%macro prologue 1 
          push ebp 
          mov ebp,esp 
          sub esp,%1 
%endmacro

This defines a C-like function prologue as a macro: so you would invoke the macro with a call such as

myfunc:   prologue 12

which would expand to the three lines of code

myfunc:   push ebp 
          mov ebp,esp 
          sub esp,12

The number 1 after the macro name in the %macro line defines the number of parameters the macro prologue expects to receive. The use of %1 inside the macro definition refers to the first parameter to the macro call. With a macro taking more than one parameter, subsequent parameters would be referred to as %2, %3 and so on.

Multi-line macros, like single-line macros, are case-sensitive, unless you define them using the alternative directive %imacro.

If you need to pass a comma as part of a parameter to a multi-line macro, you can do that by enclosing the entire parameter in braces. So you could code things like

%macro silly 2 
%2:       db %1 
%endmacro 
          silly 'a', letter_a    ; letter_a:  db 'a' 
          silly 'ab', string_ab  ; string_ab: db 'ab' 
          silly {13,10}, crlf    ; crlf:      db 13,10

4.3.1 Overloading Multi-Line Macros

As with single-line macros, multi-line macros can be overloaded by defining the same macro name several times with different numbers of parameters. This time, no exception is made for macros with no parameters at all. So you could define

%macro prologue 0 
          push ebp 
          mov ebp,esp 
%endmacro

to define an alternative form of the function prologue which

the macro a(3) will expand once, becoming 1+a(3), and will then expand no further. This behaviour can be useful: see section 8.1 for an example of its use.

You can overload single-line macros: if you write

%define foo(x) 1+x 
%define foo(x,y) 1+x*y

the preprocessor will be able to handle both types of macro call, by counting the parameters you pass; so foo(3) will become 1+3 whereas foo(ebx,2) will become 1+ebx*2. However, if you define

%define foo bar

then no other definition of foo will be accepted: a macro with no parameters prohibits the definition of the same name as a macro with parameters, and vice versa.

This doesn't prevent single-line macros being redefined: you can perfectly well define a macro with

%define foo bar

and then re-define it later in the same source file with

%define foo baz

You can pre-define single-line macros using the `-d' option on the NASM command line: see section 2.1.11.

4.1.2 Undefining macros: `%undef`

Single-line macros can be removed with the %undef command. For example, the following sequence:

%define foo bar 
%undef foo 
		mov eax, foo

will expand to the instruction mov eax, foo, since after %undef the macro foo is no longer defined.

Macros that would otherwise be pre-defined can be undefined on the command-line using the `-u' option on the NASM command line: see section 2.1.12.

4.1.3 Preprocessor Variables: `%assign`

Like %define, macros defined using %assign can be re-defined later, so you can do things like

%assign i i+1

to increment the numeric value of a macro.

%assign is useful for controlling the termination of %rep preprocessor loops: see section 4.5 for an example of this. Another use for %assign is given in section 7.4 and section 8.1.

4.2 String Handling in Macros: `%strlen` and `%substr`

It's often useful to be able to handle strings in macros. NASM supports two simple string handling macro operators from which more complex operations can be constructed.

4.2.1 String Length: `%strlen`

%strlen charcnt 'my string'

%define sometext 'my string' 
%strlen charcnt sometext

As in the first case, this would result in charcnt being assigned the value of 8.

4.2.2 Sub-strings: `%substr`

Individual letters in strings can be extracted using %substr. An example of its use is probably more useful than the description:

%substr mychar 'xyz' 1  ; equivalent to %define mychar 'x' 
%substr mychar 'xyz' 2  ; equivalent to %define mychar 'y' 
%substr mychar 'xyz' 3  ; equivalent to %define mychar 'z'

4.3 Multi-Line Macros: `%macro`

Multi-line macros are much more like the type of macro seen in MASM and TASM: a multi-line macro definition in NASM looks something like this.

%macro prologue 1 
          push ebp 
          mov ebp,esp 
          sub esp,%1 
%endmacro

This defines a C-like function prologue as a macro: so you would invoke the macro with a call such as

myfunc:   prologue 12

which would expand to the three lines of code

myfunc:   push ebp 
          mov ebp,esp 
          sub esp,12

Multi-line macros, like single-line macros, are case-sensitive, unless you define them using the alternative directive %imacro.

If you need to pass a comma as part of a parameter to a multi-line macro, you can do that by enclosing the entire parameter in braces. So you could code things like

%macro silly 2 
%2:       db %1 
%endmacro 
          silly 'a', letter_a    ; letter_a:  db 'a' 
          silly 'ab', string_ab  ; string_ab: db 'ab' 
          silly {13,10}, crlf    ; crlf:      db 13,10

4.3.1 Overloading Multi-Line Macros

%macro prologue 0 
          push ebp 
          mov ebp,esp 
%endmacro

to define an alternative form of the function prologue which

the macro a(3) will expand once, becoming 1+a(3), and will then expand no further. This behaviour can be useful: see section 8.1 for an example of its use.

You can overload single-line macros: if you write

%define foo(x) 1+x 
%define foo(x,y) 1+x*y

the preprocessor will be able to handle both types of macro call, by counting the parameters you pass; so foo(3) will become 1+3 whereas foo(ebx,2) will become 1+ebx*2. However, if you define

%define foo bar

then no other definition of foo will be accepted: a macro with no parameters prohibits the definition of the same name as a macro with parameters, and vice versa.

This doesn't prevent single-line macros being redefined: you can perfectly well define a macro with

%define foo bar

and then re-define it later in the same source file with

%define foo baz

You can pre-define single-line macros using the `-d' option on the NASM command line: see section 2.1.11.

4.1.2 Undefining macros: `%undef`

Single-line macros can be removed with the %undef command. For example, the following sequence:

%define foo bar 
%undef foo 
		mov eax, foo

will expand to the instruction mov eax, foo, since after %undef the macro foo is no longer defined.

Macros that would otherwise be pre-defined can be undefined on the command-line using the `-u' option on the NASM command line: see section 2.1.12.

4.1.3 Preprocessor Variables: `%assign`

Like %define, macros defined using %assign can be re-defined later, so you can do things like

%assign i i+1

to increment the numeric value of a macro.

%assign is useful for controlling the termination of %rep preprocessor loops: see section 4.5 for an example of this. Another use for %assign is given in section 7.4 and section 8.1.

4.2 String Handling in Macros: `%strlen` and `%substr`

It's often useful to be able to handle strings in macros. NASM supports two simple string handling macro operators from which more complex operations can be constructed.

4.2.1 String Length: `%strlen`

%strlen charcnt 'my string'

%define sometext 'my string' 
%strlen charcnt sometext

As in the first case, this would result in charcnt being assigned the value of 8.

4.2.2 Sub-strings: `%substr`

Individual letters in strings can be extracted using %substr. An example of its use is probably more useful than the description:

%substr mychar 'xyz' 1  ; equivalent to %define mychar 'x' 
%substr mychar 'xyz' 2  ; equivalent to %define mychar 'y' 
%substr mychar 'xyz' 3  ; equivalent to %define mychar 'z'

4.3 Multi-Line Macros: `%macro`

Multi-line macros are much more like the type of macro seen in MASM and TASM: a multi-line macro definition in NASM looks something like this.

%macro prologue 1 
          push ebp 
          mov ebp,esp 
          sub esp,%1 
%endmacro

This defines a C-like function prologue as a macro: so you would invoke the macro with a call such as

myfunc:   prologue 12

which would expand to the three lines of code

myfunc:   push ebp 
          mov ebp,esp 
          sub esp,12

Multi-line macros, like single-line macros, are case-sensitive, unless you define them using the alternative directive %imacro.

If you need to pass a comma as part of a parameter to a multi-line macro, you can do that by enclosing the entire parameter in braces. So you could code things like

%macro silly 2 
%2:       db %1 
%endmacro 
          silly 'a', letter_a    ; letter_a:  db 'a' 
          silly 'ab', string_ab  ; string_ab: db 'ab' 
          silly {13,10}, crlf    ; crlf:      db 13,10

4.3.1 Overloading Multi-Line Macros

%macro prologue 0 
          push ebp 
          mov ebp,esp 
%endmacro

to define an alternative form of the function prologue which

the macro a(3) will expand once, becoming 1+a(3), and will then expand no further. This behaviour can be useful: see section 8.1 for an example of its use.

You can overload single-line macros: if you write

%define foo(x) 1+x 
%define foo(x,y) 1+x*y

the preprocessor will be able to handle both types of macro call, by counting the parameters you pass; so foo(3) will become 1+3 whereas foo(ebx,2) will become 1+ebx*2. However, if you define

%define foo bar

then no other definition of foo will be accepted: a macro with no parameters prohibits the definition of the same name as a macro with parameters, and vice versa.

This doesn't prevent single-line macros being redefined: you can perfectly well define a macro with

%define foo bar

and then re-define it later in the same source file with

%define foo baz

You can pre-define single-line macros using the `-d' option on the NASM command line: see section 2.1.11.

4.1.2 Undefining macros: `%undef`

Single-line macros can be removed with the %undef command. For example, the following sequence:

%define foo bar 
%undef foo 
		mov eax, foo

will expand to the instruction mov eax, foo, since after %undef the macro foo is no longer defined.

Macros that would otherwise be pre-defined can be undefined on the command-line using the `-u' option on the NASM command line: see section 2.1.12.

4.1.3 Preprocessor Variables: `%assign`

Like %define, macros defined using %assign can be re-defined later, so you can do things like

%assign i i+1

to increment the numeric value of a macro.

%assign is useful for controlling the termination of %rep preprocessor loops: see section 4.5 for an example of this. Another use for %assign is given in section 7.4 and section 8.1.

4.2 String Handling in Macros: `%strlen` and `%substr`

It's often useful to be able to handle strings in macros. NASM supports two simple string handling macro operators from which more complex operations can be constructed.

4.2.1 String Length: `%strlen`

%strlen charcnt 'my string'

%define sometext 'my string' 
%strlen charcnt sometext

As in the first case, this would result in charcnt being assigned the value of 8.

4.2.2 Sub-strings: `%substr`

Individual letters in strings can be extracted using %substr. An example of its use is probably more useful than the description:

%substr mychar 'xyz' 1  ; equivalent to %define mychar 'x' 
%substr mychar 'xyz' 2  ; equivalent to %define mychar 'y' 
%substr mychar 'xyz' 3  ; equivalent to %define mychar 'z'

4.3 Multi-Line Macros: `%macro`

Multi-line macros are much more like the type of macro seen in MASM and TASM: a multi-line macro definition in NASM looks something like this.

%macro prologue 1 
          push ebp 
          mov ebp,esp 
          sub esp,%1 
%endmacro

This defines a C-like function prologue as a macro: so you would invoke the macro with a call such as

myfunc:   prologue 12

which would expand to the three lines of code

myfunc:   push ebp 
          mov ebp,esp 
          sub esp,12

Multi-line macros, like single-line macros, are case-sensitive, unless you define them using the alternative directive %imacro.

If you need to pass a comma as part of a parameter to a multi-line macro, you can do that by enclosing the entire parameter in braces. So you could code things like

%macro silly 2 
%2:       db %1 
%endmacro 
          silly 'a', letter_a    ; letter_a:  db 'a' 
          silly 'ab', string_ab  ; string_ab: db 'ab' 
          silly {13,10}, crlf    ; crlf:      db 13,10

4.3.1 Overloading Multi-Line Macros

%macro prologue 0 
          push ebp 
          mov ebp,esp 
%endmacro

to define an alternative form of the function prologue which

the macro a(3) will expand once, becoming 1+a(3), and will then expand no further. This behaviour can be useful: see section 8.1 for an example of its use.

You can overload single-line macros: if you write

%define foo(x) 1+x 
%define foo(x,y) 1+x*y

the preprocessor will be able to handle both types of macro call, by counting the parameters you pass; so foo(3) will become 1+3 whereas foo(ebx,2) will become 1+ebx*2. However, if you define

%define foo bar

then no other definition of foo will be accepted: a macro with no parameters prohibits the definition of the same name as a macro with parameters, and vice versa.

This doesn't prevent single-line macros being redefined: you can perfectly well define a macro with

%define foo bar

and then re-define it later in the same source file with

%define foo baz

You can pre-define single-line macros using the `-d' option on the NASM command line: see section 2.1.11.

4.1.2 Undefining macros: `%undef`

Single-line macros can be removed with the %undef command. For example, the following sequence:

%define foo bar 
%undef foo 
		mov eax, foo

will expand to the instruction mov eax, foo, since after %undef the macro foo is no longer defined.

Macros that would otherwise be pre-defined can be undefined on the command-line using the `-u' option on the NASM command line: see section 2.1.12.

4.1.3 Preprocessor Variables: `%assign`

Like %define, macros defined using %assign can be re-defined later, so you can do things like

%assign i i+1

to increment the numeric value of a macro.

%assign is useful for controlling the termination of %rep preprocessor loops: see section 4.5 for an example of this. Another use for %assign is given in section 7.4 and section 8.1.

4.2 String Handling in Macros: `%strlen` and `%substr`

It's often useful to be able to handle strings in macros. NASM supports two simple string handling macro operators from which more complex operations can be constructed.

4.2.1 String Length: `%strlen`

%strlen charcnt 'my string'

%define sometext 'my string' 
%strlen charcnt sometext

As in the first case, this would result in charcnt being assigned the value of 8.

4.2.2 Sub-strings: `%substr`

Individual letters in strings can be extracted using %substr. An example of its use is probably more useful than the description:

%substr mychar 'xyz' 1  ; equivalent to %define mychar 'x' 
%substr mychar 'xyz' 2  ; equivalent to %define mychar 'y' 
%substr mychar 'xyz' 3  ; equivalent to %define mychar 'z'

4.3 Multi-Line Macros: `%macro`

Multi-line macros are much more like the type of macro seen in MASM and TASM: a multi-line macro definition in NASM looks something like this.

%macro prologue 1 
          push ebp 
          mov ebp,esp 
          sub esp,%1 
%endmacro

This defines a C-like function prologue as a macro: so you would invoke the macro with a call such as

myfunc:   prologue 12

which would expand to the three lines of code

myfunc:   push ebp 
          mov ebp,esp 
          sub esp,12

Multi-line macros, like single-line macros, are case-sensitive, unless you define them using the alternative directive %imacro.

If you need to pass a comma as part of a parameter to a multi-line macro, you can do that by enclosing the entire parameter in braces. So you could code things like

%macro silly 2 
%2:       db %1 
%endmacro 
          silly 'a', letter_a    ; letter_a:  db 'a' 
          silly 'ab', string_ab  ; string_ab: db 'ab' 
          silly {13,10}, crlf    ; crlf:      db 13,10

4.3.1 Overloading Multi-Line Macros

%macro prologue 0 
          push ebp 
          mov ebp,esp 
%endmacro

to define an alternative form of the function prologue which

the macro a(3) will expand once, becoming 1+a(3), and will then expand no further. This behaviour can be useful: see section 8.1 for an example of its use.

You can overload single-line macros: if you write

%define foo(x) 1+x 
%define foo(x,y) 1+x*y

the preprocessor will be able to handle both types of macro call, by counting the parameters you pass; so foo(3) will become 1+3 whereas foo(ebx,2) will become 1+ebx*2. However, if you define

%define foo bar

then no other definition of foo will be accepted: a macro with no parameters prohibits the definition of the same name as a macro with parameters, and vice versa.

This doesn't prevent single-line macros being redefined: you can perfectly well define a macro with

%define foo bar

and then re-define it later in the same source file with

%define foo baz

You can pre-define single-line macros using the `-d' option on the NASM command line: see section 2.1.11.

4.1.2 Undefining macros: `%undef`

Single-line macros can be removed with the %undef command. For example, the following sequence:

%define foo bar 
%undef foo 
		mov eax, foo

will expand to the instruction mov eax, foo, since after %undef the macro foo is no longer defined.

Macros that would otherwise be pre-defined can be undefined on the command-line using the `-u' option on the NASM command line: see section 2.1.12.

4.1.3 Preprocessor Variables: `%assign`

Like %define, macros defined using %assign can be re-defined later, so you can do things like

%assign i i+1

to increment the numeric value of a macro.

%assign is useful for controlling the termination of %rep preprocessor loops: see section 4.5 for an example of this. Another use for %assign is given in section 7.4 and section 8.1.

4.2 String Handling in Macros: `%strlen` and `%substr`

It's often useful to be able to handle strings in macros. NASM supports two simple string handling macro operators from which more complex operations can be constructed.

4.2.1 String Length: `%strlen`

%strlen charcnt 'my string'

%define sometext 'my string' 
%strlen charcnt sometext

As in the first case, this would result in charcnt being assigned the value of 8.

4.2.2 Sub-strings: `%substr`

Individual letters in strings can be extracted using %substr. An example of its use is probably more useful than the description:

%substr mychar 'xyz' 1  ; equivalent to %define mychar 'x' 
%substr mychar 'xyz' 2  ; equivalent to %define mychar 'y' 
%substr mychar 'xyz' 3  ; equivalent to %define mychar 'z'

4.3 Multi-Line Macros: `%macro`

Multi-line macros are much more like the type of macro seen in MASM and TASM: a multi-line macro definition in NASM looks something like this.

%macro prologue 1 
          push ebp 
          mov ebp,esp 
          sub esp,%1 
%endmacro

This defines a C-like function prologue as a macro: so you would invoke the macro with a call such as

myfunc:   prologue 12

which would expand to the three lines of code

myfunc:   push ebp 
          mov ebp,esp 
          sub esp,12

Multi-line macros, like single-line macros, are case-sensitive, unless you define them using the alternative directive %imacro.

If you need to pass a comma as part of a parameter to a multi-line macro, you can do that by enclosing the entire parameter in braces. So you could code things like

%macro silly 2 
%2:       db %1 
%endmacro 
          silly 'a', letter_a    ; letter_a:  db 'a' 
          silly 'ab', string_ab  ; string_ab: db 'ab' 
          silly {13,10}, crlf    ; crlf:      db 13,10

4.3.1 Overloading Multi-Line Macros

%macro prologue 0 
          push ebp 
          mov ebp,esp 
%endmacro

to define an alternative form of the function prologue which

the macro a(3) will expand once, becoming 1+a(3), and will then expand no further. This behaviour can be useful: see section 8.1 for an example of its use.

You can overload single-line macros: if you write

%define foo(x) 1+x 
%define foo(x,y) 1+x*y

the preprocessor will be able to handle both types of macro call, by counting the parameters you pass; so foo(3) will become 1+3 whereas foo(ebx,2) will become 1+ebx*2. However, if you define

%define foo bar

then no other definition of foo will be accepted: a macro with no parameters prohibits the definition of the same name as a macro with parameters, and vice versa.

This doesn't prevent single-line macros being redefined: you can perfectly well define a macro with

%define foo bar

and then re-define it later in the same source file with

%define foo baz

You can pre-define single-line macros using the `-d' option on the NASM command line: see section 2.1.11.

4.1.2 Undefining macros: `%undef`

Single-line macros can be removed with the %undef command. For example, the following sequence:

%define foo bar 
%undef foo 
		mov eax, foo

will expand to the instruction mov eax, foo, since after %undef the macro foo is no longer defined.

Macros that would otherwise be pre-defined can be undefined on the command-line using the `-u' option on the NASM command line: see section 2.1.12.

4.1.3 Preprocessor Variables: `%assign`

Like %define, macros defined using %assign can be re-defined later, so you can do things like

%assign i i+1

to increment the numeric value of a macro.

%assign is useful for controlling the termination of %rep preprocessor loops: see section 4.5 for an example of this. Another use for %assign is given in section 7.4 and section 8.1.

4.2 String Handling in Macros: `%strlen` and `%substr`

It's often useful to be able to handle strings in macros. NASM supports two simple string handling macro operators from which more complex operations can be constructed.

4.2.1 String Length: `%strlen`

%strlen charcnt 'my string'

%define sometext 'my string' 
%strlen charcnt sometext

As in the first case, this would result in charcnt being assigned the value of 8.

4.2.2 Sub-strings: `%substr`

Individual letters in strings can be extracted using %substr. An example of its use is probably more useful than the description:

%substr mychar 'xyz' 1  ; equivalent to %define mychar 'x' 
%substr mychar 'xyz' 2  ; equivalent to %define mychar 'y' 
%substr mychar 'xyz' 3  ; equivalent to %define mychar 'z'

4.3 Multi-Line Macros: `%macro`

Multi-line macros are much more like the type of macro seen in MASM and TASM: a multi-line macro definition in NASM looks something like this.

%macro prologue 1 
          push ebp 
          mov ebp,esp 
          sub esp,%1 
%endmacro

This defines a C-like function prologue as a macro: so you would invoke the macro with a call such as

myfunc:   prologue 12

which would expand to the three lines of code

myfunc:   push ebp 
          mov ebp,esp 
          sub esp,12

Multi-line macros, like single-line macros, are case-sensitive, unless you define them using the alternative directive %imacro.

If you need to pass a comma as part of a parameter to a multi-line macro, you can do that by enclosing the entire parameter in braces. So you could code things like

%macro silly 2 
%2:       db %1 
%endmacro 
          silly 'a', letter_a    ; letter_a:  db 'a' 
          silly 'ab', string_ab  ; string_ab: db 'ab' 
          silly {13,10}, crlf    ; crlf:      db 13,10

4.3.1 Overloading Multi-Line Macros

%macro prologue 0 
          push ebp 
          mov ebp,esp 
%endmacro

to define an alternative form of the function prologue which

the macro a(3) will expand once, becoming 1+a(3), and will then expand no further. This behaviour can be useful: see section 8.1 for an example of its use.

You can overload single-line macros: if you write

%define foo(x) 1+x 
%define foo(x,y) 1+x*y

the preprocessor will be able to handle both types of macro call, by counting the parameters you pass; so foo(3) will become 1+3 whereas foo(ebx,2) will become 1+ebx*2. However, if you define

%define foo bar

then no other definition of foo will be accepted: a macro with no parameters prohibits the definition of the same name as a macro with parameters, and vice versa.

This doesn't prevent single-line macros being redefined: you can perfectly well define a macro with

%define foo bar

and then re-define it later in the same source file with

%define foo baz

You can pre-define single-line macros using the `-d' option on the NASM command line: see section 2.1.11.