# 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 needs to implement chaining
  signal handlers properly.

The preload library `libbt.so` is build with the default make target.
```
> make
cc -o libbt.so bt.c -shared -fPIC -static-libgcc -ldl -Wall -Wextra -g
```

## 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

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

[BT:INFO]: installed signal handler
[BT:INFO]: 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.

[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