From 996473c86e68ca7c735958e24dc984cbb84d9a4f Mon Sep 17 00:00:00 2001
From: Johannes Stoelp <johannes.stoelp@gmail.com>
Date: Mon, 24 Jul 2023 22:49:47 +0200
Subject: gdb: add catchpoint, threading, multi-process, tui

---
 src/tools/gdb.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 74 insertions(+), 4 deletions(-)

(limited to 'src/tools')

diff --git a/src/tools/gdb.md b/src/tools/gdb.md
index 5ae9062..126795e 100644
--- a/src/tools/gdb.md
+++ b/src/tools/gdb.md
@@ -11,6 +11,8 @@
       -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)
 ```
 
 # Interactive usage
@@ -83,13 +85,40 @@
           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
+```markdown
+  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
 ```markdown
   info functions [<regex>]
@@ -99,6 +128,9 @@
   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
@@ -118,6 +150,37 @@
           Create a catchpoint for <signal>.
 ```
 
+## Multi-threading
+```markdown
+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
+```markdown
+  set follow-fork-mode <child | parent>
+          Specify which process to follow when debuggee makes a fork(2)
+          syscall.
+
+  set detach-on-frok <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>.
+```
+
 ## Source file locations
 ```markdown
   dir <path>
@@ -139,10 +202,6 @@
   set disassembly-flavor <intel | att>
           Set the disassembly style "flavor".
 
-  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.
 
@@ -154,6 +213,9 @@
   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).
 
@@ -165,6 +227,14 @@
           off: log to file and tty.
 ```
 
+# Text user interface (TUI)
+```markdown
+  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:
-- 
cgit v1.2.3