Handling Stack Overflows
Learn about differences in reporting crashes from stack-overflows across platforms and Sentry can help.
Application crashes due to stack overflow differ from other crashes from the handler's perspective because the handler relies on the resource that ran out: stack space. Since the handler typically runs on the thread whose stack overflowed, it can no longer use stack variables or call functions. This results in a crashed handler that can't report the initial crash.
How to handle this issue is different from platform to platform, but options boil down to:
- allocating a stack that only the crash handler can use (Linux and Windows)
- running the handler in a separate thread (or process), which will receive a message of the crash asynchronously (macOS)
Independent of whether an application crashed due to stack overflow or not, handlers should make minimal use of the stack because even if there was no stack overflow, the stack amount available to the handler could be limited. This is especially true for users who use the on_crash or before_send hook over which Sentry has no control.
On Linux (and other POSIX systems), users should preallocate everything before their hooks run and only move data into preallocated storage because heap allocations can also fail inside the signal handler (constructing sentry_value_t is okay because we use a safe allocator inside the signal handler). See also What to consider when writing on_crash hooks.
The Windows API provides a thread-stack guarantee interface where users can give a size in bytes reserved for the handler to run in case of a crash. However, this size is subtracted from the thread stack reserve as it is a direct continuation inside the thread stack, not a separate allocation or memory region.
This means the developer must weigh the thread stack reserve against the handler's guarantee during regular operation. Otherwise, the guarantee used for the handler could eat enough stack space to lead to an overflow.
This should not be the case for most threads on Windows, which have a default stack reserve of 1MiB (whereas the required handler guarantee will be only 10s of KiB). However, some threads created by specific runtimes or the kernel (for drivers) might have much smaller stack reserves, where a handler guarantee of 32KiB could already be half or all the stack available to the thread.
In short, while Windows provides a very high-level request interface ("guarantee me x bytes for my handler"), it is not flexible regarding the location of the guaranteed handler stack. As such, you must consider the size of the guarantee in the context of the stack reserve and the actual stack use in a particular thread. The latter is hard to do for threads you do not control.
In addition, you must request the stack guarantee from within the thread for which you want it. You cannot set a guarantee from the outside, which typically limits you to the threads you own.
On Windows, the Native SDK automatically sets a stack guarantee of 64KiB for all threads that start after loading it as a shared library. For static library builds, we only automatically set the stack guarantee for the thread that calls sentry_init().
If you need to set stack guarantees manually, you can use the Win32 API directly or sentry_set_thread_stack_guarantee(), which provides logging and prevents overriding a previously set stack guarantee.
The auto initialization is also defensive in requesting the stack reserve for each thread it runs on and only attempts to set a guarantee if the reserve is at least 10 times larger than the requested default guarantee.
You can parameterize this behavior to suite your use-case:
- you can disable
When you use POSIX signal handlers, you can specify a sigaltstack. This alternative signal stack allows the kernel to continue the handler stack even if the crashed and preempted thread stack runs out.
This relatively low-level interface allows users to specify an arbitrary memory range (from the heap or any mmap a user can access). The upside of allowing the user to determine the size and location offers flexibility compared to the Windows approach because it is independent of the stack usage and size of the crashed thread and allows you to add additional bounds like protected regions around the handler stack. However, it also adds environmental complexity because a badly placed or incorrectly set up memory region could lead to hard-to-identify bugs (consider a handler stack inside the heap, where a handler overflow could lead to an arbitrary heap corruption).
Like Windows, you can only assign a sigaltstack from within the thread, meaning you can only set the handler region for threads you own.
Android automatically configures every thread to use a sigaltstack size of 16KiB (on 32-bit systems) and 32KiB (on 64-bit systems). The Android team recommends not overriding these because configuration inconsistencies with the signal stacks provided by Android can lead to crashes. The inproc backend of the Native SDK used in the Android integration will not define a sigaltstack on Linux/Android if one is already specified. Thus, only the default sigaltstack will be used on Android, and you can be sure that one exists for each thread.
The Mach exception port listener typically blocks in a separate thread until the kernel delivers a Mach exception. Since the listener thread is entirely independent of the thread that crashed, an exception caused by a stack overflow will never affect the available stack for the handler. This is even more true for crashpad on macOS, where the handler doesn't only run in a separate thread but in a separate process.
Be aware that in contrast to mach exception port usage, signal handlers on macOS run on the same thread that caused the signal and thus also need a sigaltstack to handle any crash from a stack overflow.
All backends that use signal handlers as their primary means of handling
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").