GDB Usage Summary for Debugging

Introduction

Start GDB by running the gdb command in a shell. After startup, GDB displays its banner and a prompt.

example gdb GNU gdb (Ubuntu 8.1.1-0ubuntu1) 8.1.1 Copyright (C) 2018 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "x86_64-linux-gnu". Type "show configuration" for configuration details. For bug reporting instructions, please see: <http://www.gnu.org/software/gdb/bugs/>. Find the GDB manual and other documentation resources online at: <http://www.gnu.org/software/gdb/documentation/>. For help, type "help". Type "apropos word" to search for commands related to "word". (gdb)

Example C Program

#include <stdio.h> int minus(int a,int b){ printf("In minus():n"); int c = a-b; return c; } int sum(int a, int b) { printf("In sum():n"); int c = a+b; return c; } void print(int xx, int *xxptr) { printf("In print():n"); printf(" xx is %d and is stored at %p.n", xx, &xx); printf(" ptr points to %p which holds %d.n", xxptr, *xxptr); int c = sum(2,3); int d = minus(3,2); } int main(void) { int x = 10; int *ptr = &x; printf("In main():n"); printf(" x is %d and is stored at %p.n", x, &x); printf(" ptr points to %p which holds %d.n", ptr, *ptr); print(x, ptr); return 0; }

Breakpoints

Set breakpoints by function name, line number, file:line, address, or offset. When the program reaches a breakpoint it will pause so you can inspect variables, view the stack, adjust breakpoints, or restart. The break command can be abbreviated to b.

Format

break <location>

Examples

(gdb) b main Breakpoint 1 at 0x758: file gdb_example.c, line 9.

Location examples

break <function-name> break <line-number> break <file>:<line-number> break <file>:<function-name> break +<offset> break -<offset> break *<address>

Example session

(gdb) b print Breakpoint 2 at 0x709: file gdb_example.c, line 4. (gdb) b gdb_example.c:5 Breakpoint 3 at 0x715: file gdb_example.c, line 5. (gdb) b +3 Note: breakpoint 2 also set at pc 0x709. Breakpoint 4 at 0x709: file gdb_example.c, line 4. (gdb) b *0x709 Note: breakpoints 2 and 4 also set at pc 0x709. Breakpoint 5 at 0x709: file gdb_example.c, line 4. (gdb)

Verify breakpoints with info break

(gdb) info break Num Type Disp Enb Address What 1 breakpoint keep y 0x0000000000000758 in main at gdb_example.c:9 2 breakpoint keep y 0x0000000000000709 in print at gdb_example.c:4 3 breakpoint keep y 0x0000000000000715 in print at gdb_example.c:5 4 breakpoint keep y 0x0000000000000709 in print at gdb_example.c:4 5 breakpoint keep y 0x0000000000000709 in print at gdb_example.c:4

Stack Frames (Backtrace)

Use backtrace (bt) to show the call stack when execution is paused. Aliases include where and info stack (info s).

Basic

backtrace bt

Show a limited number of frames

backtrace N bt N # show the first N frames backtrace -N bt -N # show the last N frames

Full frames

backtrace full bt full backtrace full N bt full N backtrace full -N bt full -N

Example

(gdb) b 4 Breakpoint 1 at 0x714: file gdb_example.c, line 4. (gdb) r Starting program: /home/zhongyi/code/example/gdb_example In main(): x is 10 and is stored at 0x7fffffffe2fc. ptr points to 0x7fffffffe2fc which holds 10. In print(): xx is 10 and is stored at 0x7fffffffe2cc. ptr points to 0x7fffffffe2fc which holds 10. In sum(): In minus(): Breakpoint 1, minus (a=3, b=2) at gdb_example.c:4 4 int c = a-b; # Show backtrace (gdb) bt #0 minus (a=3, b=2) at gdb_example.c:4 #1 0x00005555555547c0 in print (xx=10, xxptr=0x7fffffffe2fc) at gdb_example.c:17 #2 0x0000555555554841 in main () at gdb_example.c:28 # Show only first 2 frames (gdb) bt 2 #0 minus (a=3, b=2) at gdb_example.c:4 #1 0x00005555555547c0 in print (xx=10, xxptr=0x7fffffffe2fc) at gdb_example.c:17 (More stack frames follow...)

Printing Variables

Use print (p) to display variables or expressions.

print <expression>

(gdb) p x $1 = 10 (gdb) p ptr $2 = (int *) 0x7fffffffe2fc

Registers

Show registers with info reg

