Dive Into Systems

3.2. GDB Commands in Detail

In this section, we list common GDB commands and show some of their features with examples. We first discuss some common keyboard shortcuts that make GDB even easier to use.

3.2.1. Keyboard Shortcuts in GDB

GDB supports command line completion. A user can enter a unique prefix of a command and hit the TAB key, and GDB will try to complete the command line. Also, a unique short abbreviation can be used to issue many common GDB commands. For example, rather than entering the command print x, a user can just enter p x to print out the value of x, or l can be used for the list command, or n for next.

The up and down arrow keys scroll through previous GDB command lines, eliminating the need to retype them each time.

Hitting the RETURN key at the GDB prompt executes the most recent previous command. This is particularly useful when stepping through the execution with a sequence of next or step commands; just press RETURN and GDB executes the next instruction.

3.2.2. Common GDB Commands

We summarize GDB’s most common commands here, grouping them by similar functionality: commands for controlling program execution; commands for evaluating the point in the program’s execution; commands for setting and controlling breakpoints; and commands for printing program state and evaluating expressions. The GDB help command provides information about all GDB commands:

help: Help documentation for topics and GDB commands.

help <topic or command>   Shows help available for topic or command

help breakpoints    Shows help information about breakpoints
help print          Shows help information about print command

Commands for Execution Control Flow

break: Set a breakpoint.

break <func-name>   Set breakpoint at start of function <func-name>
break <line>        Set breakpoint at line number <line>
break <filename:><line>  Set breakpoint at <line> in file <filename>

break main          Set breakpoint at beginning of main
break 13            Set breakpoint at line 13
break gofish.c:34   Set breakpoint at line 34 in gofish.c
break main.c:34     Set breakpoint at line 34 in main.c

Specifying a line in a specific file (as in break gofish.c:34) allows a user to set breakpoints in C programs that span several C source code files (.c files). This feature is particularly useful when the breakpoint being set is not in the same file as the code at the pause point of the program.

run: Start running the debugged program from the beginning.

run <command line arguments>

run             Run with no command line arguments
run 2 40 100    Run with 3 command line arguments: 2, 40, 100

continue (cont): Continue execution from breakpoint
```
continue
```
step (s): Execute the next line(s) of the program’s C source code, stepping into a function if a function call is executed on the line(s).
```
step          Execute next line (stepping into a function)
step <count>  Executes next <count> lines of program code

step 10       Executes the next 10 lines (stepping into functions)
```
In the case of the step <count> command, if a line contains a function call, lines of the called function are counted in the count total of lines to step through. Thus, step <count> may result in the program pausing inside a function that was called from the pause point at which the step <count> command was issued.
next (n): Similar to the step command, but it treats a function call as a single line. In other words, when the next instruction contains a function call, next does not step into the execution of the function but pauses the program after the function call returns (pausing the program at the next line in the code following the one with the function call).
```
next            Execute the next line
next <count>    Executes next <count> instructions
```
until: Execute the program until it reaches the specified source code line number.
```
until <line>    Executes until hit line number <line>
```
quit: Exit GDB
```
quit
```

Commands for Examining the Execution Point and Listing Program Code

list: List program source code.

list                Lists next few lines of program source code
list <line>         Lists lines around line number <line> of program
list <start> <end>  Lists line numbers <start> through <end>
list <func-name>    Lists lines around beginning of function <func-name>

list 30 100         List source code lines 30 to 100

where (backtrace, bt): Show the contents of the stack (the sequence of function calls at the current point in the program’s execution). The where command is helpful for pinpointing the location of a program crash and for examining state at the interface between function calls and returns, such as argument values passed to functions.
```
where
```
frame <frame-num>: Move into the context of stack frame number <frame-num>. As a default, the program is paused in the context of frame 0, the frame at the top of the stack. The frame command can be used to move into the context of another stack frame. Typically, GDB users move into another stack frame to print out the values of parameters and local variables of another function.
```
frame <frame-num>   Sets current stack frame to <frame-num>
info frame          Show state about current stack frame

frame 3             Move into stack frame 3's context (0 is top frame)
```

Commands for Setting and Manipulating Breakpoints

break: Set a breakpoint (there is more explanation about this command in Commands for execution control flow section above.)

break <func-name>   Set a breakpoint at start of a function
break <line>        Set a breakpoint at a line number

break main          Set a breakpoint at start of main
break 12            Set a breakpoint at line 12
break file.c:34     Set a breakpoint at line 34 of file.c

enable, disable, ignore, delete, clear: Enable, disable, ignore for some number of times, or delete one or more breakpoints. The delete command deletes a breakpoint by its number. In contrast, using the clear command deletes a breakpoint at a particular location in the source code.

disable <bnums ...>    Disable one or more breakpoints
enable  <bnums ...>    Enable one or more breakpoints
ignore  <bpnum> <num>  Don't pause at breakpoint <bpnum>
                         the next <num> times it's hit
delete  <bpnum>        Delete breakpoint number <bpnum>
delete                 Deletes all breakpoints
clear <line>           Delete breakpoint at line <line>
clear <func-name>      Delete breakpoint at function <func-name>

info break      List breakpoint info (including breakpoint bnums)
disable 3       Disable breakpoint number 3
ignore  2  5    Ignore the next 5 times breakpoint 2 is hit
enable  3       Enable breakpoint number 3
delete  1       Delete breakpoint number 1
clear   124     Delete breakpoint at source code line 124

