<HTML>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Created on March, 27 2008 by texi2html 1.64 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
-->
<HEAD>
<TITLE>Debugging with GDB: Macros</TITLE>
<META NAME="description" CONTENT="Debugging with GDB: Macros">
<META NAME="keywords" CONTENT="Debugging with GDB: Macros">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.64">
</HEAD>
<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<A NAME="SEC83"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_9.html#SEC82"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC84"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC84"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 9. C Preprocessor Macros </H1>
<!--docid::SEC83::-->
<P>
Some languages, such as C and C<TT>++</TT>, provide a way to define and invoke
"preprocessor macros" which expand into strings of tokens.
GDB can evaluate expressions containing macro invocations, show
the result of macro expansion, and show a macro's definition, including
where it was defined.
</P><P>
You may need to compile your program specially to provide GDB
with information about preprocessor macros. Most compilers do not
include macros in their debugging information, even when you compile
with the <SAMP>`-g'</SAMP> flag. See section <A HREF="gdb_5.html#SEC19">4.1 Compiling for Debugging</A>.
</P><P>
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, GDB
uses the macros in scope at that frame's source code line. Otherwise,
GDB uses the macros in scope at the current listing location;
see <A HREF="gdb_8.html#SEC52">7.1 Printing Source Lines</A>.
</P><P>
At the moment, GDB does not support the <CODE>##</CODE>
token-splicing operator, the <CODE>#</CODE> stringification operator, or
variable-arity macros.
</P><P>
Whenever GDB evaluates an expression, it always expands any
macro invocations present in the expression. GDB also provides
the following commands for working with macros explicitly.
</P><P>
<DL COMPACT>
<A NAME="IDX507"></A>
<A NAME="IDX508"></A>
<A NAME="IDX509"></A>
<A NAME="IDX510"></A>
<DT><CODE>macro expand <VAR>expression</VAR></CODE>
<DD><DT><CODE>macro exp <VAR>expression</VAR></CODE>
<DD>Show the results of expanding all preprocessor macro invocations in
<VAR>expression</VAR>. Since GDB simply expands macros, but does
not parse the result, <VAR>expression</VAR> need not be a valid expression;
it can be any string of tokens.
<P>
<A NAME="IDX511"></A>
<DT><CODE>macro expand-once <VAR>expression</VAR></CODE>
<DD><DT><CODE>macro exp1 <VAR>expression</VAR></CODE>
<DD><A NAME="IDX512"></A>
<I>(This command is not yet implemented.)</I> Show the results of
expanding those preprocessor macro invocations that appear explicitly in
<VAR>expression</VAR>. 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 GDB simply expands macros, but does not
parse the result, <VAR>expression</VAR> need not be a valid expression; it
can be any string of tokens.
<P>
<A NAME="IDX513"></A>
<A NAME="IDX514"></A>
<A NAME="IDX515"></A>
<DT><CODE>info macro <VAR>macro</VAR></CODE>
<DD>Show the definition of the macro named <VAR>macro</VAR>, and describe the
source location where that definition was established.
<P>
<A NAME="IDX516"></A>
<A NAME="IDX517"></A>
<A NAME="IDX518"></A>
<A NAME="IDX519"></A>
<DT><CODE>macro define <VAR>macro</VAR> <VAR>replacement-list</VAR></CODE>
<DD><DT><CODE>macro define <VAR>macro</VAR>(<VAR>arglist</VAR>) <VAR>replacement-list</VAR></CODE>
<DD><I>(This command is not yet implemented.)</I> Introduce a definition for a
preprocessor macro named <VAR>macro</VAR>, invocations of which are replaced
by the tokens given in <VAR>replacement-list</VAR>. 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 <VAR>arglist</VAR>.
<P>
A definition introduced by this command is in scope in every expression
evaluated in GDB, until it is removed with the <CODE>macro
undef</CODE> command, described below. The definition overrides all
definitions for <VAR>macro</VAR> present in the program being debugged, as
well as any previous user-supplied definition.
</P><P>
<A NAME="IDX520"></A>
<DT><CODE>macro undef <VAR>macro</VAR></CODE>
<DD><I>(This command is not yet implemented.)</I> Remove any user-supplied
definition for the macro named <VAR>macro</VAR>. This command only affects
definitions provided with the <CODE>macro define</CODE> command, described
above; it cannot remove definitions present in the program being
debugged.
<P>
<A NAME="IDX521"></A>
<DT><CODE>macro list</CODE>
<DD><I>(This command is not yet implemented.)</I> List all the macros
defined using the <CODE>macro define</CODE> command.
</DL>
<P>
<A NAME="IDX522"></A>
Here is a transcript showing the above commands in action. First, we
show our source files:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>$ 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 <
$
</FONT></pre></td></tr></table></P><P>
Now, we compile the program using the GNU C compiler, GCC.
We pass the <SAMP>`-gdwarf-2'</SAMP> and <SAMP>`-g3'</SAMP> flags to ensure the
compiler includes information about preprocessor macros in the debugging
information.
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>$ gcc -gdwarf-2 -g3 sample.c -o sample
$
</FONT></pre></td></tr></table></P><P>
Now, we start GDB on our sample program:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>$ gdb -nw sample
GNU gdb 2002-05-06-cvs
Copyright 2002 Free Software Foundation, Inc.
GDB is free software, <small>...</small>
(gdb)
</FONT></pre></td></tr></table></P><P>
We can expand macros and examine their definitions, even when the
program is not running. GDB uses the current listing position
to decide which macro definitions are in scope:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) 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");
(gdb) info macro ADD
Defined at /home/jimb/gdb/macros/play/sample.c:5
#define ADD(x) (M + x)
(gdb) 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 <
(gdb) macro expand ADD(1)
expands to: (42 + 1)
(gdb) macro expand-once ADD(1)
expands to: once (M + 1)
(gdb)
</FONT></pre></td></tr></table></P><P>
In the example above, note that <CODE>macro expand-once</CODE> expands only
the macro invocation explicit in the original text -- the invocation of
<CODE>ADD</CODE> -- but does not expand the invocation of the macro <CODE>M</CODE>,
which was introduced by <CODE>ADD</CODE>.
</P><P>
Once the program is running, GDB uses the macro definitions in
force at the source line of the current stack frame:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) break main
Breakpoint 1 at 0x8048370: file sample.c, line 10.
(gdb) run
Starting program: /home/jimb/gdb/macros/play/sample
Breakpoint 1, main () at sample.c:10
10 printf ("Hello, world!\n");
(gdb)
</FONT></pre></td></tr></table></P><P>
At line 10, the definition of the macro <CODE>N</CODE> at line 9 is in force:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) info macro N
Defined at /home/jimb/gdb/macros/play/sample.c:9
#define N 28
(gdb) macro expand N Q M
expands to: 28 < 42
(gdb) print N Q M
$1 = 1
(gdb)
</FONT></pre></td></tr></table></P><P>
As we step over directives that remove <CODE>N</CODE>'s definition, and then
give it a new definition, GDB finds the definition (or lack
thereof) in force at each point:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) next
Hello, world!
12 printf ("We're so creative.\n");
(gdb) info macro N
The symbol `N' has no definition as a C/C++ preprocessor macro
at /home/jimb/gdb/macros/play/sample.c:12
(gdb) next
We're so creative.
14 printf ("Goodbye, world!\n");
(gdb) info macro N
Defined at /home/jimb/gdb/macros/play/sample.c:13
#define N 1729
(gdb) macro expand N Q M
expands to: 1729 < 42
(gdb) print N Q M
$2 = 0
(gdb)
</FONT></pre></td></tr></table></P><P>
<A NAME="Tracepoints"></A>
<HR SIZE="6">
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC84"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<BR>
<FONT SIZE="-1">
<address>
<p>Please send FSF & GNU inquiries & questions to <a
href="mailto:gnu@gnu.org">gnu@gnu.org</a>. There are also <a
href="http://www.gnu.org/home.html#ContactInfo">other ways to
contact</a> the FSF.</p>
<p>These pages are maintained by <a
href="http://www.gnu.org/software/gdb/">the GDB developers</a>.</p>
<p>Copyright Free Software Foundation, Inc., 59 Temple Place - Suite
330, Boston, MA 02111, USA.</p>
<p>Verbatim copying and distribution of this entire article is
permitted in any medium, provided this notice is preserved.</p>
</address>
This document was generated
by <I>GDB Administrator</I> on <I>March, 27 2008</I>
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
</BODY>
</HTML>