27.6.5 GDB Graphical Interface

The command M-x gdb starts GDB in an IDE-like interface, with specialized buffers for controlling breakpoints, stack frames, and other aspects of the debugger state. It also provides additional ways to control the debugging session with the mouse, such as clicking in the fringe of a source buffer to set a breakpoint there.

To run GDB using just the GUD interaction buffer interface, without these additional features, use M-x gud-gdb (see Starting GUD). You must use this if you want to debug multiple programs within one Emacs session, as that is currently unsupported by M-x gdb.

Internally, M-x gdb informs GDB that its screen size is unlimited; for correct operation, you must not change GDB’s screen height and width values during the debugging session.

• GDB User Interface Layout		Control the number of displayed buffers.
• Source Buffers		Use the mouse in the fringe/margin to control your program.
• Breakpoints Buffer		A breakpoint control panel.
• Threads Buffer		Displays your threads.
• Stack Buffer		Select a frame from the call stack.
• Other GDB Buffers		Other buffers for controlling the GDB state.
• Watch Expressions		Monitor variable values in the speedbar.
• Multithreaded Debugging		Debugging programs with several threads.

27.6.5.1 GDB User Interface Layout

If the variable gdb-many-windows is nil (the default), M-x gdb normally displays only the GUD interaction buffer. However, if the variable gdb-show-main is also non-nil, it starts with two windows: one displaying the GUD interaction buffer, and the other showing the source for the main function of the program you are debugging.

If gdb-many-windows is non-nil, then M-x gdb displays the following frame layout:

+--------------------------------+--------------------------------+
|   GUD interaction buffer       |   Locals/Registers buffer      |
|--------------------------------+--------------------------------+
|   Primary Source buffer        |   I/O buffer for debugged pgm  |
|--------------------------------+--------------------------------+
|   Stack buffer                 |   Breakpoints/Threads buffer   |
+--------------------------------+--------------------------------+

If you ever change the window layout, you can restore the many-windows layout by typing M-x gdb-restore-windows. To toggle between the many windows layout and a simple layout with just the GUD interaction buffer and a source file, type M-x gdb-many-windows.

If you have an elaborate window setup, and don’t want gdb-many-windows to disrupt that, it is better to invoke M-x gdb in a separate frame to begin with, then the arrangement of windows on your original frame will not be affected. A separate frame for GDB sessions can come in especially handy if you work on a text-mode terminal, where the screen estate for windows could be at a premium.

You may also specify additional GDB-related buffers to display, either in the same frame or a different one. Select the buffers you want by typing M-x gdb-display-buffertype-buffer or M-x gdb-frame-buffertype-buffer, where buffertype is the relevant buffer type, such as ‘breakpoints’. You can do the same with the menu bar, with the ‘GDB-Windows’ and ‘GDB-Frames’ sub-menus of the ‘GUD’ menu.

When you finish debugging, kill the GUD interaction buffer with C-x k, which will also kill all the buffers associated with the session. However you need not do this if, after editing and re-compiling your source code within Emacs, you wish to continue debugging. When you restart execution, GDB automatically finds the new executable. Keeping the GUD interaction buffer has the advantage of keeping the shell history as well as GDB’s breakpoints. You do need to check that the breakpoints in recently edited source files are still in the right places.

27.6.5.2 Source Buffers

mouse-1 (in fringe)

Set or clear a breakpoint on that line (gdb-mouse-set-clear-breakpoint).

C-mouse-1 (in fringe)

Enable or disable a breakpoint on that line (gdb-mouse-toggle-breakpoint-margin).

mouse-3 (in fringe)

Continue execution to that line (gdb-mouse-until).

C-mouse-3 (in fringe)

Jump to that line (gdb-mouse-jump).

On a graphical display, you can click mouse-1 in the fringe of a source buffer, to set a breakpoint on that line (see Fringes). A red dot appears in the fringe, where you clicked. If a breakpoint already exists there, the click removes it. A C-mouse-1 click enables or disables an existing breakpoint; a breakpoint that is disabled, but not unset, is indicated by a gray dot.

On a text terminal, or when fringes are disabled, enabled breakpoints are indicated with a ‘B’ character in the left margin of the window. Disabled breakpoints are indicated with ‘b’. (The margin is only displayed if a breakpoint is present.)

A solid arrow in the left fringe of a source buffer indicates the line of the innermost frame where the debugged program has stopped. A hollow arrow indicates the current execution line of a higher-level frame. If you drag the arrow in the fringe with mouse-1, that causes execution to advance to the line where you release the button. Alternatively, you can click mouse-3 in the fringe to advance to that line. You can click C-mouse-3 in the fringe to jump to that line without executing the intermediate lines. This command allows you to go backwards, which can be useful for running through code that has already executed, in order to examine its execution in more detail.

