GDB Quick Reference


The GNU Debugger, GDB, is more or less the defacto tool for debugging software running on a *nix (UNIX, Linux, BSD, Solaris, OS X, etc) system. It supports a wide variety of languages including Ada, C, C++, Objective-C, and Pascal, and can even be used to debug programs that are already running, or running on other machines. Whereas some tools are geared toward finding memory problems in running programs (Valgrind), or looking for security flaws and other bugs in source (Splint), GDB is geared primarily toward debugging logic problems.

GDB works by allowing the developer to step through their program one line at a time or to stop execution at a desired point, such as when a given function is called, a specific line is reached, or the value in a particular variable is changed. Once execution has been stopped, the develeper can take a look at the current value of variables or examine a stack trace to see what called the function.

This page is intended as a quick overview of GDB's various functions, rather than a comprehensive discussion of everything it can do. If you want to learn about GDB's more advanced functionality, the FSF provides a stunningly comprehensive set of documentation.

Starting GDB

To use GDB effectively, your program must have been compiled using g++'s -g flag. If you're using a Makefile of the sort provided in class, you're set.

Assuming your program is named foo, you can invoke GDB using the command gdb foo.

Controlling Program Exection

As noted above, GDB provides developers with very, very fine-grained control over the execution of their program. Here are some commands for tapping into that control:

Command When To Use Function
run Once you've configured some breakpoints, or after the target has finished running. Begins execution of the target program, and turns control over to same. The target will continue to execute until the first break / watch point is encountered, or the target exits, whichever comes first.
step or s Any time a running target is stopped Run target until execution arrives at the next line of source code, then return control to GDB. Will enter or leave functions as necessary.
next or n Any time a running target is stopped Works like step, except that it treats function calls as single lines, rather than expanding the function and stepping through it.
until Any time a running target is stopped Same as next, except that it only steps through the body of a loop once. After the first pass, the loop runs to completion before returning control to GDB.
finish Any time a running target is stopped Run until the current function returns, then give control back to GDB. Prints the return value of the function.
continue or c Any time a running target is stopped Resume execution of the target and run until the next break / watch point or until the target exits, whichever is first.

Setting Stopping Conditions (Breakpoints and Watchs)

Most of the commands for controlling target execution rely on the target being stopped. The set of commands below can be used to cause GDB to automatically stop execution of the target when certain conditions are met. (As should be obvious, these can only be used when the program is stopped.)

Command Parameters Function
break line number or function name Set a breakpoint to stop the target every time it reachs the specified line number or a call to the designated function. Use fully qualified function names for class member functions. A file name may be prepended to the line number or function in the case of ambiguity (eg foo.cpp:10).
tbreak line number or function name Works like break, except the breakpoint will only stop execution once, rather than every time it is encountered.
info breakpoints none Displays information about all currently set breakpoints.
watch variable name Stop execution of the target any time the named variable is written to. Variable must be defined in the current scope, but you may set watchpoints on private class members. Watchpoints are automatically deleted when they are no longer in the current scope.
rwatch variable name Like watch but stops when the variable is read, rather than written.
awatch variable name Like watch or rwatch, but stops for both read and write.
info watchpoints none Displays information about all currently set watchpoints.
delete breakpoint or watchpoint Delete the specified breakpoint or watchpoint, so it will no longer stop execution of the target.

Looking At Data

In addition to providing control over the execution of a target program, GDB is also able to display the contents of variables within the program. This is especially helpful when trying to analyze how or why a variable is changing. Here are some commands for displaying variables.

Command Parameters Function
print or p variable name Displays the contents of the variable. In the case of pointers, prints out the address to which the pointer points. Only the contents of variables which are currently in-scope can be printed.
display variable name Similar to print, but automatically prints the contents of the variable whenever target execution is stopped while the variable is in-scope.
info display none Prints out information about any currently set automatic displays.

Last Update 30 May 2010