gdb(1)

CLI

  gdb [opts] [prg [-c coredump | -p pid]]
+  gdb [opts] --args prg <prg-args>
+    opts:
+      -p <pid>        attach to pid
+      -c <coredump>   use <coredump>
+      -x <file>       execute script <file> before prompt
+      -ex <cmd>       execute command <cmd> before prompt
+      --tty <tty>     set I/O tty for debugee
+      --batch         run in batch mode, exit after processing options (eg used
+                      for scripting)
+      --batch-silent  link --batch, but surpress gdb stdout
+

Interactive usage

Misc

  apropos <regex>
+          Search commands matching regex.
+
+  tty <tty>
+          Set <tty> as tty for debugee.
+          Make sure nobody reads from target tty, easiest is to spawn a shell
+          and run following in target tty:
+          > while true; do sleep 1024; done
+
+  sharedlibrary [<regex>]
+          Load symbols of shared libs loaded by debugee. Optionally use <regex>
+          to filter libs for symbol loading.
+
+  display [/FMT] <expr>
+          Print <expr> every time debugee stops. Eg print next instr, see
+          examples below.
+
+  undisplay [<num>]
+          Delete display expressions either all or one referenced by <num>.
+
+  info display
+          List display expressions.
+
+  info sharedlibrary [<regex>]
+          List shared libraries loaded. Optionally use <regex> to filter.
+

Breakpoints

  break [-qualified] <sym> thread <tnum>
+          Set a breakpoint only for a specific thread.
+          -qualified: Treat <sym> as fully qualified symbol (quiet handy to set
+          breakpoints on C symbols in C++ contexts)
+
+  break <sym> if <cond>
+          Set conditional breakpoint (see examples below).
+
+  delete [<num>]
+          Delete breakpoint either all or one referenced by <num>.
+
+  info break
+          List breakpoints.
+
+  cond <bp> <cond>
+          Make existing breakpoint <bp> conditional with <cond>.
+
+  cond <bp>
+          Remove condition from breakpoint <bp>.
+
+  tbreak
+          Set temporary breakpoint, will be deleted when hit.
+          Same syntax as `break`.
+
+  rbreak <regex>
+          Set breakpoints matching <regex>, where matching internally is done
+          on: .*<regex>.*
+
+  command [<bp_list>]
+          Define commands to run after breakpoint hit. If <bp_list> is not
+          specified attach command to last created breakpoint. Command block
+          terminated with 'end' token.
+
+          <bp_list>: Space separates list, eg 'command 2 5-8' to run command
+          for breakpoints: 2,5,6,7,8.
+
+  save break <file>
+          Save breakpoints to <file>. Can be loaded with the `source` command.
+

Watchpoints

  watch [-location|-l] <expr> [thread <tnum>]
+          Create a watchpoint for <expr>, will break if <expr> is written to.
+          Watchpoints respect scope of variables, -l can be used to watch the
+          memory location instead.
+
+  rwatch ...
+          Sets a read watchpoint, will break if <expr> is read from.
+
+  awatch ...
+          Sets an access watchpoint, will break if <expr> is written to or read
+          from.
+

Catchpoints

  catch load [<regex>]
+          Stop when shared libraries are loaded, optionally specify a <regex>
+          to stop only on matches.
+  catch unload [<regex>]
+          Stop when shared libraries are unloaded, optionally specify a <regex>
+          to stop only on matches.
+
+  catch throw
+          Stop when an exception is thrown.
+  catch rethrow
+          Stop when an exception is rethrown.
+  catch catch
+          Stop when an exception is caught.
+
+  catch fork
+          Stop at calls to fork (also stops at clones, as some systems
+          implement fork via clone).
+
+  catch syscall [<syscall> <syscall> ..]
+          Stop at syscall. If no argument is given, stop at all syscalls.
+          Optionally give a list of syscalls to stop at.
+

Inspection

  info functions [<regex>]
+          List functions matching <regex>. List all functions if no <regex>
+          provided.
+
+  info variables [<regex>]
+          List variables matching <regex>. List all variables if no <regex>
+          provided.
+
+  info register [<reg> <reg> ..]
+          Dump content of all registers or only the specified <reg>ister.
+

Signal handling

  info handle [<signal>]
+          Print how to handle <signal>. If no <signal> specified print for all
+          signals.
+
+  handle <signal> <action>
+          Configure how gdb handles <signal> sent to debugee.
+          <action>:
+            stop/nostop       Catch signal in gdb and break.
+            print/noprint     Print message when gdb catches signal.
+            pass/nopass       Pass signal down to debugee.
+
+  catch signal <signal>
+          Create a catchpoint for <signal>.
+

