CS 24 GDB tutorial

Keegan McAllister and Sami Zerrade

April 14, 2008

Introduction

GDB is a debugger, a tool that allows you to interactively examine and manipulate a program as it runs. GDB supports many programming languages, including C and assembly.

Compiling

GDB requires the compiler or assembler to provide extra debugging information; this does not happen by default and must be enabled by a command-line option. For C programs, this is done by giving the -g flag when you execute GCC from the command line:

    [user@pong:~]> gcc -g -o foo foo.c

Since optimization tends to make debugging more difficult, you should avoid giving any of the optimization flags to GCC (-O1, -O2, etc.) If you are using the provided Makefile to compile your C project, the -g flag should be already specified; this is accomplished by the line

    CFLAGS=-Wall -g

in the Makefile.

For assembly language programs, there are two ways to invoke the assembler. You can invoke the assembler with GCC, in which case debugging is enabled the exact same way as for C. Alternatively, you can run the assembler directly, passing it the -g option, like this:

    [user@pong:~]> as -g -o foo foo.s

If you are using make to compile an assembly program, the Makefile must contain the line

    ASFLAGS=-g

to ensure that as is passed the debug option. (This line is missing from the Lab 2 Makefile; you can add it right after the CFLAGS line.)

Starting GDB

Invoke GDB by giving the executable you wish to debug as an argument:

    [user@pong:~]> gdb foo

After some startup messages you should get the GDB prompt:

    (gdb)

GDB accepts many commands (far more than you will need for CS 24). Documentation on all commands is available through the on-line help system which you can access with the command

    (gdb) help

What follows is a short listing of the commands we feel will be most useful for CS 24.

Running your program

run arguments
Starts executing your program as if you had typed
[user@pong:~]> ./foo arguments
but runs it under the control of GDB. The arguments can include UNIX input/output redirection, e.g.
(gdb) run < input.txt > output.txt
GDB will execute your program until it causes an error (segmentation fault, etc.), reaches a breakpoint (see below), or terminates. In any case, it will return you to the GDB prompt.
quit
Leave GDB.
step
Execute one line of source code. Can be abbreviated as s. To execute more than one step, give an optional integer argument, e.g. step 5
stepi
Like step, but executes one machine instruction exactly. In high-level languages like C, one source line will usually correspond to many machine instructions.
next
Like step, but executes any function call(s) as one step rather than proceeding into the function. Can be abbreviated as n. There is also nexti with the expected meaning.
finish
Execute until the current function returns.
continue
Execute until one of the conditions listed above for run is encountered.

Inspecting program state

bt
Display the active function calls. Short for backtrace.
print exp
Evaluate and print the value of the source-language expression exp. When debugging a C program you could do something like
(gdb) print 2*x + y
where x and y are C variables. When debugging assembly, you can refer to a register by prefixing its name with a dollar sign, e.g.
(gdb) print $eax
i reg
Print the current value of each machine register. Short for info registers.
x/16xb addr
Print 16 hexadecimal bytes of memory, starting from addr (which can be an expression involving literals, registers, variables, etc.) If addr is omitted it will start where the last x command left off. For information on specifying other formats, type help x.
list
Print program source around the currently-executing location. See help list for other uses.
disassemble
Disassemble machine code around the currently-executing location. Produces assembly code even when the source language is high-level. See help disassemble for other uses.

Breakpoints

break pos
Place a breakpoint at position pos. This can be the name of a function, a line number, or a combination filename/line number (e.g. foo.c:5). If and when many-step execution (e.g. by run or continue) reaches this point, GDB will stop executing and return to the GDB prompt.
As an example, if you want to single-step your program from the beginning, you could start with
    (gdb) break main
    Breakpoint 1 at 0x8048355: file foo.c, line 2.
    (gdb) run
i break
Display active breakpoints. Short for info breakpoints.
del break n
Delete breakpoint number n.

Other resources

In addition to this (brief) tutorial, there are many other GDB resources on the Web, including online manuals, a quick reference card, and other tutorials.