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 /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
/src/lib9/needstack.c
/src/libthread

SEE ALSO
thread(3)