Multi-threading

info thread
+          List all threads.
+
+thread apply <id> [<id>] <command>
+          Run command on all threads listed by <id> (space separated list).
+          When 'all' is specified as <id> the <command> is run on all threads.
+
+thread name <name>
+          The <name> for the current thread.
+

Multi-process

  set follow-fork-mode <child | parent>
+          Specify which process to follow when debuggee makes a fork(2)
+          syscall.
+
+  set detach-on-fork <on | off>
+          Turn on/off detaching from new child processes (on by default).
+          Turning this off allows to debug multiple processes (inferiors) with
+          one gdb session.
+
+  info inferiors
+          List all processes gdb debugs.
+
+  inferior <id>
+          Switch to inferior with <id>.
+

Scheduling

  set schedule-multiple <on | off>
+          on: Resume all threads of all processes (inferiors) when continuing
+              or stepping.
+          off: (default) Resume only threads of current process (inferior).
+

Shell commands

  shell <shell_cmd>
+          Run the shell_cmd and print the output, can also contain a pipeline.
+
+  pipe <gdb_cmd> | <shell_cmd>
+          Evaluate the gdb_cmd and run the shell_cmd which receives the output
+          of the gdb_cmd via stdin.
+

Source file locations

  dir <path>
+          Add <path> to the beginning of the searh path for source files.
+
+  show dir
+          Show current search path.
+
+  set substitute-path <from> <to>
+          Add substitution rule checked during source file lookup.
+
+  show substitute-path
+          Show current substitution rules.
+

Configuration

  set disassembly-flavor <intel | att>
+          Set the disassembly style "flavor".
+
+  set pagination <on | off>
+          Turn on/off gdb's pagination.
+
+  set breakpoint pending <on | off | auto>
+          on: always set pending breakpoints.
+          off: error when trying to set pending breakpoints.
+          auto: interatively query user to set breakpoint.
+
+  set print pretty <on | off>
+          Turn on/off pertty printing of structures.
+
+  set style enabled <on | off>
+          Turn on/off styling (eg colored output).
+
+  set logging <on | off>
+          Enable output logging to file (default gdb.txt).
+
+  set logging file <fname>
+          Change output log file to <fname>
+
+  set logging redirect <on | off>
+          on: only log to file.
+          off: log to file and tty.
+
+  set logging overwrite <on | off>
+          on: Truncate log file on each run.
+          off: Append to logfile (default).
+
+  set history filename <fname>
+          Change file where to save and restore command history to and from.
+
+  set history <on | off>
+          Enable or disable saving of command history.
+

+
Logging options should be configured before logging is turned on.
+

Text user interface (TUI)

  C-x a     Toggle UI.
+  C-l       Redraw UI (curses UI can be messed up after the debugee prints to
+            stdout/stderr).
+  C-x o     Change focus.
+

User commands (macros)

Gdb allows to create & document user commands as follows:

  define <cmd>
+    # cmds
+  end
+
+  document <cmd>
+    # docu
+  end
+

To get all user commands or documentations one can use:

  help user-defined
+  help <cmd>
+

Hooks

Gdb allows to create two types of command hooks

hook- will be run before <cmd>
hookpost- will be run after <cmd>

  define hook-<cmd>
+    # cmds
+  end
+
+  define hookpost-<cmd>
+    # cmds
+  end
+

Examples

Automatically print next instr

When ever the debugee stops automatically print the memory at the current +instruction pointer ($rip x86) and format as instruction /i.

  # rip - x86
+  display /i $rip
+
+  # step instruction, after the step the next instruction is automatically printed
+  si
+

Conditional breakpoints

Create conditional breakpoints for a function void foo(int i) in the debugee.

  # Create conditional breakpoint
+  b foo if i == 42
+
+  b foo     # would create bp 2
+  # Make existing breakpoint conditional
+  cond 2 i == 7
+

Set breakpoint on all threads except one

Create conditional breakpoint using the $_thread convenience +variable.

  # Create conditional breakpoint on all threads except thread 12.
+  b foo if $_thread != 12
+

Catch SIGSEGV and execute commands

This creates a catchpoint for the SIGSEGV signal and attached the command +to it.

  catch signal SIGSEGV
+  command
+    bt
+    c
+  end
+

Run `backtrace` on thread 1 (batch mode)

  gdb --batch -ex 'thread 1' -ex 'bt' -p <pid>
+

Script gdb for automating debugging sessions

To script gdb add commands into a file and pass it to gdb via -x. +For example create run.gdb:

  set pagination off
