*gdb.txt* For Vim version 6.2. Last change: 2004 Mar 28
VIM REFERENCE MANUAL by Xavier de Gaye
The GDB interface user guide *gdb*
This document explains how to use Vim's GDB interface
1. Introduction |gdb-introduction|
2. Starting VimGDB |gdb-starting|
3. GDB commands |gdb-commands|
4. Gdb console |gdb-console|
5. The variables window |gdb-variables|
6. Mappings |gdb-mappings|
7. Gdb assembly |gdb-assembly|
8. Limitations |gdb-limitations|
{Vi does not have any of these commands}
VimGDB has been tested with GNU GDB 5.3 and 6.0 on linux-2.4.3, with GNU
GDB 2003-03-03-cvs (cygwin-special) on Cygwin.
The GDB interface only works when Vim is compiled with the |+gdb| feature.
==============================================================================
1. Introduction *gdb-introduction*
Vim's gdb interface provides the following features:
* Input is done using the window input-line with syntax highlighting so that
you can check GDB syntax while typing commands. Any GDB command can be
mapped to a key sequence using Vim key mappings. This allows, for example,
to set/clear a breakpoint or print a variable's value at the current cursor
position by just hitting a key.
* GDB output goes to a Vim buffer displayed in the gdb console. This includes
output done by the program you are debugging. The gdb console status line
shows the target status.
* You can send an interrupt to GDB and the program it is running.
* A pool of assembly buffers holds the assembly code for the most recently
used functions wether there is source code information for these functions
or not. This feature can be disabled or interrupted.
* Breakpoints are highlighted in source code and in the assembly buffers. The
highlighting includes the last two digits of the breakpoint number so that
they can be easily identified. Disabled breakpoints are noted with a
different highlighting color. VimGDB automatically finds the source file for
the breakpoint if it exists, and displays and highlights the line. When
there is no debugging information or source files, VimGDB disassembles the
function containing the breakpoint and displays and highlights its line.
* Each time GDB displays a stack frame, VimGDB automatically finds the source
file for that frame, displays and highlights the line. When there is no
source code for the frame or when doing instruction stepping (stepi, nexti)
the program counter line within an assembly window is highlighted.
* Depending on the GDB version you are using, VimGDB may run in two different
modes: level 2 when using the deprecated GDB annotations level 2 and
level 3 when using GDB/MI and the new annotations level 3. See |gdb-modes|.
Mode selection is automatically done by VimGDB.
* Any variable (any expression in level 2 mode) can be "dropped" in the gdb
variables window by selecting it and hitting <CTR-P>. The variable's value
is updated and highlighted whenever changed. To remove a variable, just
delete it from the gdb variables window with a Vim command. See
|gdb-variables|.
* GDB command and file name completion. This also works while entering a GDB
user-defined sequence of commands or a list of commands for a breakpoint.
* The current GDB session can be abandonned with the "quit" GDB command and
another GDB session started later, within the same Vim session, using
possibly a different GDB program.
==============================================================================
2. Starting VimGDB *gdb-starting*
Before starting VimGDB, here are some optional Vim commands that you may want to
run or include in your .vimrc: >
Start VimGDB. There are two ways to do that:
1) Open the window input-line: >
<
and then start an instance of GDB by pressing <CR> inside the window
input-line, or enter any GDB command in this window.
To open the window input-line, one can also also hit <Space> in Vim normal mode
when 'gdb_mappings.vim' has been sourced.
2) Start VimGDB directly without using the window input-line by using a
<Space> as argument to the function gdb(): >
<
or start GDB and execute straightaway a GDB command: >
<
To stop GDB, type the GDB "quit" command in the window input-line. To start
another instance later, use the same procedure as described above, possibly
with another GDB program by setting Vim option 'gdbprg' to a different name.
In order to have both GDB and Vim's gdb interface find your source files when
they are not located in the current directory, you must add the relevant
directories to GDB source path. For example, from ~/tmp run the following GDB
commands in the window input-line:
file ~/src/vim/vim62/src/vim ~
directory ~/src/vim/vim62/src/ ~
break gdb.c:1170 ~
will set a breakpoint and edit gdb.c with line 1170 highlighted. You do not
need to issue the "directory" command most of the time when you launch Vim in
the debugged program's directory.
*gdb-modes*
VimGDB modes:
------------
VimGDB may run in two different modes called level 2 and level 3. Level 2 uses
GDB annotations level 2. Level 3 uses GDB/MI and annotations level 3. When
starting, VimGDB automatically selects the appropriate mode.
There are two reasons why you should be aware of the mode you are using. The
first is that the behaviour of |gdb-variables| is different, depending on the
mode. The second reason is that you may want to tell the mode that was being
used when sending VimGDB bug reports.
The mode VimGDB is currently using is shown on the first line displayed in the
gdb console after GDB starts. Another way to know which mode you are on, is to
run the GDB command "show annotate". The resulting "Annotation_level" has the
same value as VimGDB mode level.
The chosen mode depends on the GDB version you are running (technical: level 3
mode is chosen when the GDB command "interpreter-exec" that gives access to
GDB/MI is supported by GDB). GDB 5.3 runs with level 2 mode. GDB 6.0 and above,
and GDB 2003-03-03-cvs on Cygwin all run with level 3 mode.
==============================================================================
3. GDB commands *gdb-commands*
To enter a GDB command using the Vim command line, call the Vim gdb()
function. For example, when you want to set a breakpoint in Vim at
gdb_parse_output_cli() type: >
It might be easier to use the gdb window input-line and enter the GDB command
directly within this window. The gdb window input-line can be opened by typing: >
or by hitting <Space> in Vim normal mode when 'gdb_mappings.vim' has been
sourced.
The following keys have a special function within the gdb window input-line:
CTRL-Z send an interrupt to GDB
<Tab> ask GDB for a completion
<CR> send the line where the cursor is positionned as
a command to GDB. On an empty line, cause a new GDB
instance to be started if one is not already running
CTRL-C CTRL-C standard Vim method for aborting a window input-line.
It also sends an interrupt to GDB
Of course using key mappings is even easier than the gdb window input-line.
See |gdb-mappings| for available mappings after sourcing 'gdb_mappings.vim'.
Note: As long as the current GDB command has not completed, VimGDB discards
further commands except interrupts and displays a message on the command line
warning that the command has been discarded.
==============================================================================
4. Gdb console *gdb-console*
You can hide the gdb console at any time with the Vim |:quit| command. The
gdb console pops up when:
GDB outputs a frame (in other words: the debuggee stopped)
the gdb() function is called
The gdb console initial height is set according to the 'previewheight' option
value.
In Normal mode, the gdb console is updated whenever GDB outputs some data. In
all the other Vim modes, VimGDB stops reading GDB's output.
All successive GDB sessions within the same Vim session share an unique buffer
displayed in the gdb console.
The gdb console status line displays the name of the symbol file and the target
status. When the debuggee is stopped, the target status is replaced by the
disassembled instruction of the program counter.
==============================================================================
5. The variables window *gdb-variables*
The variables window and its related commands behave differently depending on
the mode being used. See |gdb-modes| for information on VimGDB modes. It is
worth upgrading to GDB 6.0 or later in order to run VimGDB with level 3, as
this level provides much better correctness in the display of variable values
(see below, sub-section "The level 3 mode").
The first part in this chapter discusses what is common to both modes.
The Vim option 'gdbvariables' (short name 'gdbvar', default value
"gdb-variables") defines the name of the buffer containing the GDB variables
that are displayed in the gdb variables window. This buffer is not related to
a file and belongs to the |special-buffers| category (buftype=nofile). When
this option is empty, the gdb variables window feature is disabled entirely.
*cr* *createvar*
The "createvar" command is used with the variables window to drop any valid
GDB variable (GDB expression in level 2) in the gdb variables window. For
example, to drop the variable "*curwin" in the gdb variables window: >
It is even easier to select in Visual mode in some source code the variable
you want to drop, and just hit CTRL-P ('gdb_mappings.vim' must have been
sourced).
The "createvar" command can be entered as any GDB command but is not a GDB
command. In level 2 this command is mapped to the GDB "display" command so
that typing "createvar" and "display" are equivalent. In level 3 the
"createvar" command is intercepted by VimGDB and internally mapped to GDB/MI
commands.
The "createvar" command syntax is:
createvar/FMT variable
where /FMT is optionnal and FMT may be one of:
`t'
Print as integer in binary. The letter `t' stands for "two"
`d'
Print as integer in signed decimal
`x'
Regard the bits of the value as an integer, and print in hexadecimal
`o'
Print as integer in octal
When dropping a variable into the gdb variables window, this window is popped
up if not already displayed: VimGDB picks up the first available window that
is not the gdb console and replaces its contents with the gdb variables window
buffer. It might be convenient sometimes to |:split| your windows before doing
the dropping.
In both modes, deleting a line in the variables window removes all the
corresponding references to the tracked variable in GDB and VimGDB.
Changed values are highlighted with the "Special" highlighting. With level 3,
when a variable goes out of scope, its value is highlighted with the "Comment"
highlighting.
The highlighting is done with the support of the gdbvar.vim syntax file. If
this file is missing or cannot be accessed by Vim, the equal sign that
separates variable from value in the gdb variables window are tagged with
(these signs are hidden when syntax is available): >
The gdb variables window buffer is 'modifiable', which means you can move
around lines, insert empty lines and even add your own comments as long as
none of your lines starts with a number followed by a colon (more precisely:
does not match the regular expression "^\s*\d\+:")
The level 2 mode:
----------------
This sub-section describes what is specific to level 2.
The gdb variables window uses the GDB "automatic display" feature. In level 2
the "createvar" command is mapped to the GDB "display" command so that typing
"createvar" and "display" are equivalent.
Level 2 is not restricted to dropping only variables, expressions can be
dropped as well in the variables window.
The expression value is updated whenever the debuggee stops or the GDB
"display" or VimGDB "createvar" command is run without argument. Note that the
expression must be valid in the current context in order to be evaluated by
GDB "automatic display" feature. This is one of the important differences with
level 3. To make it easier to track data, each value is highlighted whenever
changed.
To "undisplay" an expression, just delete it from the gdb variables window.
VimGDB will invoke GDB "undisplay" command transparently to remove this item
from GDB "automatic display list" next time the debuggee stops or the GDB
"display" or VimGDB "createvar" command is run without argument.
Conversely, if you invoke the GDB "undisplay" command corresponding to a
displayed line, VimGDB will delete this line from the gdb variables window
next time the debuggee stops or the GDB "display" or VimGDB "createvar"
command is run without argument.
When The Vim option 'gdbvariables' is empty or the variables buffer has been
wiped out, the gdb variables window feature is disabled entirely for the
current GDB session and the GDB "display" commands output goes unprocessed to
the gdb console.
The level 3 mode:
----------------
This sub-section describes what is specific to level 3.
Level 3 deals only with variables, not expressions. However this mode provides
with the variables window a much more powerful tool than is provided by
level 2.
First, variables are updated any time you enter any GDB command. If you are
tracking variable "int foo" with a current value of 100, and run the GDB
command "print foo = 333", then its value will be highlighted in the variables
window and the new value displayed.
The variables that are out of scope are highlighted with the "Comment"
highlighting.
Variables that are in scope are updated and highlighted whenever changed.
Here is an example involving the scope concept: >
Run VimGDB on this module and add variables to the variables window as
described in the module's comments step 1 and step 2. The variables argv[0],
period and mainstore are all in scope within functions foobar() and foo().
Their new values are displayed and highlighted as changed when changed in
foo() except mainstore that displays a value of {...} with the same
highlighting telling it has changed.
Trying to run the GDB "print" command on "period" while stopped in foo()
causes an error with the message 'No symbol "period" in current context'.
While in the same time, the variables window with GDB/MI is able to detect
changes in "period"'s value and to evaluate "period"'s value when stopped in
foo().
However, complex data such as structures cannot currently be evaluated by
VimGDB when not defined in the current context. Instead the following symbol
{...} is displayed and highlighted to tell you its value has changed. In this
case, to get the variable's value, go in the stack frame where this variable
is defined using the "up", "down" or "frame" GDB command and "print" it.
When exiting foobar(), period and mainstore become out of scope and are
highlighted with the "Comment" highlighting.
Note: The "createvar" command requires an argument in level 3. The "automatic
display list" and the variables are two independent features in level 3.
==============================================================================
6. Mappings *gdb-mappings*
The gdb() function accepts a string as single argument which is sent to GDB as
a GDB command. This can be used to map any command to a key sequence. Examples
of such mappings are given in 'macros/gdb_mappings.vim'. To use those
mappings, source the script: >
Once this done, hit key <F7> to toggle between the 'gdb_mappings.vim' mappings
and the default Vim mappings.
List of key mappings in 'gdb_mappings.vim':
<Space> launch the interactive gdb window input-line
CTRL-Z send an interrupt to GDB and the program it is running
B info breakpoints
L info locals
A info args
S step
I stepi
CTRL-N next: next source line, skipping all function calls
X nexti
F finish
R run
Q quit
C continue
W where
CTRL-U up: go up one frame
CTRL-D down: go down one frame
CTRL-B set a breakpoint on the line where the cursor is located
CTRL-E clear all breakpoints on the line where the cursor is located
CTRL-P Normal mode: print value of word under cursor
Visual mode: GDB command "createvar" selected expression, see
|gdb-variables|
CTRL-X print value of data referenced by word under cursor
CTRL-B and CTRL-E operate both on source code and on disassembled code in
assembly buffers.
==============================================================================
7. Gdb assembly *gdb-assembly*
If you do not care for assembly display, skip this section and add this line
to your .vimrc: >
The Vim 'asm' option defines the size of the pool of assembly buffers. This
pool is used as a cache and holds the disassembled code of the most recently
used functions. These buffers are 'notlisted', use |:ls!| to list them.
Assembly buffers are cleared when you run the following GDB commands: file,
exec-file or core-file.
The size of the pool of assembly buffers is defined by the value of the 'asm'
option at the start of each new GDB session (default 10, max hard limit 64).
When 'asm' is zero at the start of a new GDB session, assembly buffers are not
used at all for the whole session. When 'asm' is set to zero in the middle of
a GDB session, assembly buffers are temporarily not used until you set back
'asm' to a non-zero value.
The assembly buffers are used:
a - when setting a breakpoint and there is no debugging information or source
file, VimGDB disassembles the function containing the breakpoint and
displays and highlights its line in an assembly buffer
b - when the debuggee stops in a portion of code where there is no source
code, or when doing instruction stepping (stepi, nexti), an assembly
buffer is displayed and the program counter line highlighted
c - when doing source code stepping (not stepi or nexti) within some source
code and the corresponding assembly buffer is displayed simultaneously in
another window, the assembly window scrolls to make the program counter
line visible in the assembly code
When filling large assembly buffers, VimGDB displays a busy message. You can
interrupt the command at any time with a GDB interrupt CTRL-Z, except on
Cygwin.
Note: When the source is missing and the corresponding object is compiled with
'-g', GDB skips some frame annotations and therefore some $pc highlighting do
not occur. In this case, strip the debuggee with '--strip-debug' (or '-g':
remove debugging symbols only) to restore the normal behavior.
==============================================================================
8. Limitations *gdb-limitations*
You cannot include |+gdb| in a Vim version compiled with "small" or "tiny"
features, "normal" features is the minimum requirement.
You cannot set any command line argument to GDB. However, all of them can be
set from within GDB with the GDB "set" command, once it is started.
To enable syntax highlighting in the gdb console, the prompt must be surrounded
by parenthesis.
Cygwin:
------
The current port of GDB to Cygwin does not provide some features available on
other GDBs (these restrictions obviously apply also to Vim's gdb interface):
. cannot interrupt the running program under GDB control with SIGINT
. the program output is displayed only after the program terminates
. Tip: when debugging and "attach"ing to a running Vim process waiting
on the select() function, you must type any key (CTRL-L for example)
in the debuggee terminal in order to have GDB "attach" command complete