Cover | Table of Contents

Table of Contents

Chapter 1: GDB Pocket Reference

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The GNU Debugger, GDB, is the standard debugger on GNU/Linux and BSD systems and can be used on just about any Unix system with a C compiler and at least one of several well-known object file formats. It can also be used on other kinds of systems as well. GDB has a very rich feature set, making it the preferred debugger of many developers the world over.

This pocket reference provides a complete summary of GDB command-line syntax, initialization files, expressions, variables, and commands. It also describes the source code locations for GDB and two other graphical debuggers based on GDB.

A full introduction to GDB may be found in itsa documentation, which is included in the source code. This documentation is also available from the Free Software Foundation in Debugging with GDB: The GNU Source-Level Debugger, by Richard M. Stallman, Roland Pesch, Stan Shebs, et al.

This book follows the typographic conventions that are outlined below:

Constant width

Used for directory names, commands, program names, functions, variables, and options. All terms shown in constant width are typed literally. It is also used to show the contents of files or the output from commands.

Constant width italic

Used in syntax and command summaries to show generic text; these should be replaced with user-supplied values.

Constant width bold

Used in examples to show text that should be typed literally by the user.

Italic

Used to show generic arguments and options; these should be replaced with user-supplied values. Italic is also used to indicate URLs, macro package names, filenames, comments in examples, and the first mention of terms.

$

Used in some examples as the Bash, Bourne or Korn shell prompt.

program (N )

Indicates the "manpage" for program in section N of the online manual. For example, echo (1) means the entry for the echo command.

[ ]

Surround optional elements in a description of syntax. (The brackets themselves should never be typed.) Note that many commands show the argument [files]. If a filename is omitted, standard input (usually the keyboard) is assumed. End keyboard input with an end-of-file character.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Introduction

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The GNU Debugger, GDB, is the standard debugger on GNU/Linux and BSD systems and can be used on just about any Unix system with a C compiler and at least one of several well-known object file formats. It can also be used on other kinds of systems as well. GDB has a very rich feature set, making it the preferred debugger of many developers the world over.

This pocket reference provides a complete summary of GDB command-line syntax, initialization files, expressions, variables, and commands. It also describes the source code locations for GDB and two other graphical debuggers based on GDB.

A full introduction to GDB may be found in itsa documentation, which is included in the source code. This documentation is also available from the Free Software Foundation in Debugging with GDB: The GNU Source-Level Debugger, by Richard M. Stallman, Roland Pesch, Stan Shebs, et al.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Conventions Used in This Book

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This book follows the typographic conventions that are outlined below:

Constant width

Used for directory names, commands, program names, functions, variables, and options. All terms shown in constant width are typed literally. It is also used to show the contents of files or the output from commands.

Constant width italic

Used in syntax and command summaries to show generic text; these should be replaced with user-supplied values.

Constant width bold

Used in examples to show text that should be typed literally by the user.

Italic

Used to show generic arguments and options; these should be replaced with user-supplied values. Italic is also used to indicate URLs, macro package names, filenames, comments in examples, and the first mention of terms.

$

Used in some examples as the Bash, Bourne or Korn shell prompt.

program (N )

Indicates the "manpage" for program in section N of the online manual. For example, echo (1) means the entry for the echo command.

[ ]

Surround optional elements in a description of syntax. (The brackets themselves should never be typed.) Note that many commands show the argument [files]. If a filename is omitted, standard input (usually the keyboard) is assumed. End keyboard input with an end-of-file character.

^x

indicates a "control character," typed by holding down the Control key and the x key for any key x.

|

Used in syntax descriptions to separate items for which only one alternative may be chosen at a time.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Conceptual Overview

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

A debugger is a program that lets you run a second program, which we will call the debuggee. The debugger lets you examine and change the state of the debuggee, and control its execution. In particular, you can single-step the program, executing one statement or instruction at a time, in order to watch the program's behavior.

Debuggers come in two flavors: instruction-level debuggers, which work at the level of machine instructions, and source-level debuggers, which operate in terms of your program's source code and programming language. The latter are considerably easier to use, and usually can do machine-level debugging if necessary. GDB is a source-level debugger; it is probably the most widely applicable (portable to the largest number of architectures) of any current debugger.

GDB itself provides two user interfaces: the traditional command-line interface (CLI) and a text user interface (TUI). The latter is meant for regular terminals or terminal emulators, dividing the screen into separate "windows" for the display of source code, register values, and so on.