+
+  break mmap
+  command
+    info reg rdi rsi rdx
+    bt
+    c
+  end
+
+  #initial drop
+  c
+

This script can be used as:

  gdb --batch -x ./run.gdb -p <pid>
+

Hook to automatically save breakpoints on `quit`

define break-save
+    save breakpoint $arg0.gdb.bp
+end
+define break-load
+    source $arg0.gdb.bp
+end
+
+define hook-quit
+    break-save quit
+end
+

Watchpoint on struct / class member

A symbolic watchpoint defined on a member variable for debugging is only valid +as long as the expression is in scope. Once out of scope the watchpoint gets +deleted.

When debugging some memory corruption we want to keep the watchpoint even the +expression goes out of scope to find the location that overrides the variable +and introduces the corruption.

(gdb) l
+1  struct S { int v; };
+2
+3  void set(struct S* s, int v) {
+4      s->v = v;
+5  }
+6
+7  int main() {
+8      struct S s;
+9      set(&s, 1);
+10     set(&s, 2);
+11     set(&s, 3);
+...
+
+(gdb) s
+set (s=0x7fffffffe594, v=1) at test.c:4
+4    s->v = v;
+
+# Define a new watchpoint on the member of the struct. The expression however
+# is only valid in the current functions scope.
+
+(gdb) watch s->v
+Hardware watchpoint 2: s->v
+
+(gdb) c
+Hardware watchpoint 2: s->v
+Old value = 0
+New value = 1
+set (s=0x7fffffffe594, v=1) at test.c:5
+5   }
+
+# The watchpoint gets deleted as soon as we leave the function scope.
+
+(gdb) c
+Watchpoint 2 deleted because the program has left the block in
+which its expression is valid.
+main () at test.c:10
+10      set(&s, 2);
+
+# Define the watchpoint on the location of the object to watch.
+
+(gdb) watch -l s->v
+
+# This is equivalent to the following.
+
+(gdb) p &s->v
+$1 = (int *) 0x7fffffffe594
+
+# Define a watchpoint to the address of the member variable of the s instance.
+# This of course only makes sense as long as the s instance is not moved in memory.
+
+(gdb) watch *0x7fffffffe594
+Hardware watchpoint 3: *0x7fffffffe594
+
+(gdb) c
+Hardware watchpoint 3: *0x7fffffffe594
+Old value = 1
+New value = 2
+set (s=0x7fffffffe594, v=2) at test.c:5
+5   }
+
+(gdb) c
+Hardware watchpoint 3: *0x7fffffffe594
+Old value = 2
+New value = 3
+set (s=0x7fffffffe594, v=3) at test.c:5
+5   }
+

Shell commands

# Run shell commands.
+
+(gdb) shell zcat /proc/config.gz | grep CONFIG_KVM=
+CONFIG_KVM=m
+
+# Pipe gdb command to shell command.
+
+(gdb) pipe info proc mapping | grep libc
+    0x7ffff7a1a000     0x7ffff7a42000    0x28000        0x0  r--p   /usr/lib/libc.so.6
+    0x7ffff7a42000     0x7ffff7b9d000   0x15b000    0x28000  r-xp   /usr/lib/libc.so.6
+    0x7ffff7b9d000     0x7ffff7bf2000    0x55000   0x183000  r--p   /usr/lib/libc.so.6
+    0x7ffff7bf2000     0x7ffff7bf6000     0x4000   0x1d7000  r--p   /usr/lib/libc.so.6
+    0x7ffff7bf6000     0x7ffff7bf8000     0x2000   0x1db000  rw-p   /usr/lib/libc.so.6
+

Know Bugs

Workaround `command + finish` bug

When using finish inside a command block, commands after finish are not +executed. To workaround that bug one can create a wrapper function which calls +finish.

  define handler
+    bt
+    finish
+    info reg rax
+  end
+
+  command
+    handler
+  end
+

+ +

Notes

gdb(1)

CLI

Interactive usage

Misc

Breakpoints

Watchpoints

Catchpoints

Inspection

Signal handling

Multi-threading

Multi-process

Scheduling

Shell commands

Source file locations

Configuration

Text user interface (TUI)

User commands (macros)

Hooks

Examples

Automatically print next instr

Conditional breakpoints

Set breakpoint on all threads except one

Catch SIGSEGV and execute commands

Run `backtrace` on thread 1 (batch mode)

Script gdb for automating debugging sessions

Hook to automatically save breakpoints on `quit`

Watchpoint on struct / class member

Shell commands

Know Bugs

Workaround `command + finish` bug

Notes

gdbserver(1)

CLI

Example

Wrapper example: Set environment variables just for the debugee

Notes

Debug