From f11c1e8310c995c91dc796ec5332eedaec6ddcce Mon Sep 17 00:00:00 2001 From: Johannes Stoelp Date: Wed, 11 Sep 2024 21:08:38 +0200 Subject: update readme --- README.md | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2e691d1..2df1772 100644 --- a/README.md +++ b/README.md @@ -11,17 +11,33 @@ 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. +- If the program overrides the signal handler, it needs to implement chaining + signal handlers properly. The preload library `libbt.so` is build with the default make target. ``` -make +> make +cc -o libbt.so bt.c -shared -fPIC -static-libgcc -ldl -Wall -Wextra -g ``` -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. +## Concept + +The library is based on the following features. + +- Global signal disposition for `SIGSEGV`. +- *Alternate* signal stacks. + +The signal handler for `SIGSEGV` is directly executed in the thread generating +the *segfault*. This is fine as long as the segfault is generated from anything +other than a *stackoverflow*. To also support this case, the library installs +an *alternate* signal stack with [`sigaltstack(2)`][sigaltstack] for each +thread by wrapping the [`pthread_create(3)`][pthread_create] call. + +Support for threads created with raw [`clone(2)`][clone] calls is not +supported. + +The examples `recurse1.c` and `recurse2.c` demonstrate the handling for +stackoverflows. ## Examples @@ -49,4 +65,7 @@ Alternatively one can run `make run`, to run all examples under `example/`. ## License This project is licensed under the MIT license. +[clone]: https://www.man7.org/linux/man-pages/man2/clone.2.html [ptrace]: https://www.man7.org/linux/man-pages/man2/ptrace.2.html +[sigaltstack]: https://www.man7.org/linux/man-pages/man2/sigaltstack.2.html +[pthread_create]: https://www.man7.org/linux/man-pages/man3/pthread_create.3.html -- cgit v1.2.3