add readme and change default make target

1 files changed, 52 insertions, 0 deletions

diff --git a/README.me b/README.me
new file mode 100644
index 0000000..f7122ca
--- /dev/null
+++ b/README.me
@@ -0,0 +1,52 @@
+# preload-libbt
+
+`preload-libbt` is a utility library for some very special occasions.
+
+It aims to extract a backtrace when a program *segfaults*, on machines where
+[`ptrace(2)`][ptrace] syscalls are restricted, and hence launching the program
+under *gdb* or attaching wth *gdb* is not possible.
+
+The library must be `LD_PRELOAD`ed, which then installs a signal handler that
+dumps a stacktrace. For it to work the program must adhere to the following
+rules:
+
+- The program must not override the installed signal handler.
+- If the program overrides the signal handler, it properly needs to implement
+signal handler chaining.
+
+The preload library `libbt.so` is build with the default make target.
+```
+make
+```
+
+The library installs *alternative signal stacks* to be able to do its work even
+when the program *segfaults* due to a *stackoverflow*. This is demonstrated by
+the `example/recurse*.c` examples.
+
+## Examples
+
+The following gives an example and shows how a stacktrace dump looks like.
+```
+cc -o libbt.so bt.c -shared -fPIC -ldl
+cc -o raise1 example/raise1.c -rdynamic
+LD_PRELOAD=./libbt.so ./raise1
+
+[INFO:BT]: installed signal handler
+[INFO:BT]: caught signal 11
+# 0 [  0x7f53b9e203f4] /usr/lib/libc.so.6+0x963f4
+# 1 [  0x7f53b9dc7120] gsignal+0x20 /usr/lib/libc.so.6+0x3d100
+# 2 [  0x55748166c147] foo+0xe raise1+0x1139
+# 3 [  0x55748166c158] bar+0xe raise1+0x114a
+# 4 [  0x55748166c169] qux+0xe raise1+0x115b
+# 5 [  0x55748166c17a] main+0xe raise1+0x116c
+# 6 [  0x7f53b9dafe08] /usr/lib/libc.so.6+0x25e08
+# 7 [  0x7f53b9dafecc] __libc_start_main+0x8c /usr/lib/libc.so.6+0x25e40
+# 8 [  0x55748166c065] _start+0x25 raise1+0x1040
+```
+
+Alternatively one can run `make run`, to run all examples under `example/`.
+
+## License
+This project is licensed under the MIT license.
+
+[https://www.man7.org/linux/man-pages/man2/ptrace.2.html]