needstack(3) - Plan 9 from User Space

| NEEDSTACK(3) | NEEDSTACK(3)
| NAME
| needstack – check for execution stack overflow
SYNOPSIS
| `#include <u.h>
` `#include <libc.h>
` `int needstack(int n)`
DESCRIPTION
| Stack overflow in the thread library leads to bugs that are difficult to diagnose. The Plan 9 libraries are careful about not allocating large structures on the stack, so typically four or eight kilobytes is plenty of stack for a thread. Other libraries are not always as careful. Calling needstack indicates to the thread library that an external routine is about to be called that will require n bytes of stack space. If there is not enough space left on the stack, the thread library prints an error and terminates the program. The call `needstack(0)` can be used to check whether the stack is currently overflowed.
Needstack is defined in `libc.h` so that library functions used in threaded and non-threaded contexts can call it. The implementation of needstack in `lib9` is a no-op.
Needstack should be thought of as a comment checked at run time, like assert(3).
EXAMPLE
| The X Window library implementation of XLookupString allocates some very large buffers on the stack, so `/usr/lib/plan9/src/cmd/devdraw/x11−itrans.c` calls `needstack(64*1024)` before making calls to XLookupString. If a thread (in this case, the keyboard-reading thread used inside the draw(3) library) does not allocate a large enough stack, the problem is diagnosed immediately rather than left to corrupt memory.
SOURCE
| `/usr/lib/plan9/src/lib9/needstack.c /usr/lib/plan9/src/libthread`
SEE ALSO
| thread(3)