.TH NEEDSTACK 3
.SH NAME
needstack \- check for execution stack overflow
.SH SYNOPSIS
.B
#include <u.h>
.PP
.B
#include <libc.h>
.PP
.B
int	needstack(int n)
.SH 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
.I needstack
indicates to the thread library that an external routine is about
to be called that will require
.I 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
.B needstack(0)
can be used to check whether the stack is
currently overflowed.
.PP
.I Needstack
is defined in
.B libc.h
so that library functions used in threaded and non-threaded contexts
can call it.
The implementation of
.I needstack
in
.B lib9
is a no-op.
.PP
.I Needstack
should be thought of as a comment checked at run time,
like
.IR assert (3).
.SH EXAMPLE
The X Window library implementation of
.I XLookupString
allocates some very large buffers on the stack, so
.B \*9/src/cmd/devdraw/x11-itrans.c
calls
.B needstack(64*1024)
before making calls to
.IR XLookupString .
If a thread (in this case, the keyboard-reading thread used
inside the
.IR draw (3)
library)
does not allocate a large enough stack, the problem is diagnosed
immediately rather than left to corrupt memory.
.SH SOURCE
.B \*9/src/lib9/needstack.c
.br
.B \*9/src/libthread
.SH SEE ALSO
.IR thread (3)