1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Macros</title> 18 19<meta name="description" content="Debugging with GDB: Macros"> 20<meta name="keywords" content="Debugging with GDB: Macros"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="index.html#Top" rel="up" title="Top"> 29<link href="Tracepoints.html#Tracepoints" rel="next" title="Tracepoints"> 30<link href="Tail-Call-Frames.html#Tail-Call-Frames" rel="previous" title="Tail Call Frames"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Macros"></a> 65<div class="header"> 66<p> 67Next: <a href="Tracepoints.html#Tracepoints" accesskey="n" rel="next">Tracepoints</a>, Previous: <a href="Optimized-Code.html#Optimized-Code" accesskey="p" rel="previous">Optimized Code</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="C-Preprocessor-Macros"></a> 71<h2 class="chapter">12 C Preprocessor Macros</h2> 72 73<p>Some languages, such as C and C<tt>++</tt>, provide a way to define and invoke 74“preprocessor macros” which expand into strings of tokens. 75<small>GDB</small> can evaluate expressions containing macro invocations, show 76the result of macro expansion, and show a macro’s definition, including 77where it was defined. 78</p> 79<p>You may need to compile your program specially to provide <small>GDB</small> 80with information about preprocessor macros. Most compilers do not 81include macros in their debugging information, even when you compile 82with the <samp>-g</samp> flag. See <a href="Compilation.html#Compilation">Compilation</a>. 83</p> 84<p>A program may define a macro at one point, remove that definition later, 85and then provide a different definition after that. Thus, at different 86points in the program, a macro may have different definitions, or have 87no definition at all. If there is a current stack frame, <small>GDB</small> 88uses the macros in scope at that frame’s source code line. Otherwise, 89<small>GDB</small> uses the macros in scope at the current listing location; 90see <a href="List.html#List">List</a>. 91</p> 92<p>Whenever <small>GDB</small> evaluates an expression, it always expands any 93macro invocations present in the expression. <small>GDB</small> also provides 94the following commands for working with macros explicitly. 95</p> 96<dl compact="compact"> 97<dd> 98<a name="index-macro-expand"></a> 99<a name="index-macro-expansion_002c-showing-the-results-of-preprocessor"></a> 100<a name="index-preprocessor-macro-expansion_002c-showing-the-results-of"></a> 101<a name="index-expanding-preprocessor-macros"></a> 102</dd> 103<dt><code>macro expand <var>expression</var></code></dt> 104<dt><code>macro exp <var>expression</var></code></dt> 105<dd><p>Show the results of expanding all preprocessor macro invocations in 106<var>expression</var>. Since <small>GDB</small> simply expands macros, but does 107not parse the result, <var>expression</var> need not be a valid expression; 108it can be any string of tokens. 109</p> 110<a name="index-macro-exp1"></a> 111</dd> 112<dt><code>macro expand-once <var>expression</var></code></dt> 113<dt><code>macro exp1 <var>expression</var></code></dt> 114<dd><a name="index-expand-macro-once"></a> 115<p><i>(This command is not yet implemented.)</i> Show the results of 116expanding those preprocessor macro invocations that appear explicitly in 117<var>expression</var>. Macro invocations appearing in that expansion are 118left unchanged. This command allows you to see the effect of a 119particular macro more clearly, without being confused by further 120expansions. Since <small>GDB</small> simply expands macros, but does not 121parse the result, <var>expression</var> need not be a valid expression; it 122can be any string of tokens. 123</p> 124<a name="index-info-macro"></a> 125<a name="index-macro-definition_002c-showing"></a> 126<a name="index-definition-of-a-macro_002c-showing"></a> 127<a name="index-macros_002c-from-debug-info"></a> 128</dd> 129<dt><code>info macro [-a|-all] [--] <var>macro</var></code></dt> 130<dd><p>Show the current definition or all definitions of the named <var>macro</var>, 131and describe the source location or compiler command-line where that 132definition was established. The optional double dash is to signify the end of 133argument processing and the beginning of <var>macro</var> for non C-like macros where 134the macro may begin with a hyphen. 135</p> 136<a name="index-info-macros"></a> 137</dd> 138<dt><code>info macros <var>location</var></code></dt> 139<dd><p>Show all macro definitions that are in effect at the location specified 140by <var>location</var>, and describe the source location or compiler 141command-line where those definitions were established. 142</p> 143<a name="index-macro-define"></a> 144<a name="index-user_002ddefined-macros"></a> 145<a name="index-defining-macros-interactively"></a> 146<a name="index-macros_002c-user_002ddefined"></a> 147</dd> 148<dt><code>macro define <var>macro</var> <var>replacement-list</var></code></dt> 149<dt><code>macro define <var>macro</var>(<var>arglist</var>) <var>replacement-list</var></code></dt> 150<dd><p>Introduce a definition for a preprocessor macro named <var>macro</var>, 151invocations of which are replaced by the tokens given in 152<var>replacement-list</var>. The first form of this command defines an 153“object-like” macro, which takes no arguments; the second form 154defines a “function-like” macro, which takes the arguments given in 155<var>arglist</var>. 156</p> 157<p>A definition introduced by this command is in scope in every 158expression evaluated in <small>GDB</small>, until it is removed with the 159<code>macro undef</code> command, described below. The definition overrides 160all definitions for <var>macro</var> present in the program being debugged, 161as well as any previous user-supplied definition. 162</p> 163<a name="index-macro-undef"></a> 164</dd> 165<dt><code>macro undef <var>macro</var></code></dt> 166<dd><p>Remove any user-supplied definition for the macro named <var>macro</var>. 167This command only affects definitions provided with the <code>macro 168define</code> command, described above; it cannot remove definitions present 169in the program being debugged. 170</p> 171<a name="index-macro-list"></a> 172</dd> 173<dt><code>macro list</code></dt> 174<dd><p>List all the macros defined using the <code>macro define</code> command. 175</p></dd> 176</dl> 177 178<a name="index-macros_002c-example-of-debugging-with"></a> 179<p>Here is a transcript showing the above commands in action. First, we 180show our source files: 181</p> 182<div class="smallexample"> 183<pre class="smallexample">$ cat sample.c 184#include <stdio.h> 185#include "sample.h" 186 187#define M 42 188#define ADD(x) (M + x) 189 190main () 191{ 192#define N 28 193 printf ("Hello, world!\n"); 194#undef N 195 printf ("We're so creative.\n"); 196#define N 1729 197 printf ("Goodbye, world!\n"); 198} 199$ cat sample.h 200#define Q < 201$ 202</pre></div> 203 204<p>Now, we compile the program using the <small>GNU</small> C compiler, 205<small>GCC</small>. We pass the <samp>-gdwarf-2</samp><a name="DOCF14" href="#FOOT14"><sup>14</sup></a> <em>and</em> <samp>-g3</samp> flags to ensure the compiler 206includes information about preprocessor macros in the debugging 207information. 208</p> 209<div class="smallexample"> 210<pre class="smallexample">$ gcc -gdwarf-2 -g3 sample.c -o sample 211$ 212</pre></div> 213 214<p>Now, we start <small>GDB</small> on our sample program: 215</p> 216<div class="smallexample"> 217<pre class="smallexample">$ gdb -nw sample 218GNU gdb 2002-05-06-cvs 219Copyright 2002 Free Software Foundation, Inc. 220GDB is free software, … 221(gdb) 222</pre></div> 223 224<p>We can expand macros and examine their definitions, even when the 225program is not running. <small>GDB</small> uses the current listing position 226to decide which macro definitions are in scope: 227</p> 228<div class="smallexample"> 229<pre class="smallexample">(gdb) list main 2303 2314 #define M 42 2325 #define ADD(x) (M + x) 2336 2347 main () 2358 { 2369 #define N 28 23710 printf ("Hello, world!\n"); 23811 #undef N 23912 printf ("We're so creative.\n"); 240(gdb) info macro ADD 241Defined at /home/jimb/gdb/macros/play/sample.c:5 242#define ADD(x) (M + x) 243(gdb) info macro Q 244Defined at /home/jimb/gdb/macros/play/sample.h:1 245 included at /home/jimb/gdb/macros/play/sample.c:2 246#define Q < 247(gdb) macro expand ADD(1) 248expands to: (42 + 1) 249(gdb) macro expand-once ADD(1) 250expands to: once (M + 1) 251(gdb) 252</pre></div> 253 254<p>In the example above, note that <code>macro expand-once</code> expands only 255the macro invocation explicit in the original text — the invocation of 256<code>ADD</code> — but does not expand the invocation of the macro <code>M</code>, 257which was introduced by <code>ADD</code>. 258</p> 259<p>Once the program is running, <small>GDB</small> uses the macro definitions in 260force at the source line of the current stack frame: 261</p> 262<div class="smallexample"> 263<pre class="smallexample">(gdb) break main 264Breakpoint 1 at 0x8048370: file sample.c, line 10. 265(gdb) run 266Starting program: /home/jimb/gdb/macros/play/sample 267 268Breakpoint 1, main () at sample.c:10 26910 printf ("Hello, world!\n"); 270(gdb) 271</pre></div> 272 273<p>At line 10, the definition of the macro <code>N</code> at line 9 is in force: 274</p> 275<div class="smallexample"> 276<pre class="smallexample">(gdb) info macro N 277Defined at /home/jimb/gdb/macros/play/sample.c:9 278#define N 28 279(gdb) macro expand N Q M 280expands to: 28 < 42 281(gdb) print N Q M 282$1 = 1 283(gdb) 284</pre></div> 285 286<p>As we step over directives that remove <code>N</code>’s definition, and then 287give it a new definition, <small>GDB</small> finds the definition (or lack 288thereof) in force at each point: 289</p> 290<div class="smallexample"> 291<pre class="smallexample">(gdb) next 292Hello, world! 29312 printf ("We're so creative.\n"); 294(gdb) info macro N 295The symbol `N' has no definition as a C/C++ preprocessor macro 296at /home/jimb/gdb/macros/play/sample.c:12 297(gdb) next 298We're so creative. 29914 printf ("Goodbye, world!\n"); 300(gdb) info macro N 301Defined at /home/jimb/gdb/macros/play/sample.c:13 302#define N 1729 303(gdb) macro expand N Q M 304expands to: 1729 < 42 305(gdb) print N Q M 306$2 = 0 307(gdb) 308</pre></div> 309 310<p>In addition to source files, macros can be defined on the compilation command 311line using the <samp>-D<var>name</var>=<var>value</var></samp> syntax. For macros defined in 312such a way, <small>GDB</small> displays the location of their definition as line zero 313of the source file submitted to the compiler. 314</p> 315<div class="smallexample"> 316<pre class="smallexample">(gdb) info macro __STDC__ 317Defined at /home/jimb/gdb/macros/play/sample.c:0 318-D__STDC__=1 319(gdb) 320</pre></div> 321 322 323<div class="footnote"> 324<hr> 325<h4 class="footnotes-heading">Footnotes</h4> 326 327<h3><a name="FOOT14" href="#DOCF14">(14)</a></h3> 328<p>This is the 329minimum. Recent versions of <small>GCC</small> support <samp>-gdwarf-3</samp> 330and <samp>-gdwarf-4</samp>; we recommend always choosing the most recent 331version of DWARF.</p> 332</div> 333<hr> 334<div class="header"> 335<p> 336Next: <a href="Tracepoints.html#Tracepoints" accesskey="n" rel="next">Tracepoints</a>, Previous: <a href="Optimized-Code.html#Optimized-Code" accesskey="p" rel="previous">Optimized Code</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 337</div> 338 339 340 341</body> 342</html> 343