GDB provides support for debugging programs written in C, C++, Objective C, Java™, and Fortran. It provides partial support for Modula-2 programs compiled with the GNU Modula-2 compiler and for Ada programs compiled with the GNU Ada Translator, GNAT. GDB provides some minimal support for debugging Pascal programs. The Chill language is no longer supported.

When working with C++ and Objective C, GDB provides name demangling. C++ and Objective C encode overloaded procedure names into a unique "mangled" name that represents the procedure's return type, argument types, and class membership. This ensures so-called type-safe linkage. There are different methods for name mangling, thus GDB allows you to select among a set of supported methods, besides just automatically demangling names in displays.

If your program is compiled with the GNU Compiler Collection (GCC), using the -g3 and -gdwarf-2 options, GDB understands references to C preprocessor macros. This is particularly helpful for code using macros to simplify complicated

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Command-Line Syntax

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

GDB is invoked as follows:

gdb [options] [executable [corefile-or-PID]]
gdb [options] --args executable [program args ...]

The gdbtui command is equivalent to gdb --tui; it invokes GDB with the Text User Interface (TUI). The TUI is described in the later section "."

GDB has both traditional short options and GNU-style long options. Long options may start with either one or two hyphens. The command-line options are as follows.

--args

Pass on arguments after executable to the program being debugged.

--async, --noasync

Enable/disable the asynchronous version of the command-line interface.

-b baudrate, --baud baudrate

Set the serial port baud rate used for remote debugging.

--batch

Process options and then exit.

--cd dir

Change current directory to dir.

-c file, --core file

Analyze the core dump file.

-d dir, --directory dir

Search for source files in dir.

-e file, --exec file

Use file as the executable.

-f, --fullname

Output information used by the Emacs-GDB interface.

--help

Print a usage and option summary and then exit.

--interpreter interp

Select a specific interpreter/user interface. The command-line interface is the default, although there are other interfaces for use by frontend programs.

-m, --mapped

Use mapped symbol files if supported on this system.

-n, --nx

Do not read the .gdbinit file.

-nw, --nowindows

Force the use of the command-line interface, even if a windows interface is available.

-p pidnum, -c pidnum, --pid pidnum

Attach to running process pidnum.

-q, --quiet, --silent

Do not print the version number on startup.

-r, --readnow

Fully read symbol files on first access.

-s file, --symbols file

Read symbols from file.

--se file

Use file for both the symbol file and the executable file.

--statistics

Print statistics about CPU time and memory usage after each command finishes.

-t device, --tty device

Use device for input/output by the program being debugged.

--tui

Use the Terminal User Interface (TUI).

-x file, --command file

Execute GDB commands from file.

--version

Print version information and then exit.

-w, --windows

Force the use of a window interface if there is one.

--write

Allow writing into executable and core files.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Initialization Files

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Two files are used to initialize GDB and the readline library, respectively.

At startup, GDB reads its initialization file. This is a file of commands, such as option settings, for example, that you tell GDB to run every time it starts up. The initialization file is named .gdbinit on Unix (BSD, Linux, etc.) systems. Some MS-Windows versions of GDB use gdb.ini instead. Empty lines (they do nothing) are allowed, and comments in initialization files start with a # and continue to the end of the line. GDB executes commands from initialization files and from the command line in the following order:

1. Commands in $HOME/.gdbinit. This acts as a "global" initialization; settings that should always be used go here.
2. Command-line options and operands.
3. Commands in ./.gdbinit. This allows for option settings that apply to a particular program by keeping the file in the same directory as the program's source code.
4. Command files specified with the -x option.

You may use the -nx option to make GDB skip the execution of the initialization files.

Just like the Bash shell, GDB uses the readline library to provide command-line history and editing. You may use either vi- or Emacs-style commands for editing your command line. The readline library reads the file ~/.inputrc to initialize its settings and options. The details are beyond the scope of this book; see the Bash and GDB documentation or the online Info system for the full story. Here is a sample .inputrc file:

set editing-mode vi	Use vi editor commands
set horizontal-scroll-mode On	Scroll line left/right as cursor moves along it
control-h: backward-delete-char	Use ^H as backspace character
set comment-begin #	For Bash, # starts comments
set expand-tilde On	Expand ~ notation
"\C-r": redraw-current-line	Make ^R redraw the current input line

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

GDB Expressions

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

GDB can be thought of as a specialized programming language. It has variables and operators similar to those of C, and special features for debugging. This section looks at the different kinds of expressions that GDB understands.

Every time you print a value with print, GDB saves the value in the value history. You can reference these saved values by their numeric place in the history, preceded with a $. GDB reminds you of this by printing $n = val. For example:

$ gdb whizprog
...
(gdb) print stopped_early
$1 = 0
(gdb) print whiny_users
$2 = TRUE
(gdb)

