From f2a7581c71fe5863a527850e4c0e2906f02e4d2d Mon Sep 17 00:00:00 2001
From: johannst <johannes.stoelp@gmail.com>
Date: Wed, 17 Feb 2021 23:45:10 +0100
Subject: gdb: add new notes and split in sub-sections

---
 src/tools/gdb.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 103 insertions(+), 5 deletions(-)

(limited to 'src')

diff --git a/src/tools/gdb.md b/src/tools/gdb.md
index 7a43ca1..2318e0e 100644
--- a/src/tools/gdb.md
+++ b/src/tools/gdb.md
@@ -15,6 +15,7 @@
 
 # Interactive usage
 
+## Misc
 ```markdown
   tty <tty>
           Set <tty> as tty for debugee.
@@ -22,19 +23,44 @@
           and run following in target tty:
           > while true; do sleep 1024; done
 
-  set follow-fork-mode <child | parent>
-          Specify which process to follow when debuggee makes a fork(2)
-          syscall.
-
   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.
+```
+
+## Breakpoints
+```markdown
   break [-qualified] <sym> thread <tnum>
           Set a breakpoint only for a specific thread.
-          -qualified: Tred <sym> as fully qualified symbol (quiet handy to set
+          -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>.
+
+  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>.*
@@ -46,7 +72,10 @@
 
           <bp_list>: Space separates list, eg 'command 2 5-8' to run command
           for breakpoints: 2,5,6,7,8.
+```
 
+## Inspection
+```markdown
   info functions [<regex>]
           List functions matching <regex>. List all functions if no <regex>
           provided.
@@ -54,7 +83,10 @@
   info variables [<regex>]
           List variables matching <regex>. List all variables if no <regex>
           provided.
+```
 
+## Signal handling
+```markdown
   info handle [<signal>]
           Print how to handle <signal>. If no <signal> specified print for all
           signals.
@@ -70,6 +102,50 @@
           Create a catchpoint for <signal>.
 ```
 
+## Source file locations
+```markdown
+  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
+
+```markdown
+  set follow-fork-mode <child | parent>
+          Specify which process to follow when debuggee makes a fork(2)
+          syscall.
+
+  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 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.
+```
+
 # User commands (macros)
 
 Gdb allows to create & document user commands as follows:
@@ -106,6 +182,28 @@ Gdb allows to create two types of command `hooks`
 
 # 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`.
+```markdown
+  # 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.
+```markdown
+  # Create conditional breakpoint
+  b foo if i == 42
+
+  b foo     # would create bp 2
+  # Make existing breakpoint conditional
+  cond 2 if i == 7
+```
+
 ## Catch SIGSEGV and execute commands
 This creates a `catchpoint` for the `SIGSEGV` signal and attached the `command`
 to it.
-- 
cgit v1.2.3