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