A special interface allows you to use GNU Emacs to view (and
edit) the source files for the program you are debugging with
GDB.

To use this interface, use the command M-x gdb in Emacs. Give the
executable file you want to debug as an argument. This command starts
GDB as a subprocess of Emacs, with input and output through a newly
created Emacs buffer.

Using GDB under Emacs is just like using GDB normally except for two
things:

All "terminal" input and output goes through the Emacs buffer.

This applies both to GDB commands and their output, and to the input
and output done by the program you are debugging.

This is useful because it means that you can copy the text of previous
commands and input them again; you can even use parts of the output
in this way.

All the facilities of Emacs' Shell mode are available for interacting
with your program. In particular, you can send signals the usual
way--for example, C-c C-c for an interrupt, C-c C-z for a
stop.

GDB displays source code through Emacs.

Each time GDB displays a stack frame, Emacs automatically finds the
source file for that frame and puts an arrow (`=>') at the
left margin of the current line. Emacs uses a separate buffer for
source display, and splits the screen to show both your GDB session
and the source.

Explicit GDB list or search commands still produce output as
usual, but you probably have no reason to use them from Emacs.

Warning: If the directory where your program resides is not your
current directory, it can be easy to confuse Emacs about the location of
the source files, in which case the auxiliary display buffer does not
appear to show your source. GDB can find programs by searching your
environment's PATH variable, so the GDB input and output
session proceeds normally; but Emacs does not get enough information
back from GDB to locate the source files in this situation. To
avoid this problem, either start GDB mode from the directory where
your program resides, or specify an absolute file name when prompted for the
M-x gdb argument.

A similar confusion can result if you use the GDB file command to
switch to debugging a program in some other location, from an existing
GDB buffer in Emacs.

By default, M-x gdb calls the program called `gdb'. If
you need to call GDB by a different name (for example, if you keep
several configurations around, with different names) you can set the
Emacs variable gdb-command-name; for example,

(setq gdb-command-name "mygdb")

(preceded by ESC ESC, or typed in the *scratch* buffer, or
in your `.emacs' file) makes Emacs call the program named
"mygdb" instead.

In the GDB I/O buffer, you can use these special Emacs commands in
addition to the standard Shell mode commands:

C-h m

Describe the features of Emacs' GDB Mode.

M-s

Execute to another source line, like the GDB step command; also
update the display window to show the current file and location.

M-n

Execute to next source line in this function, skipping all function
calls, like the GDB next command. Then update the display window
to show the current file and location.

Execute to next instruction, using the GDB nexti command; update
display window accordingly.

C-c C-f

Execute until exit from the selected stack frame, like the GDB
finish command.

M-c

Continue execution of your program, like the GDB continue
command.

Warning: In Emacs v19, this command is C-c C-p.

M-u

Go up the number of frames indicated by the numeric argument
(see section `Numeric Arguments' in The GNU Emacs Manual),
like the GDB up command.

Warning: In Emacs v19, this command is C-c C-u.

M-d

Go down the number of frames indicated by the numeric argument, like the
GDB down command.

Warning: In Emacs v19, this command is C-c C-d.

C-x &

Read the number where the cursor is positioned, and insert it at the end
of the GDB I/O buffer. For example, if you wish to disassemble code
around an address that was displayed earlier, type disassemble;
then move the cursor to the address display, and pick up the
argument for disassemble by typing C-x &.

You can customize this further by defining elements of the list
gdb-print-command; once it is defined, you can format or
otherwise process numbers picked up by C-x & before they are
inserted. A numeric argument to C-x & indicates that you
wish special formatting, and also acts as an index to pick an element of the
list. If the list element is a string, the number to be inserted is
formatted using the Emacs function format; otherwise the number
is passed as an argument to the corresponding list element.

In any source file, the Emacs command C-x SPC (gdb-break)
tells GDB to set a breakpoint on the source line point is on.

If you accidentally delete the source-display buffer, an easy way to get
it back is to type the command f in the GDB buffer, to
request a frame display; when you run under Emacs, this recreates
the source buffer if necessary to show you the context of the current
frame.

The source files displayed in Emacs are in ordinary Emacs buffers
which are visiting the source files in the usual way. You can edit
the files with these buffers if you wish; but keep in mind that GDB
communicates with Emacs in terms of line numbers. If you add or
delete lines from the text, the line numbers that GDB knows cease
to correspond properly with the code.