added mdbook + migrated first chapter as test (gdb)

5 files changed, 166 insertions, 148 deletions

diff --git a/.gitignore b/.gitignore
index 5a1407e..7585238 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1 @@
-tags
-*.nopub
+book
diff --git a/book.toml b/book.toml
new file mode 100644
index 0000000..305776d
--- /dev/null
+++ b/book.toml
@@ -0,0 +1,9 @@
+[book]
+authors = ["johannst"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Notes"
+
+[output.html]
+default-theme = "ayu"
diff --git a/gdb.txt b/gdb.txt
deleted file mode 100644
index f064cb5..0000000
--- a/gdb.txt
+++ /dev/null
@@ -1,146 +0,0 @@
-# gdb
---------------------------------------------------------------------------------
-
-# toc
-------
-  |gdb|
-    |opts|
-    |prompt|
-    |user_commands|
-    |hooks|
-    |flows|
-
-# gdb(1)                                                                   *gdb*
-=========
-  gdb [opts] [exe [coredump | pid]]
-  gdb [opts] --args exe <exe-args>
-    opts:                                                                 *opts*
-      -p <pid>        attach to pid
-      -x <file>       execute script <file> before prompt
-      -ex <cmd>       execute command <cmd> before prompt
-      --tty <tty>     set I/O tty for debugee (see *prompt* for details)
-
-
-    prompt:                                                             *prompt*
-      tty <tty>             set <tty> as tty for debugee.  make sure nobody
-                            reads from target tty, easiest is to spawn a shell
-                            and run
-                            > while true; do sleep 1024; done
-
-      set follow-fork-mode <child | parent>
-                            specify which process to follow on fork(2)
-
-      sharedlibrary [regex]
-                            load symbols of shared lib, if REGEX then only symbols
-                            for matching libs
-
-      break [-qualified] <sym> thread <tnum>
-                            set a breakpoint only on a specific thread
-                            -qualified: sym must be fully qualified (quiet handy
-                            to set breakpoints on C symbols in C++ contexts)
-
-      rbreak <regex>        set breakpoints based on symbols matching regex
-                            <regex> is internally expanded to .*<regex>.*
-                            so 'rbreak foo' matches barfoobar()
-
-      command [bp_list]     define commands to run after breakpoint hit if
-                            BP_LIST not supplied attach command to last
-                            created bp
-
-                            BP_LIST: space separates list, eg 'command 2 5-8'
-                            to run command for bp 2,5,6,7,8
-
-      info functions [regex]
-                            list functions according to REGEX, if REGEX empty,
-                            list all
-
-      info variables [regex]
-                            list variables according to REGEX, if REGEX empty,
-                            list all
-
-      info handle [signal]
-                            list bevahior for SIGNAL, if SIGNAL empty list all signals
-
-      handle signal <action>
-                            configure how gdb handles SIGNAL which is ment for the 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
-                              noignore/ignore   synonyms for
-
-      catch signal <signal>
-                            create a catchpoint for SIGNAL
-
-
-    user commands:                                               *user_commands*
-      define <cmd>                  defines user command <cmd> to be run
-        # cmds                      in prompt or script
-      end
-
-      document <cmd>                define documentation for cmd <cmd>
-        # docu
-      end
-
-      help user-defined             list user defined commands
-      help <cmd>                    list documentation for command <cmd>
-
-
-    hooks:                                                               *hooks*
-      define hook-<cmd>             run commands defined in hook before
-        # cmds                      executing <cmd>
-      end
-
-      define hookpost-<cmd>         run commands defined in hookpost after
-        # cmds                      executing <cmd>
-      end
-
-
-    flows:                                                               *flows*
-      # catch SIGSEGV and execute some actions once it happends
-      - script:
-        catch signal SIGSEGV
-        command
-          bt
-          c
-        end
-
-      # quickly execute gdb command on running process, eg get backtrace from
-      # thread 1
-      - cmd:
-        $> gdb -ex 'thread 1' -ex 'bt' -p <PID>
-
-      # script gdb for automating debugging sessions
-      - script: run.gdb
-        set pagination off
-
-        break mmap
-        command
-        info reg rdi rsi rdx
-        bt
-        c
-        end
-
-        #initial drop
-        c
-
-      - cmd:
-        $> gdb -p <PID> -x ./run.gdb  --batch &> run.log
-
-    # workaround command + finish bug
-    # issue: when using finish in a command block, actions after finish will not
-    # be executed
-    - script:
-      define handler
-      bt
-      finish
-      info reg rax
-      end
-
-      command
-      handler
-      end
-
---------------------------------------------------------------------------------
-vim:ft=help:sts=2:et:tw=80:cc=80:fo+=t
-
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
new file mode 100644
index 0000000..f31e217
--- /dev/null
+++ b/src/SUMMARY.md
@@ -0,0 +1,3 @@
+# Summary
+
+- [gdb](./gdb.md)
diff --git a/src/gdb.md b/src/gdb.md
new file mode 100644
index 0000000..c11a85d
--- /dev/null
+++ b/src/gdb.md
@@ -0,0 +1,153 @@
+# gdb(1)
+
+# CLI
+
+```markdown
+  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
+```
+
+# Interactive usage
+
+```markdown
+  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
+
+  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.
+
+  break [-qualified] <sym> thread <tnum>
+          Set a breakpoint only for a specific thread.
+          -qualified: Tred <sym> as fully qualified symbol (quiet handy to set
+          breakpoints on C symbols in C++ contexts)
+
+  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.
+
+  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 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>.
+```
+
+# User commands (macros)
+
+```markdown
+  define <cmd>
+    # cmds
+  end
+
+  document <cmd>
+    # docu
+  end
+
+  help user-defined             List user defined commands.
+  help <cmd>                    List documentation for command <cmd>.
+```
+
+# Hooks
+
+Gdb allows to create two types of command `hooks` which will be either executed
+before or after a certain command.
+
+```markdown
+  define hook-<cmd>             Run commands defined in hook before
+    # cmds                      executing <cmd>.
+  end
+
+  define hookpost-<cmd>         Run commands defined in hookpost after
+    # cmds                      executing <cmd>.
+  end
+```
+
+# Flows
+
+## Catch SIGSEGV and execute commands on occurrence
+```markdown
+  catch signal SIGSEGV
+  command
+    bt
+    c
+  end
+```
+
+## Run `backtrace` on thread 1 (batch mode)
+```markdown
+  gdb --batch -ex 'thread 1' -ex 'bt' -p <pid>
+```
+
+## Script gdb for automating debugging sessions
+```markdown
+# 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:
+```markdown
+  gdb -p <pid> -x ./run.gdb  --batch &> run.log
+```
+
+## Workaround `command + finish` bug
+When using `finish` action inside a `command` block, actions after `finish` are
+not executed anymore. To workaround that bug one can create a wrapper function
+which calls `finish`.
+```markdown
+  define handler
+  bt
+  finish
+  info reg rax
+  end
+
+  command
+  handler
+  end
+```