A plain $ refers to the most recent value in the value history. This can save considerable typing. If you've just looked at a pointer variable, you can use:

(gdb) print *$

to print the contents of whatever the pointer is pointing to. $$ refers to the next most recent value in the history, and $$n refers to the value n places from the end. (Thus, $n counts from the beginning, while $$n counts from the end.)

You can use show values to see the values in the history. Whenever GDB reloads the executable (rereads the symbol table), it clears the value history. This is because the value history may have contained pointers into the symbol table and such pointers become invalid when the symbol table is reloaded.

GDB lets you create convenience variables. These are variables you can use to store values as you need them. Their names begin with a $ and consist of alphanumeric characters and underscores. They should start with a letter or underscore. (Note that values in the value history have names that are numeric.) You might want to use a convenience variable as an array index:

(gdb) set $j = 0
(gdb) print data[$j++]

After these two commands, simply hitting the ENTER key repeats the last command, stepping through the array one element at a time.

GDB predefines several convenience variables. It also enables you to access the machine registers using predefined register names. Register names vary with machine architecture, of course, but there are four predefined registers available on every architecture.

The following list summarizes the convenience variables and predefined registers. The last four entries in the list are the registers that are always available.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

The GDB Text User Interface

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

GDB, in its default mode, shows its line-oriented heritage. When single-stepping, it displays only one line of source code at a time. Graphical debuggers can show you much more, and indeed many programmers prefer a graphical debugger, if only for this reason. However, recent versions of GDB offer a text user interface (TUI), which uses the tried-and-true curses library to provide several "windows" on a regular terminal or terminal emulator, such as an xterm. This can be quite effective, especially since it allows you to do everything from the keyboard.

A number of set options and GDB commands are specific to the TUI. These are listed along with the rest of the set options and GDB commands in the later section "," and in the later section "."

Unfortunately (as of GDB 6.3), the TUI is still immature; I could not get several documented features to work. Thus this book doesn't provide detailed coverage of it. However, it should improve over time, and you should continue to evaluate it to see whether it meets your needs.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Group Listing of GDB Commands

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This section summarizes the GDB commands by task. Esoteric commands, such as those used by GDB's maintainers, or to cross-debug remote systems connected via serial port or a network, have been omitted.

Alias	Short for ...	Alias	Short for ...
bt	backtrace	i	info
c	continue	l	list
cont	continue	n	next
d	delete	ni	nexti
dir	directory	p	print
dis	disable	po	print-object
do	down	r	run
e	edit	s	step
f	frame	share	sharedlibrary
fo	forward-search	si	stepi
gcore	generate-core-file	u	until
h	help	where	backtrace

awatch	Set an expression watchpoint.
break	Set a breakpoint at a line or function.
catch	Set a catchpoint to catch an event.
clear	Clear a given breakpoint.
commands	Specify commands to run when a breakpoint is reached.
condition	Supply a condition to a particular breakpoint.
delete	Delete one or more breakpoints or auto-display expressions.
disable	Disable one or more breakpoints.
enable	Enable one or more breakpoints.
hbreak	Set a hardware-assisted breakpoint.
ignore	Set the ignore-count of a particular breakpoint.
rbreak	Set a breakpoint for all functions matching a regular expression.
rwatch	Set a read watchpoint for an expression.
tbreak	Set a temporary breakpoint.
tcatch	Set a temporary catchpoint.
thbreak	Set a temporary hardware-assisted breakpoint.
watch	Set an expression watchpoint.

call	Call a function in the program.
delete display	Cancel one or more expressions that have been set to display when the program stops.
delete mem	Delete a memory region.
disable display	Disable one or more expressions that have been set to display when the program stops.
disable mem	Disable a memory region.
disassemble	Disassemble a section of memory.
display	Print the value of an expression each time the program stops.
enable display	Enable one or more expressions that have been set to display when the program stops.
enable mem	Enable a memory region.
inspect	Same as print.
mem	Define attributes for a memory region.
output	Similar to print, but doesn't save the value in history and doesn't print a newline. For scripting.
print	Print the value of an expression.
print-object	Cause an Objective C object to print information about itself.
printf	Print values such as the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Summary of set and show Commands

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The set command accepts a large number of different parameters that control GDB's behavior. Many of the accepted parameters are rather esoteric. The show command displays the values of the same parameters as set accepts. The following section summarizes the parameters and how they affect GDB.

For most of the options, set option and set option on are equivalent; they enable the option. Use set option off to disable the option.

annotate

set annotate level
show annotate

