9. C Preprocessor Macros

Some languages, such as C and C++, provide a way to define and invoke “preprocessor macros” which expand into strings of tokens. No value for GDBN can evaluate expressions containing macro invocations, show the result of macro expansion, and show a macro's definition, including where it was defined.

You may need to compile your program specially to provide No value for GDBN with information about preprocessor macros. Most compilers do not include macros in their debugging information, even when you compile with the ‘-g’ flag. See section Compiling for Debugging.

A program may define a macro at one point, remove that definition later, and then provide a different definition after that. Thus, at different points in the program, a macro may have different definitions, or have no definition at all. If there is a current stack frame, No value for GDBN uses the macros in scope at that frame's source code line. Otherwise, No value for GDBN uses the macros in scope at the current listing location; see Printing Source Lines.

At the moment, No value for GDBN does not support the ## token-splicing operator, the # stringification operator, or variable-arity macros.

Whenever No value for GDBN evaluates an expression, it always expands any macro invocations present in the expression. No value for GDBN also provides the following commands for working with macros explicitly.

macro expand expression

macro exp expression

Show the results of expanding all preprocessor macro invocations in expression. Since No value for GDBN simply expands macros, but does not parse the result, expression need not be a valid expression; it can be any string of tokens.

macro expand-once expression

macro exp1 expression

(This command is not yet implemented.) Show the results of expanding those preprocessor macro invocations that appear explicitly in expression. Macro invocations appearing in that expansion are left unchanged. This command allows you to see the effect of a particular macro more clearly, without being confused by further expansions. Since No value for GDBN simply expands macros, but does not parse the result, expression need not be a valid expression; it can be any string of tokens.

info macro macro

Show the definition of the macro named macro, and describe the source location where that definition was established.

macro define macro replacement-list

macro define macro(arglist) replacement-list

(This command is not yet implemented.) Introduce a definition for a preprocessor macro named macro, invocations of which are replaced by the tokens given in replacement-list. The first form of this command defines an “object-like” macro, which takes no arguments; the second form defines a “function-like” macro, which takes the arguments given in arglist.

A definition introduced by this command is in scope in every expression evaluated in No value for GDBN, until it is removed with the macro undef command, described below. The definition overrides all definitions for macro present in the program being debugged, as well as any previous user-supplied definition.

macro undef macro

(This command is not yet implemented.) Remove any user-supplied definition for the macro named macro. This command only affects definitions provided with the macro define command, described above; it cannot remove definitions present in the program being debugged.

macro list

(This command is not yet implemented.) List all the macros defined using the macro define command.

Here is a transcript showing the above commands in action. First, we show our source files:

$ cat sample.c
#include <stdio.h>
#include "sample.h"

#define M 42
#define ADD(x) (M + x)

main ()
{
#define N 28
  printf ("Hello, world!\n");
#undef N
  printf ("We're so creative.\n");
#define N 1729
  printf ("Goodbye, world!\n");
}
$ cat sample.h
#define Q <
$

Now, we compile the program using the GNU C compiler, No value for NGCC. We pass the ‘-gdwarf-2’ and ‘-g3’ flags to ensure the compiler includes information about preprocessor macros in the debugging information.

$ gcc -gdwarf-2 -g3 sample.c -o sample
$

Now, we start No value for GDBN on our sample program:

$ gdb -nw sample
GNU gdb 2002-05-06-cvs
Copyright 2002 Free Software Foundation, Inc.
GDB is free software, …
(No value for GDBP)

We can expand macros and examine their definitions, even when the program is not running. No value for GDBN uses the current listing position to decide which macro definitions are in scope:

(No value for GDBP) list main
3
4       #define M 42
5       #define ADD(x) (M + x)
6
7       main ()
8       {
9       #define N 28
10        printf ("Hello, world!\n");
11      #undef N
12        printf ("We're so creative.\n");
(No value for GDBP) info macro ADD
Defined at /home/jimb/gdb/macros/play/sample.c:5
#define ADD(x) (M + x)
(No value for GDBP) info macro Q
Defined at /home/jimb/gdb/macros/play/sample.h:1
  included at /home/jimb/gdb/macros/play/sample.c:2
#define Q <
(No value for GDBP) macro expand ADD(1)
expands to: (42 + 1)
(No value for GDBP) macro expand-once ADD(1)
expands to: once (M + 1)
(No value for GDBP)

In the example above, note that macro expand-once expands only the macro invocation explicit in the original text — the invocation of ADD — but does not expand the invocation of the macro M, which was introduced by ADD.

Once the program is running, No value for GDBN uses the macro definitions in force at the source line of the current stack frame:

(No value for GDBP) break main
Breakpoint 1 at 0x8048370: file sample.c, line 10.
(No value for GDBP) run
Starting program: /home/jimb/gdb/macros/play/sample

Breakpoint 1, main () at sample.c:10
10        printf ("Hello, world!\n");
(No value for GDBP)

At line 10, the definition of the macro N at line 9 is in force:

(No value for GDBP) info macro N
Defined at /home/jimb/gdb/macros/play/sample.c:9
#define N 28
(No value for GDBP) macro expand N Q M
expands to: 28 < 42
(No value for GDBP) print N Q M
$1 = 1
(No value for GDBP)

As we step over directives that remove N's definition, and then give it a new definition, No value for GDBN finds the definition (or lack thereof) in force at each point:

(No value for GDBP) next
Hello, world!
12        printf ("We're so creative.\n");
(No value for GDBP) info macro N
The symbol `N' has no definition as a C/C++ preprocessor macro
at /home/jimb/gdb/macros/play/sample.c:12
(No value for GDBP) next
We're so creative.
14        printf ("Goodbye, world!\n");
(No value for GDBP) info macro N
Defined at /home/jimb/gdb/macros/play/sample.c:13
#define N 1729
(No value for GDBP) macro expand N Q M
expands to: 1729 < 42
(No value for GDBP) print N Q M
$2 = 0
(No value for GDBP)