(gdb) info reg rax 0xc 12 rbx 0x0 0 rcx 0x7ffff7af2104 140737348837636 rdx 0x7ffff7dcf8c0 140737351841984 rsi 0x555555756260 93824994337376 rdi 0x1 1 rbp 0x7fffffffe310 0x7fffffffe310 rsp 0x7fffffffe2f0 0x7fffffffe2f0 r8 0x7ffff7fe14c0 140737354011840 r9 0x0 0 r10 0x0 0 r11 0x246 582 r12 0x5555555545f0 93824992232944 r13 0x7fffffffe3f0 140737488348144 r14 0x0 0 r15 0x0 0 rip 0x555555554841 0x555555554841 <main+123> eflags 0x202 [ IF ] cs 0x33 51 ss 0x2b 43 ds 0x0 0 es 0x0 0 fs 0x0 0 gs 0x0 0

Print a variable with a specific format:

p/<format> <variable>

Format options:

Memory Display

Use the x command to examine memory.

x/<format> <address>

Examples

(gdb) x $r12 0x5555555545f0 <_start>: xor %ebp,%ebp (gdb) x $r8 0x7ffff7fe14c0: rclb $0xf7,(%rsi,%rdi,8)

Disassembly

Use disassemble to show assembly instructions.

disassemble disassemble <program-counter> disassemble <start-address> <end-address>

Formats: 1 disassembles the current function, 2 disassembles the function containing the program counter, 3 disassembles a specified address range.

(gdb) disassemble Dump of assembler code for function sum: 0x0000555555554722 <+0>: push %rbp 0x0000555555554723 <+1>: mov %rsp,%rbp 0x0000555555554726 <+4>: sub $0x20,%rsp 0x000055555555472a <+8>: mov %edi,-0x14(%rbp) 0x000055555555472d <+11>: mov %esi,-0x18(%rbp) 0x0000555555554730 <+14>: lea 0x1bd(%rip),%rdi # 0x5555555548f4 0x0000555555554737 <+21>: callq 0x5555555545b0 <puts@plt> => 0x000055555555473c <+26>: mov -0x14(%rbp),%edx 0x000055555555473f <+29>: mov -0x18(%rbp),%eax 0x0000555555554742 <+32>: add %edx,%eax 0x0000555555554744 <+34>: mov %eax,-0x4(%rbp) 0x0000555555554747 <+37>: mov -0x4(%rbp),%eax 0x000055555555474a <+40>: leaveq 0x000055555555474b <+41>: retq End of assembler dump.

Stepping

next # execute one source line, skipping over function calls step # step into function calls nexti # next instruction (assembly) stepi # step into instruction (assembly)

Continue

Resume execution.

continue continue <count>

Using a count tells GDB to ignore breakpoints for that many stops. For example, continue 5 will ignore the next 5 breakpoint hits and stop on the 6th.

Watchpoints

Monitor expressions for changes.

watch <expression> # stop when expression value changes awatch <expression> # stop on read or write rwatch <expression> # stop on read

Example

(gdb) watch c Hardware watchpoint 2: c (gdb) c Continuing. Hardware watchpoint 2: c Old value = 21845 New value = 5 sum (a=2, b=3) at gdb_example.c:10 10 return c;

Deleting Breakpoints or Watchpoints

delete <number>

<number> refers to the breakpoint or watchpoint index.

Example

(gdb) info b Num Type Disp Enb Address What 1 breakpoint keep y 0x000055555555473c in sum at gdb_example.c:9 breakpoint already hit 1 time 2 hw watchpoint keep y c breakpoint already hit 1 time (gdb) delete 2 (gdb) info b Num Type Disp Enb Address What 1 breakpoint keep y 0x000055555555473c in sum at gdb_example.c:9 breakpoint already hit 1 time

Change Variable Values

set variable <variable>=<expression>

Example

(gdb) p c $1 = 5 (gdb) set variable c=0 (gdb) p c $2 = 0

Generate Core Dump

Generate a core file of the debugged process to analyze later. From inside GDB:

(gdb) generate-core-file warning: Memory read failed for corefile section, 4096 bytes at 0xffffffffff600000. Saved corefile core.2380

Or from the shell (without stopping the program):

gcore <pid>

Core files are useful for offline analysis or for sending to another machine for debugging.

Conditional Breakpoints

break <location> if <condition>

The breakpoint will pause execution only when the condition evaluates to true.

condition <break-number> condition <break-number> <condition>

The first form removes a condition from a breakpoint; the second sets a condition.

Ignore and Repeat

ignore <break-number> <count>

Ignore the specified breakpoint or watchpoint for the next count hits.

continue <count> step <count> stepi <count> next <count> nexti <count>

finish until until <address>

finish runs until the current function returns. until runs until the current loop or code block completes; it is commonly used to exit loops.

Clear, Disable, Enable Breakpoints

clear clear <function-name> clear <line-number> clear <file>:<line-number> clear <file>:<function-name> delete [breakpoints] <break-number>

