Debugging with GDB#

GDB is a debugger. It lets you run a program one step at a time, pause at a specific line, inspect variables, and see where a program stops.

Use GDB after your program compiles. It is most useful when the program runs but gives the wrong answer, crashes, or stops before you expect it to stop.

The current course syllabus, assignment instructions, programming standards, and applicable CSN or college policies take precedence over anything on this website.

Compile with debug symbols#

GDB works best when the executable contains debugging information. On Bellagio, $CXXFLAGS already includes debugging support. You should still know how to request debugging information when you compile.

For a single source file:

g++ -ggdb $CXXFLAGS main.cpp -o main

For multiple source files:

g++ -ggdb $CXXFLAGS main.cpp helper.cpp -o main

The -ggdb option tells g++ to include debugging information for GDB. The -o main option names the executable main.

Start GDB#

Start GDB with the executable, not the source file:

gdb ./main

You should see a GDB prompt:

(gdb)

Commands typed at this prompt control the debugger.

Run the program#

At the GDB prompt, type:

run

If your program needs command-line arguments, put them after run:

run input.txt

Set a breakpoint#

A breakpoint tells GDB where to pause the program.

Set a breakpoint at a line number:

break main.cpp:12

Set a breakpoint at a function:

break main

Then run the program:

run

When the program reaches the breakpoint, GDB pauses before executing that line.

Step through code#

Use these commands after the program pauses:

The GDB command continue is not the C++ continue statement. It is a debugger command that tells GDB to resume the stopped program.

Use next most of the time when you are beginning. Use step when you want to enter a function and inspect what happens inside it.

Inspect variables#

Print the value of a variable:

print total

Print the value of an expression:

print count + 1

Watch a variable each time the program stops:

display total

Remove automatic displays:

undisplay

A short example session#

Compile the program:

g++ -ggdb $CXXFLAGS main.cpp -o main

Start GDB:

gdb ./main

At the GDB prompt:

break main
run
next
print total
continue
quit

This starts the program, pauses at main, executes one line, prints total, continues running, and exits GDB.

Optional: disassembly#

Most CS 135 and CS 202 debugging does not require assembly language. If you are asked to inspect disassembly, set Intel syntax first:

set disassembly-flavor intel
disassemble

Use this only when you have a reason to inspect machine-level instructions. For ordinary programming assignments, variables, breakpoints, and stepping are usually the right tools.

Exit GDB#

To leave GDB, type:

quit

If GDB asks whether to quit while the program is running, answer:

y

Common mistakes#

• Starting GDB with main.cpp instead of ./main.
• Forgetting to compile after changing the source file.
• Forgetting to include debug symbols when compiling.
• Setting a breakpoint on a line that does not contain executable code.
• Using step when next would be easier.

When asking for help#

If you ask for debugging help, include the command you used to compile, the GDB command you ran, the line where you set a breakpoint, and the output or error message you saw.

Do not post your source code publicly. See How to Ask a Debugging Question for the information to include.