If the file names of the source files are shown with octal escapes, set the variable gdb-mi-decode-strings to the appropriate coding-system, most probably utf-8. (This is nil by default because GDB may emit octal escapes in situations where decoding is undesirable, and also because the program being debugged might use an encoding different from the one used to encode non-ASCII file names on your system.)

27.6.5.3 Breakpoints Buffer

The GDB Breakpoints buffer shows the breakpoints, watchpoints and catchpoints in the debugger session. See Breakpoints in The GNU debugger. It provides the following commands, which mostly apply to the current breakpoint (the breakpoint which point is on):

SPC

Enable/disable current breakpoint (gdb-toggle-breakpoint). On a graphical display, this changes the color of the dot in the fringe of the source buffer at that line. The dot is red when the breakpoint is enabled, and gray when it is disabled.

D

Delete the current breakpoint (gdb-delete-breakpoint).

RET

Visit the source line for the current breakpoint (gdb-goto-breakpoint).

mouse-2

Visit the source line for the breakpoint you click on (gdb-goto-breakpoint).

When gdb-many-windows is non-nil, the GDB Breakpoints buffer shares its window with the GDB Threads buffer. To switch from one to the other click with mouse-1 on the relevant button in the header line. If gdb-show-threads-by-default is non-nil, the GDB Threads buffer is the one shown by default.

27.6.5.4 Threads Buffer

The GDB Threads buffer displays a summary of the threads in the debugged program. See Debugging programs with multiple threads in The GNU debugger. To select a thread, move point there and press RET (gdb-select-thread), or click on it with mouse-2. This also displays the associated source buffer, and updates the contents of the other GDB buffers.

You can customize variables in the gdb-buffers group to select fields included in GDB Threads buffer.

gdb-thread-buffer-verbose-names

Show long thread names like ‘Thread 0x4e2ab70 (LWP 1983)’.

gdb-thread-buffer-arguments

Show arguments of thread top frames.

gdb-thread-buffer-locations

Show file information or library names.

gdb-thread-buffer-addresses

Show addresses for thread frames in threads buffer.

To view information for several threads simultaneously, use the following commands from the GDB Threads buffer.

d

Display disassembly buffer for the thread at current line (gdb-display-disassembly-for-thread).

f

Display the GDB Stack buffer for the thread at current line (gdb-display-stack-for-thread).

l

Display the GDB Locals buffer for the thread at current line (gdb-display-locals-for-thread).

r

Display the GDB Registers buffer for the thread at current line (gdb-display-registers-for-thread).

Their upper-case counterparts, D, F ,L and R, display the corresponding buffer in a new frame.

When you create a buffer showing information about some specific thread, it becomes bound to that thread and keeps showing actual information while you debug your program. The mode indicator for each GDB buffer shows the number of the thread whose information that buffer displays. The thread number is also included in the name of each bound buffer.

Further commands are available in the GDB Threads buffer which depend on the mode of GDB that is used for controlling execution of your program. See Multithreaded Debugging.

27.6.5.5 Stack Buffer

The GDB Stack buffer displays a call stack, with one line for each of the nested subroutine calls (stack frames) in the debugger session. See Backtraces in The GNU debugger.

On graphical displays, the selected stack frame is indicated by an arrow in the fringe. On text terminals, or when fringes are disabled, the selected stack frame is displayed in reverse contrast. To select a stack frame, move point in its line and type RET (gdb-frames-select), or click mouse-2 on it. Doing so also updates the Locals buffer (see Other GDB Buffers).

If you want the frame address to be shown each stack frame, customize the variable gdb-stack-buffer-addresses to a non-nil value.

27.6.5.6 Other GDB Buffers

Locals Buffer

This buffer displays the values of local variables of the current frame for simple data types (see Information on a frame in The GNU debugger). Press RET or click mouse-2 on the value if you want to edit it.

Arrays and structures display their type only. With GDB 6.4 or later, you can examine the value of the local variable at point by typing RET, or with a mouse-2 click. With earlier versions of GDB, use RET or mouse-2 on the type description (‘[struct/union]’ or ‘[array]’). See Watch Expressions.

Registers Buffer

This buffer displays the values held by the registers (see Registers in The GNU debugger). Press RET or click mouse-2 on a register if you want to edit its value. With GDB 6.4 or later, recently changed register values display with font-lock-warning-face.

Assembler Buffer

The assembler buffer displays the current frame as machine code. An arrow points to the current instruction, and you can set and remove breakpoints as in a source buffer. Breakpoint icons also appear in the fringe or margin.

Memory Buffer

The memory buffer lets you examine sections of program memory (see Examining memory in The GNU debugger). Click mouse-1 on the appropriate part of the header line to change the starting address or number of data items that the buffer displays. Alternatively, use S or N respectively. Click mouse-3 on the header line to select the display format or unit size for these data items.

