README.md

   1 debuglib - a convenience wrapper around ptrace
   2 ==============================================
   3
   4 this library tries to abstract away arch-specific differences for ptrace(),
   5 and provide a neater, consistent high-level interface.
   6
   7 - provides facilities to set breakpoints,
   8 - execute till breakpoint,
   9 - single-step processes,
  10 - read and write from process memory,
  11 - hook syscalls and read and modify syscall arguments
  12
  13 it was written with the idea of writing a custom ncurses debugger without
  14 having to remote-control gdb. using the provided primitives it is quite
  15 easy to write an asm-level debugger like ollydbg, but for a source-
  16 based debugger like gdb it is required to deal with the different DWARF
  17 formats, which are quite complicated.
  18
  19 the API is unstable at this moment.
  20 there are working examples for a debugger and syscall hooks in the
  21 tests/ directory.
  22
  23 debuglib was designed for use with the
  24 [RcB2](https://github.com/rofl0r/rcb2) build tool, and depends on my
  25 multi-purpose C library [libulz](https://github.com/rofl0r/libulz),
  26 which provides some data structures such as hashmaps and lists.
  27
  28 How to build the filetracer example program
  29 -------------------------------------------
  30
  31         cd /tmp
  32         mkdir debuglib-0000
  33         cd debuglib-0000/
  34         git clone https://github.com/rofl0r/debuglib
  35         git clone https://github.com/rofl0r/libulz lib
  36         git clone https://github.com/rofl0r/rcb2
  37         export PATH=$PATH:/tmp/debuglib-0000/rcb2
  38         ln -s /tmp/debuglib-0000/rcb2/rcb2.py /tmp/debuglib-0000/rcb2/rcb2
  39         cd debuglib/tests
  40         rcb2 filetrace.c
  41
  42 Known bugs:
  43 -----------
  44 there are 2 ways to use the ptrace(2) api: the old method is using
  45 `PTRACE_ATTACH`, this is what the library currently uses.
  46 it has one major problem, which is the inability to properly deal with
  47 `SIGSTOP`/`SIGTSTP` received by a child when tracing.
  48 therefore a new API was designed that uses `PTRACE_SEIZE` instead.
  49 i was unaware of the issue when designing this library and using the new
  50 seize API instead would require a major rewrite, and more costly, re-test
  51 of all the functionality.
  52 fortunately processes sending SIGSTOP to subprocesses occur quite rarely,
  53 so the issue is encountered only in rare cases.
  54 the issue can be reproduced by creating a shell script with the content
  55
  56     msgmerge --update -q /dev/null /dev/null
  57
  58 on debian sid i386 at the time of this writing, and then executing
  59
  60     DEBUG=1 idfake sh foo.sh
  61
  62 using the supplied idfake example program.
  63 This result in the program hanging forever.
  64 the rather well-known program `proot` is victim to the same design issue.
  65 recent versions of `strace` otoh use the new seize API when available.