clear deletes defined breakpoints.

disable [breakpoints] disable [breakpoints] <break-number> disable display <display-number> disable mem <memory-region>

disable temporarily disables breakpoints. The display and mem variants disable display or memory watch regions defined earlier.

enable enable [breakpoints] <break-number> enable [breakpoints] once <break-number> enable [breakpoints] delete <break-number> enable disable display <display-number> enable mem <memory-region>

once enables a breakpoint for a single hit. delete removes the breakpoint after it is hit and execution is paused.

Breakpoint Commands

Associate a set of commands with a breakpoint. Commands run automatically when the breakpoint is hit.

commands <break-number> <command> ... end

Example

(gdb) b 17 Breakpoint 3 at 0x5555555547b1: file gdb_example.c, line 17. (gdb) command 3 Type commands for definition of "3", one per line. End with a line saying just "end". >p c >end (gdb) r Starting program: /home/zhongyi/code/example/gdb_example -e 'p 1' In main(): x is 10 and is stored at 0x7fffffffe2ec. ptr points to 0x7fffffffe2ec which holds 10. In print(): xx is 10 and is stored at 0x7fffffffe2bc. ptr points to 0x7fffffffe2ec which holds 10. In sum(): Breakpoint 3, print (xx=10, xxptr=0x7fffffffe2ec) at gdb_example.c:17 17 int d = minus(3,2); $1 = 5

Combined with conditional breakpoints, breakpoint commands enable complex automated debugging actions.

Common Commands and Abbreviations

Value History

Values printed with the print command are stored in an internal value history and can be referenced in other expressions.

Example

(gdb) b 16 Breakpoint 1 at 0x79f: file gdb_example.c, line 16. (gdb) b 17 Breakpoint 2 at 0x7b1: file gdb_example.c, line 17. (gdb) b 29 Breakpoint 3 at 0x841: file gdb_example.c, line 29. (gdb) r Starting program: /home/zhongyi/code/example/gdb_example In main(): x is 10 and is stored at 0x7fffffffe2fc. ptr points to 0x7fffffffe2fc which holds 10. In print(): xx is 10 and is stored at 0x7fffffffe2cc. ptr points to 0x7fffffffe2fc which holds 10. Breakpoint 1, print (xx=10, xxptr=0x7fffffffe2fc) at gdb_example.c:16 16 int c = sum(2,3); (gdb) p c $1 = 1431651824 (gdb) c Continuing. In sum(): Breakpoint 2, print (xx=10, xxptr=0x7fffffffe2fc) at gdb_example.c:17 17 int d = minus(3,2); (gdb) p c $2 = 5 (gdb) c Continuing. In minus(): Breakpoint 3, main () at gdb_example.c:29 29 return 0;

Refer to the last printed values using $ notation.

Show recent values with show values (displays the last 10 values by default).

(gdb) show values $1 = 1431651824 $2 = 5 $3 = 10 $4 = 10

You can define your own variables that start with $. They can include letters and digits.

Command History

GDB stores command history. The default history file is ~/.gdb_history. You can control history behavior with these commands:

set history expansion show history expansion

Supports csh-style ! expansion.

set history filename <filename> show history filename

Use the history filename setting to change the file used for saving history. The environment variable GDBHISTFILE can also override the default.

set history save show history save

Enable saving and restoring of command history.

set history size <number> show history size

Set the number of commands saved in history (default 256).

Initialization File (.gdbinit)

On Linux, GDB uses a .gdbinit file. If present, GDB runs it as a command file at startup. Typical order:

$HOME/.gdbinit then command-line options then ./.gdbinit and files specified with -x option are loaded

Define Custom Commands

Use define to create custom commands. Use document to add documentation for a custom command; help <command> shows the documentation.

define <command-name> <command> ... end

document <command-name> <documentation> end

help <command-name>

Example: Define command li

(gdb) define li Type commands for definition of "li". End with a line saying just "end". >x/10i $rbp >end (gdb) document li Type documentation for "li". End with a line saying just "end". >list machine instruction >end (gdb) li 0x7fffffffe310: (bad) 0x7fffffffe311: rex.W push %rbp 0x7fffffffe313: push %rbp 0x7fffffffe314: push %rbp 0x7fffffffe315: push %rbp 0x7fffffffe316: add %al,(%rax) 0x7fffffffe318: xchg %edi,(%rax,%riz,4) 0x7fffffffe31b: idiv %edi 0x7fffffffe31d: jg 0x7fffffffe31f 0x7fffffffe31f: add %al,(%rcx)

Summary

This article provides a concise overview of commonly used GDB commands and scripting features. For deeper coverage, see the GDB manual chapter on Extending GDB.