When gdb-many-windows is non-nil, the locals buffer shares its window with the registers buffer, just like breakpoints and threads buffers. To switch from one to the other, click with mouse-1 on the relevant button in the header line.

27.6.5.7 Watch Expressions

If you want to see how a variable changes each time your program stops, move point into the variable name and click on the watch icon in the tool bar (gud-watch) or type C-x C-a C-w. If you specify a prefix argument, you can enter the variable name in the minibuffer.

Each watch expression is displayed in the speedbar (see Speedbar). Complex data types, such as arrays, structures and unions are represented in a tree format. Leaves and simple data types show the name of the expression and its value and, when the speedbar frame is selected, display the type as a tooltip. Higher levels show the name, type and address value for pointers and just the name and type otherwise. Root expressions also display the frame address as a tooltip to help identify the frame in which they were defined.

To expand or contract a complex data type, click mouse-2 or press SPC on the tag to the left of the expression. Emacs asks for confirmation before expanding the expression if its number of immediate children exceeds the value of the variable gdb-max-children.

To delete a complex watch expression, move point to the root expression in the speedbar and type D (gdb-var-delete).

To edit a variable with a simple data type, or a simple element of a complex data type, move point there in the speedbar and type RET (gdb-edit-value). Or you can click mouse-2 on a value to edit it. Either way, this reads the new value using the minibuffer.

If you set the variable gdb-show-changed-values to non-nil (the default value), Emacs uses font-lock-warning-face to highlight values that have recently changed and shadow face to make variables which have gone out of scope less noticeable. When a variable goes out of scope you can’t edit its value.

If the variable gdb-delete-out-of-scope is non-nil (the default value), Emacs automatically deletes watch expressions which go out of scope. Sometimes, when your program re-enters the same function many times, it may be useful to set this value to nil so that you don’t need to recreate the watch expression.

If the variable gdb-use-colon-colon-notation is non-nil, Emacs uses the ‘function::variable’ format. This allows the user to display watch expressions which share the same variable name. The default value is nil.

To automatically raise the speedbar every time the display of watch expressions updates, set gdb-speedbar-auto-raise to non-nil. This can be useful if you are debugging with a full screen Emacs frame.

27.6.5.8 Multithreaded Debugging

In GDB’s all-stop mode, whenever your program stops, all execution threads stop. Likewise, whenever you restart the program, all threads start executing. See All-Stop Mode in The GNU debugger. For some multi-threaded targets, GDB supports a further mode of operation, called non-stop mode, in which you can examine stopped program threads in the debugger while other threads continue to execute freely. See Non-Stop Mode in The GNU debugger. Versions of GDB prior to 7.0 do not support non-stop mode, and it does not work on all targets.

The variable gdb-non-stop-setting determines whether Emacs runs GDB in all-stop mode or non-stop mode. The default is t, which means it tries to use non-stop mode if that is available. If you change the value to nil, or if non-stop mode is unavailable, Emacs runs GDB in all-stop mode. The variable takes effect when Emacs begins a debugging session; if you change its value, you should restart any active debugging session.

When a thread stops in non-stop mode, Emacs usually switches to that thread. If you don’t want Emacs to do this switch if another stopped thread is already selected, change the variable gdb-switch-when-another-stopped to nil.

Emacs can decide whether or not to switch to the stopped thread depending on the reason which caused the stop. Customize the variable gdb-switch-reasons to select the stop reasons which will cause a thread switch.

The variable gdb-stopped-functions allows you to execute your functions whenever some thread stops.

In non-stop mode, you can switch between different modes for GUD execution control commands.

Non-stop/A

When gdb-gud-control-all-threads is t (the default value), interruption and continuation commands apply to all threads, so you can halt or continue all your threads with one command using gud-stop-subjob and gud-cont, respectively. The ‘Go’ button is shown on the tool bar when at least one thread is stopped, whereas ‘Stop’ button is shown when at least one thread is running.

Non-stop/T

When gdb-gud-control-all-threads is nil, only the current thread is stopped/continued. ‘Go’ and ‘Stop’ buttons on the GUD tool bar are shown depending on the state of current thread.

You can change the current value of gdb-gud-control-all-threads from the tool bar or from ‘GUD->GDB-MI’ menu.

Stepping commands always apply to the current thread.

In non-stop mode, you can interrupt/continue your threads without selecting them. Hitting i in threads buffer interrupts thread under point, c continues it, s steps through. More such commands may be added in the future.

Note that when you interrupt a thread, it stops with the ‘signal received’ reason. If that reason is included in your gdb-switch-reasons (it is by default), Emacs will switch to that thread.