mingw/info/gdb/Emacs.html

   1 <html lang="en">
   2 <head>
   3 <title>Debugging with GDB</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="Debugging with GDB">
   6 <meta name="generator" content="makeinfo 4.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="Emacs">Emacs</a>,
  13 Next:<a rel="next" accesskey="n" href="Annotations.html#Annotations">Annotations</a>,
  14 Previous:<a rel="previous" accesskey="p" href="TUI.html#TUI">TUI</a>,
  15 Up:<a rel="up" accesskey="u" href="index.html#Top">Top</a>
  16 <hr><br>
  17 </div>
  18
  19 <h2 class="chapter">Using GDB under <small>GNU</small> Emacs</h2>
  20
  21    <p>A special interface allows you to use <small>GNU</small> Emacs to view (and
  22 edit) the source files for the program you are debugging with
  23 GDB.
  24
  25    <p>To use this interface, use the command <kbd>M-x gdb</kbd> in Emacs.  Give the
  26 executable file you want to debug as an argument.  This command starts
  27 GDB as a subprocess of Emacs, with input and output through a newly
  28 created Emacs buffer.
  29
  30    <p>Using GDB under Emacs is just like using GDB normally except for two
  31 things:
  32
  33      <ul>
  34 <li>All "terminal" input and output goes through the Emacs buffer.
  35 </ul>
  36
  37    <p>This applies both to GDB commands and their output, and to the input
  38 and output done by the program you are debugging.
  39
  40    <p>This is useful because it means that you can copy the text of previous
  41 commands and input them again; you can even use parts of the output
  42 in this way.
  43
  44    <p>All the facilities of Emacs' Shell mode are available for interacting
  45 with your program.  In particular, you can send signals the usual
  46 way--for example, <kbd>C-c C-c</kbd> for an interrupt, <kbd>C-c C-z</kbd> for a
  47 stop.
  48
  49      <ul>
  50 <li>GDB displays source code through Emacs.
  51 </ul>
  52
  53    <p>Each time GDB displays a stack frame, Emacs automatically finds the
  54 source file for that frame and puts an arrow (<code>=&gt;</code>) at the
  55 left margin of the current line.  Emacs uses a separate buffer for
  56 source display, and splits the screen to show both your GDB session
  57 and the source.
  58
  59    <p>Explicit GDB <code>list</code> or search commands still produce output as
  60 usual, but you probably have no reason to use them from Emacs.
  61
  62    <blockquote>
  63 <em>Warning:</em> If the directory where your program resides is not your
  64 current directory, it can be easy to confuse Emacs about the location of
  65 the source files, in which case the auxiliary display buffer does not
  66 appear to show your source.  GDB can find programs by searching your
  67 environment's <code>PATH</code> variable, so the GDB input and output
  68 session proceeds normally; but Emacs does not get enough information
  69 back from GDB to locate the source files in this situation.  To
  70 avoid this problem, either start GDB mode from the directory where
  71 your program resides, or specify an absolute file name when prompted for the
  72 <kbd>M-x gdb</kbd> argument.
  73
  74         <p>A similar confusion can result if you use the GDB <code>file</code> command to
  75 switch to debugging a program in some other location, from an existing
  76 GDB buffer in Emacs.
  77 </blockquote>
  78
  79    <p>By default, <kbd>M-x gdb</kbd> calls the program called <code>gdb</code>.  If
  80 you need to call GDB by a different name (for example, if you keep
  81 several configurations around, with different names) you can set the
  82 Emacs variable <code>gdb-command-name</code>; for example,
  83
  84 <pre class="example">     (setq gdb-command-name "mygdb")
  85      </pre>
  86
  87 <p>(preceded by <kbd>M-:</kbd> or <kbd>ESC :</kbd>, or typed in the <code>*scratch*</code> buffer, or
  88 in your <code>.emacs</code> file) makes Emacs call the program named
  89 "<code>mygdb</code>" instead.
  90
  91    <p>In the GDB I/O buffer, you can use these special Emacs commands in
  92 addition to the standard Shell mode commands:
  93
  94      <dl>
  95 <dt><kbd>C-h m</kbd>
  96      <dd>Describe the features of Emacs' GDB Mode.
  97
  98      <br><dt><kbd>M-s</kbd>
  99      <dd>Execute to another source line, like the GDB <code>step</code> command; also
 100 update the display window to show the current file and location.
 101
 102      <br><dt><kbd>M-n</kbd>
 103      <dd>Execute to next source line in this function, skipping all function
 104 calls, like the GDB <code>next</code> command.  Then update the display window
 105 to show the current file and location.
 106
 107      <br><dt><kbd>M-i</kbd>
 108      <dd>Execute one instruction, like the GDB <code>stepi</code> command; update
 109 display window accordingly.
 110
 111      <br><dt><kbd>M-x gdb-nexti</kbd>
 112      <dd>Execute to next instruction, using the GDB <code>nexti</code> command; update
 113 display window accordingly.
 114
 115      <br><dt><kbd>C-c C-f</kbd>
 116      <dd>Execute until exit from the selected stack frame, like the GDB
 117 <code>finish</code> command.
 118
 119      <br><dt><kbd>M-c</kbd>
 120      <dd>Continue execution of your program, like the GDB <code>continue</code>
 121 command.
 122
 123      <p><em>Warning:</em> In Emacs v19, this command is <kbd>C-c C-p</kbd>.
 124
 125      <br><dt><kbd>M-u</kbd>
 126      <dd>Go up the number of frames indicated by the numeric argument
 127 (see <a href="../Emacs/Arguments.html#Arguments">Numeric Arguments</a>),
 128 like the GDB <code>up</code> command.
 129
 130      <p><em>Warning:</em> In Emacs v19, this command is <kbd>C-c C-u</kbd>.
 131
 132      <br><dt><kbd>M-d</kbd>
 133      <dd>Go down the number of frames indicated by the numeric argument, like the
 134 GDB <code>down</code> command.
 135
 136      <p><em>Warning:</em> In Emacs v19, this command is <kbd>C-c C-d</kbd>.
 137
 138      <br><dt><kbd>C-x &amp;</kbd>
 139      <dd>Read the number where the cursor is positioned, and insert it at the end
 140 of the GDB I/O buffer.  For example, if you wish to disassemble code
 141 around an address that was displayed earlier, type <kbd>disassemble</kbd>;
 142 then move the cursor to the address display, and pick up the
 143 argument for <code>disassemble</code> by typing <kbd>C-x &amp;</kbd>.
 144
 145      <p>You can customize this further by defining elements of the list
 146 <code>gdb-print-command</code>; once it is defined, you can format or
 147 otherwise process numbers picked up by <kbd>C-x &amp;</kbd> before they are
 148 inserted.  A numeric argument to <kbd>C-x &amp;</kbd> indicates that you
 149 wish special formatting, and also acts as an index to pick an element of the
 150 list.  If the list element is a string, the number to be inserted is
 151 formatted using the Emacs function <code>format</code>; otherwise the number
 152 is passed as an argument to the corresponding list element.
 153 </dl>
 154
 155    <p>In any source file, the Emacs command <kbd>C-x SPC</kbd> (<code>gdb-break</code>)
 156 tells GDB to set a breakpoint on the source line point is on.
 157
 158    <p>If you accidentally delete the source-display buffer, an easy way to get
 159 it back is to type the command <code>f</code> in the GDB buffer, to
 160 request a frame display; when you run under Emacs, this recreates
 161 the source buffer if necessary to show you the context of the current
 162 frame.
 163
 164    <p>The source files displayed in Emacs are in ordinary Emacs buffers
 165 which are visiting the source files in the usual way.  You can edit
 166 the files with these buffers if you wish; but keep in mind that GDB
 167 communicates with Emacs in terms of line numbers.  If you add or
 168 delete lines from the text, the line numbers that GDB knows cease
 169 to correspond properly with the code.
 170
 171    </body></html>
 172