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 typi-
cally 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 allo-
cates some very large buffers on the stack, so
/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 diag-
nosed immediately rather than left to corrupt memory.
SOURCE
/src/lib9/needstack.c
/src/libthread
SEE ALSO
thread(3)