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)