| <html lang="en"> |
| <head> |
| <title>Macros - Debugging with GDB</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="Debugging with GDB"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="prev" href="Optimized-Code.html#Optimized-Code" title="Optimized Code"> |
| <link rel="next" href="Tracepoints.html#Tracepoints" title="Tracepoints"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| Copyright (C) 1988-2019 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software'' and ``Free Software Needs |
| Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' |
| and with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: ``You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom.'' |
| --> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Macros"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="Tracepoints.html#Tracepoints">Tracepoints</a>, |
| Previous: <a rel="previous" accesskey="p" href="Optimized-Code.html#Optimized-Code">Optimized Code</a>, |
| Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a> |
| <hr> |
| </div> |
| |
| <h2 class="chapter">12 C Preprocessor Macros</h2> |
| |
| <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. |
| <span class="sc">gdb</span> can evaluate expressions containing macro invocations, show |
| the result of macro expansion, and show a macro's definition, including |
| where it was defined. |
| |
| <p>You may need to compile your program specially to provide <span class="sc">gdb</span> |
| with information about preprocessor macros. Most compilers do not |
| include macros in their debugging information, even when you compile |
| with the <samp><span class="option">-g</span></samp> flag. See <a href="Compilation.html#Compilation">Compilation</a>. |
| |
| <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, <span class="sc">gdb</span> |
| uses the macros in scope at that frame's source code line. Otherwise, |
| <span class="sc">gdb</span> uses the macros in scope at the current listing location; |
| see <a href="List.html#List">List</a>. |
| |
| <p>Whenever <span class="sc">gdb</span> evaluates an expression, it always expands any |
| macro invocations present in the expression. <span class="sc">gdb</span> also provides |
| the following commands for working with macros explicitly. |
| |
| |
| <a name="index-macro-expand-840"></a> |
| <a name="index-macro-expansion_002c-showing-the-results-of-preprocessor-841"></a> |
| <a name="index-preprocessor-macro-expansion_002c-showing-the-results-of-842"></a> |
| <a name="index-expanding-preprocessor-macros-843"></a> |
| <dl><dt><code>macro expand </code><var>expression</var><dt><code>macro exp </code><var>expression</var><dd>Show the results of expanding all preprocessor macro invocations in |
| <var>expression</var>. Since <span class="sc">gdb</span> 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="index-macro-exp1-844"></a><br><dt><code>macro expand-once </code><var>expression</var><dt><code>macro exp1 </code><var>expression</var><dd><a name="index-expand-macro-once-845"></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 <span class="sc">gdb</span> 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="index-info-macro-846"></a><a name="index-macro-definition_002c-showing-847"></a><a name="index-definition-of-a-macro_002c-showing-848"></a><a name="index-macros_002c-from-debug-info-849"></a><br><dt><code>info macro [-a|-all] [--] </code><var>macro</var><dd>Show the current definition or all definitions of the named <var>macro</var>, |
| and describe the source location or compiler command-line where that |
| definition was established. The optional double dash is to signify the end of |
| argument processing and the beginning of <var>macro</var> for non C-like macros where |
| the macro may begin with a hyphen. |
| |
| <p><a name="index-info-macros-850"></a><br><dt><code>info macros </code><var>location</var><dd>Show all macro definitions that are in effect at the location specified |
| by <var>location</var>, and describe the source location or compiler |
| command-line where those definitions were established. |
| |
| <p><a name="index-macro-define-851"></a><a name="index-user_002ddefined-macros-852"></a><a name="index-defining-macros-interactively-853"></a><a name="index-macros_002c-user_002ddefined-854"></a><br><dt><code>macro define </code><var>macro</var> <var>replacement-list</var><dt><code>macro define </code><var>macro</var><code>(</code><var>arglist</var><code>) </code><var>replacement-list</var><dd>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 <span class="sc">gdb</span>, 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><a name="index-macro-undef-855"></a><br><dt><code>macro undef </code><var>macro</var><dd>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="index-macro-list-856"></a><br><dt><code>macro list</code><dd>List all the macros defined using the <code>macro define</code> command. |
| </dl> |
| |
| <p><a name="index-macros_002c-example-of-debugging-with-857"></a>Here is a transcript showing the above commands in action. First, we |
| show our source files: |
| |
| <pre class="smallexample"> $ 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 < |
| $ |
| </pre> |
| <p>Now, we compile the program using the <span class="sc">gnu</span> C compiler, |
| <span class="sc">gcc</span>. We pass the <samp><span class="option">-gdwarf-2</span></samp><a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a> <em>and</em> <samp><span class="option">-g3</span></samp> flags to ensure the compiler |
| includes information about preprocessor macros in the debugging |
| information. |
| |
| <pre class="smallexample"> $ gcc -gdwarf-2 -g3 sample.c -o sample |
| $ |
| </pre> |
| <p>Now, we start <span class="sc">gdb</span> on our sample program: |
| |
| <pre class="smallexample"> $ gdb -nw sample |
| GNU gdb 2002-05-06-cvs |
| Copyright 2002 Free Software Foundation, Inc. |
| GDB is free software, ... |
| (gdb) |
| </pre> |
| <p>We can expand macros and examine their definitions, even when the |
| program is not running. <span class="sc">gdb</span> uses the current listing position |
| to decide which macro definitions are in scope: |
| |
| <pre class="smallexample"> (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) |
| </pre> |
| <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>Once the program is running, <span class="sc">gdb</span> uses the macro definitions in |
| force at the source line of the current stack frame: |
| |
| <pre class="smallexample"> (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) |
| </pre> |
| <p>At line 10, the definition of the macro <code>N</code> at line 9 is in force: |
| |
| <pre class="smallexample"> (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) |
| </pre> |
| <p>As we step over directives that remove <code>N</code>'s definition, and then |
| give it a new definition, <span class="sc">gdb</span> finds the definition (or lack |
| thereof) in force at each point: |
| |
| <pre class="smallexample"> (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) |
| </pre> |
| <p>In addition to source files, macros can be defined on the compilation command |
| line using the <samp><span class="option">-D</span><var>name</var><span class="option">=</span><var>value</var></samp> syntax. For macros defined in |
| such a way, <span class="sc">gdb</span> displays the location of their definition as line zero |
| of the source file submitted to the compiler. |
| |
| <pre class="smallexample"> (gdb) info macro __STDC__ |
| Defined at /home/jimb/gdb/macros/play/sample.c:0 |
| -D__STDC__=1 |
| (gdb) |
| </pre> |
| <div class="footnote"> |
| <hr> |
| <h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> This is the |
| minimum. Recent versions of <span class="sc">gcc</span> support <samp><span class="option">-gdwarf-3</span></samp> |
| and <samp><span class="option">-gdwarf-4</span></samp>; we recommend always choosing the most recent |
| version of DWARF.</p> |
| |
| <hr></div> |
| |
| </body></html> |
| |
