Home : Resources : Using GDB
Helps to know:

Sections:

Simple commands
Setting breakpoints and watchpoints
Calling functions
Setting/viewing variables
Reading the core file
Backtrace and changing frames
Handling Signals
Use help
Links

These are the commands I use 95% of the time when debugging with GDB. Take an hour learn GDB: it will save you dozens in the future.

Simple commands

To use GDB, the program must be compliled with the -g flag. Thus, compile with
gcc -g myprogram.c

To start GDB, type "gdb executableFilename", most likely "gdb a.out".

-g: compiler flag needed to use gdb
gdb executableFilename: load gdb
r command_line_arguments: run the filename, passing it the command_line_arguments. You can still do piping, such as r < myfile instead of a.out < myfile.
l: short for list, lists the current line + 10 more. Type "l 50" or "l myfunction" to display a specific line or function.
next: execute until the next line (if you are on line 100, stops at line 101).
step: execute until next instruction (if line 100 is a function call, it steps into the function).
finish: finish executing the current function (doing a sequence of nexts). Useful when accidentally stepping into a function.
q: quit GDB.

Setting Breakpoints and Watchpoints

A breakpoint stops your program whenever it reaches a certain line or function. It stops at the line, but does not execute it. To use, type something like:

(gdb) break 186
(gdb) break myfunction

Keep a source code editor open while debugging. This way you can find a line number quickly. Another way is to type "l functionname" to print the function. Then type l to 

Watchpoints are like breakpoints, but they only stop when a certain condition is false. I usually only use breakpoints to examine variables for incorrect values, so watchpoints save me this step.

(gdb) watch x == 3

will break whenever x the expression x == 3 changes. Thus, if x is always supposed to be 3 (in theory), you can have gdb break whenever this becomes false. Likewise, if a variable is always supposed to stay in some range (such as y < 14, or myPtr != NULL), set a watchpoint.

I find them more useful than breakpoints, because I just end up examining variables at a breakpoint. It is easier to watch for when a variable has an illegal value and break then.

break linenumber: set breakpoint at line N
continue: Keep executing the program (until get to next breakpoint)
delete N: remove breakpoint number N.
watch expression: break when expression changes.

Calling functions

Useful fact: you can call functions within gdb. Suppose you want to find the length of a string. You can print it and count the letters yourself, but as a programmer, you should have an urge to find an easier way. There is: type

(gdb) strlen(mystring)

and gdb will call the library function strlen. You can also call your own functions for debugging purposes. This is safer than inserting actual function calls into your code -- you don't have to remove them later. Be careful not to call a potentially buggy function, it could make your program crash (unless that is what you want to test).

Setting/Viewing Variables

I view variables a lot. Type

(gdb) print x

to print the the value of variable x once.Type

(gdb) display x

To have x displayed after every GDB command. To remove a variable from display, type

(gdb) undisplay x

or 

(gdb) undisplay 3

To set a variable, simply type

(gdb) set x = 3

Simple, eh? This is useful when checking your functions for strange inputs.

print x: display value
display x: always display x
undisplay N: remove item N from display.
set X = Z: Set variable X to value Z

Backtrace and changing frames

Type "bt" (backtrace) to print the current function stack. It shows where the program is, with respect to the depth of function. Thus, if main calls a which calls b which calls c, and you are in function c, the function stack will be

c
b
a
main

and the appropriate line numbers. Commands:

bt: Display current function stack.
up: Move up in function stack. Can re-examine local variables, etc. 
down: Move down in stack.
return: Force current function to return.

Reading Core Files

When beginning programming, I feared core dumps. I didn't know what to do or what caused them. GDB fixes that. A core file is a snapshot of your program when it crashed (stored in the file core). It keeps track of where your program was, all the variable's values, etc. Type

gdb myexecutable core

gdb a.out core

to have gdb load your program at the exact point it crashed. Next, type

(gdb) bt

To print the function stack, and figure out where your program crashed. After doing this you'll probably know what made your function crash. If questions remain, use the techniques above (such as examining variables).

Handling Signals

You may want GDB to ignore certain signals. To do this:

handle SIGNAME action

handle SIGUSR1 nostop

Use nostop, noprint, ignore, etc.

Getting Help

GDB is fairly well documented. Type help to get a list of topics. Type "help topic" for info on a specific topic (such as "help breakpoints").

Links

Those are all the commands I use when debugging. Other tutorials.

Short Tutorial
Longer Tutorial

Cheatsheets: 1 2 3
(google search "gdb cheatsheet")

Send questions, comments, corrections, and suggestions to [email protected]
Last modified: 4/4/02