From 54b31f49a6eb2ddca6eb06728db2062b2b13b5b5 Mon Sep 17 00:00:00 2001 From: Johannes Stoelp Date: Mon, 9 Sep 2024 23:40:06 +0200 Subject: fix readme file name --- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.me | 52 ---------------------------------------------------- 2 files changed, 52 insertions(+), 52 deletions(-) create mode 100644 README.md delete mode 100644 README.me diff --git a/README.md b/README.md new file mode 100644 index 0000000..f7122ca --- /dev/null +++ b/README.md @@ -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] diff --git a/README.me b/README.me deleted file mode 100644 index f7122ca..0000000 --- a/README.me +++ /dev/null @@ -1,52 +0,0 @@ -# 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] -- cgit v1.2.3