| 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/local/plan9/src/libdraw/x11−itrans.c` calls `needstack(20*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/local/plan9/src/lib9/needstack.c /usr/local/plan9/src/libthread`

SEE ALSO

| thread(3)