Set the annotation_level variable to level. GUI programs that call GDB as a subsidiary process use this variable.

architecture

set architecture architecture
show architecture

Set the architecture of target to architecture. Primarily used in cross-debugging.

args

set args
show args

Give the debuggee the argument list when you start it. The run command uses this list when it isn't given any arguments. See the entry for run in the later section "."

auto-solib-add

set auto-solib-add
show auto-solib-add

Automatically load symbols from shared libraries as needed. When set to off, symbols must be loaded manually with the sharedlibrary command.

auto-solib-limit

set auto-solib-limit megs
show auto-solib-limit

Limit the size of symbols from shared libraries that will be automatically loaded to megs megabytes. Not available on all systems.

backtrace

set backtrace limit count
show backtrace limit
set backtrace past-main
show backtrace past-main

The first syntax limits the number of stack frames shown in a backtrace to count. The default is unlimited. The second syntax controls whether GDB shows information about frames that precede the main( ) function. Such startup code is usually not of interest, thus the default is off.

breakpoint

set breakpoint pending val
show breakpoint pending

How GDB should handle breakpoint locations that can't be found (for example, if a shared library has yet to be loaded). Values are on, off, or auto. When val is on, GDB automatically creates a pending breakpoint. For auto, it asks you. For off, pending breakpoints are not created.

can-use-hw-watchpoints

set can-use-hw-watchpoints 

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Summary of the info Command

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The info command displays information about the state of the debuggee (as opposed to show, which provides information about internal GDB features, variables, and options). With no arguments, it provides a list of possible features about which information is available.

info ...	Information displayed
address sym	Information about where symbol sym is stored. This is either a memory address or a register name.
all-registers	Information about all registers, including floating-point registers.
args	Information about the arguments to the current function (stack frame).
break [bpnum]	Information about breakpoint bpnum if given, or about all breakpoints if not.
breakpoints [bpnum]	Same information as the info break command.
catch	Information on exception handlers active in the current frame.
classes [regexp]	Information about Objective-C classes that match regexp, or about all classes if regexp is not given.
display	Information about items in the automatic display list.
extensions	Information about the correspondence of filename extensions to source code programming languages.
f [address]	Same information as the info frame command.
files	Information about the current debugging target, including the current executable, core, and symbol files.
float	Information about the floating-point hardware.
frame [address]	With no argument, print information about the current frame. With an address, print information about the frame containing address, but do not make it the current frame.
functions [regexp]	With no argument, print the names and types of all functions. Otherwise, print information about functions whose names match regexp.
handle	The list of all signals and how GDB currently treats them.
line line-spec	The starting and ending address for the code containing the line specified by line-spec. See list in the "" section for a description of line-spec. This sets the default address to the starting address for the given line, so that x/i may be used to examine instructions.
locals	Information about local variables (static or automatic) accessible from the current frame.
macro macroname	Show the definition and source location for the macro

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Alphabetical Summary of GDB Commands

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The following alphabetical summary of GDB commands includes all those that are useful for day-to-day debugging. Esoteric commands, such as those used by GDB's maintainers, or to cross-debug remote systems connected via serial port or a network, have been omitted.

Many of these commands may be abbreviated. The list of abbreviations is provided in the earlier section "."

add-symbol-file

add-symbol-file file addr [-mapped] [-readnow]
add-symbol-file file [-s section address ...]

Read additional symbol table information from file, which was dynamically loaded into the debuggee outside of GDB's knowledge. You must tell GDB the address at which it was loaded, since GDB cannot determine this on its own. The -mapped and -readnow options are the same as for the file command; see file for more information. You may use -s to name the memory starting at address with the name section. You can provide multiple section/address pairs with multiple -s options.

advance

advance bp-spec

Continue executing until the program reaches bp-spec, which can have any value acceptable to the break command (see break for the details). This command is like the until command, but it does not skip recursive function calls, and the location doesn't have to be in the current frame.

apropos

apropos regex

Search through the built-in documentation for commands that match the regular expression regex. Multiple words constitute a single regular expression. GDB uses Basic Regular Expressions (like those of grep); however, it also ignores case when matching.

attach

attach pid

Attach to the running process pid, and use it to obtain information about in-memory data. You must have appropriate permission to attach to a running process.

awatch

awatch expression

Set a watchpoint to stop when expression is either read or written. (Compare rwatch and watch.)

backtrace

backtrace [count]

Print a full list of all stack frames. With a positive count, print only the innermost count stack frames. With a negative count, print only the outermost count stack frames.

break

break [bp-spec]
break bp-spec if condition

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Return to GDB Pocket Reference