condition: Set conditions on breakpoints. A conditional breakpoint is one that only transfers control to GDB when a certain condition is true. It can be used to pause at a breakpoint inside a loop only after some number of iterations (by adding a condition on the loop counter variable), or to pause the program at a breakpoint only when the value of a variable has an interesting value for debugging purposes (avoiding pausing the program at other times).
```
condition <bpnum> <exp>    Sets breakpoint number <bpnum> to break
                           only when expression <exp> is true

break 28            Set breakpoint at line 28 (in function play)
info break          Lists information about all breakpoints
  Num Type           Disp Enb Address    What
   1   breakpoint    keep y   0x080483a3 in play at gofish.c:28

condition 1 (i > 1000)     Set condition on breakpoint 1
```

Commands for Examining and Evaluating Program State and Expressions

print (p): Display the value of an expression. Although GDB users typically print the value of a program variable, GDB will print the value of any C expression (even expressions that are not in the program code). The print command supports printing in different formats and supports operands in different numeric representations.
```
print <exp>     Display the value of expression <exp>

p i             print the value of i
p i+3           print the value of (i+3)
```
To print in different formats:
```
print    <exp>     Print value of the expression as unsigned int
print/x  <exp>     Print value of the expression in hexadecimal
print/t  <exp>     Print value of the expression in binary
print/d  <exp>     Print value of the expression as signed int
print/c  <exp>     Print ASCII value of the expression
print  (int)<exp>  Print value of the expression as unsigned int

print/x 123        Prints  0x7b
print/t 123        Print  1111011
print/d 0x1c       Prints 28
print/c 99         Prints 'c'
print (int)'c'     Prints  99
```
To specify different numeric representations in the expression (the default for numbers is decimal representation):
```
0x prefix for hex: 0x1c
0b prefix for binary: 0b101

print 0b101        Prints 5 (default format is decimal)
print 0b101 + 3    Prints 8
print 0x12  + 2    Prints 20 (hex 12 is 18 in decimal)
print/x 0x12  + 2  Prints 0x14 (decimal 20 in hexadecimal format)
```
Sometimes, expressions may require explicit type casting to inform print how to interpret them. For example, here, recasting an address value to a specific type (int *) is necessary before the address can be dereferenced (otherwise, GDB does not know how to dereference the address):
```
print *(int *)0x8ff4bc10   Print int value at address 0x8ff4bc10
```
When using print to display the value of a dereferenced pointer variable, type casting is not necessary, because GDB knows the type of the pointer variable and knows how to dereference its value. For example, if ptr is declared as an int *, the int value it points to can be displayed like this:
```
print *ptr      Print the int value pointed to by ptr
```
To print out a value stored in a hardware register:
```
print $eax      Print the value stored in the eax register
```
display: Automatically display the value of an expression upon reaching a breakpoint. The expression syntax is the same as the print command.
```
display <exp>   Display value of <exp> at every breakpoint

display i
display array[i]
```

x (examine memory): Display the contents of a memory location. This command is similar to print, but it interprets its argument as an address value that it dereferences to print the value stored at the address.

x <memory address expression>

x  0x5678       Examine the contents of memory location 0x5678
x  ptr          Examine the contents of memory that ptr points to
x  &temp        Can specify the address of a variable
                 (this command is equivalent to: print temp)

Like print, x can display values in different formats (for example, as an int, a char, or a string).

Examine’s Formatting is Sticky

Sticky formatting means that GDB remembers the current format setting, and applies it to subsequent calls to x that do not specify formatting. For example, if the user enters the command x/c, all subsequent executions of x without formatting will use the /c format. As a result, formatting options only need to be explicitly specified with an x command when the user desires changes in the memory address units, repetition, or display format of the most recent call to x.

In general, x takes up to three formatting arguments (x/nfu <memory address>); the order in which they are listed does not matter:

1. n: the repeat count (a positive integer value)

2. f: the display format (s: string, i: instruction, x: hex, d: decimal, t: binary, a: address, …)

3. u: the units format (number of bytes) (b: byte, h: 2 bytes, w: 4 bytes, g: 8 bytes)

Here are some examples (assume s1 = "Hello There" is at memory address 0x40062d):

x/d   ptr       Print value stored at what ptr points to, in decimal
x/a   &ptr      Print value stored at address of ptr, as an address
x/wx  &temp     Print 4-byte value at address of temp, in hexadecimal
x/10dh  0x1234  Print 10 short values starting at address 0x1234, in decimal

x/4c s1         Examine the first 4 chars in s1
    0x40062d   72 'H'  101 'e'  108 'l'  108 'l'

x/s s1         Examine memory location associated with var s1 as a string
    0x40062d   "Hello There"

x/wd s1        Examine the memory location assoc with var s1 as an int
                (because formatting is sticky, need to explicitly set
                units to word (w) after x/s command sets units to byte)
    0x40062d   72

x/8d s1        Examine ASCII values of the first 8 chars of s1
    0x40062d:  72  101 108 108 111 32  84  104

whatis: show the type of an expression.

whatis <exp>       Display the data type of an expression

whatis (x + 3.4)   Displays:  type = double

set: assign/change the value of a program variable, or assign a value to be stored at a specific memory address, or in a specific machine register.
```
set <variable> = <exp>   Sets variable <variable> to expression <exp>

set x = 123 * y   Set var x's value to (123 * y)
```

info: lists information about program state and debugger state. There are a large number of info options for obtaining information about the program’s current execution state and about the debugger. A few examples include:

help info       Shows all the info options
help status     Lists more info and show commands

info locals     Shows local variables in current stack frame
info args       Shows the argument variable of current stack frame
info break      Shows breakpoints
info frame      Shows information about the current stack frame
info registers    Shows register values
info breakpoints  Shows the status of all breakpoints

For more information about these and other GDB commands, see the GDB man page (man gdb) and the GNU Debugger homepage.