aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md31
1 files 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