aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Makefile10
-rw-r--r--README.me52
2 files changed, 57 insertions, 5 deletions
diff --git a/Makefile b/Makefile
index be4cf0a..71b1824 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,8 @@
-all: $(patsubst example/%.c, out/%, $(wildcard example/*.c))
-all: $(patsubst example/%.c, run/%, $(wildcard example/*.c))
+libbt.so: bt.c
+ $(CC) -o $@ $^ -shared -fPIC -static-libgcc -ldl $(CFLAGS)
+
+run: $(patsubst example/%.c, out/%, $(wildcard example/*.c))
+run: $(patsubst example/%.c, run/%, $(wildcard example/*.c))
CFLAGS := -Wall -Wextra -g
CFLAGS_recurse1 := -Wno-infinite-recursion
@@ -12,9 +15,6 @@ out/%: example/%.c libbt.so
@mkdir -p out
$(CC) -o $@ $< -rdynamic $(CFLAGS) $(CFLAGS_$*)
-libbt.so: bt.c
- $(CC) -o $@ $^ -shared -fPIC -static-libgcc -ldl $(CFLAGS)
-
clean:
$(RM) -r out
$(RM) libbt.so
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]