tneedstack.3 - plan9port - [fork] Plan 9 from user space
 (HTM) git clone git://src.adamsgaard.dk/plan9port
 (DIR) Log
 (DIR) Files
 (DIR) Refs
 (DIR) README
 (DIR) LICENSE
       ---
       tneedstack.3 (1598B)
       ---
            1 .TH NEEDSTACK 3
            2 .SH NAME
            3 needstack \- check for execution stack overflow
            4 .SH SYNOPSIS
            5 .B
            6 #include <u.h>
            7 .PP
            8 .B
            9 #include <libc.h>
           10 .PP
           11 .B
           12 int        needstack(int n)
           13 .SH DESCRIPTION
           14 Stack overflow in the thread library leads to bugs that are
           15 difficult to diagnose.
           16 The Plan 9 libraries are careful about not allocating
           17 large structures on the stack, so typically four or eight kilobytes is plenty of stack
           18 for a thread.
           19 Other libraries are not always as careful.
           20 Calling
           21 .I needstack
           22 indicates to the thread library that an external routine is about
           23 to be called that will require
           24 .I n
           25 bytes of stack space.
           26 If there is not enough space left on the stack,
           27 the thread library prints an error and terminates
           28 the program.
           29 The call
           30 .B needstack(0)
           31 can be used to check whether the stack is
           32 currently overflowed.
           33 .PP
           34 .I Needstack
           35 is defined in
           36 .B libc.h
           37 so that library functions used in threaded and non-threaded contexts
           38 can call it.
           39 The implementation of
           40 .I needstack
           41 in
           42 .B lib9
           43 is a no-op.
           44 .PP
           45 .I Needstack
           46 should be thought of as a comment checked at run time,
           47 like
           48 .MR assert (3) .
           49 .SH EXAMPLE
           50 The X Window library implementation of
           51 .I XLookupString
           52 allocates some very large buffers on the stack, so
           53 .B \*9/src/cmd/devdraw/x11-itrans.c
           54 calls
           55 .B needstack(64*1024)
           56 before making calls to
           57 .IR XLookupString .
           58 If a thread (in this case, the keyboard-reading thread used
           59 inside the
           60 .MR draw (3)
           61 library)
           62 does not allocate a large enough stack, the problem is diagnosed
           63 immediately rather than left to corrupt memory.
           64 .SH SOURCE
           65 .B \*9/src/lib9/needstack.c
           66 .br
           67 .B \*9/src/libthread
           68 .SH SEE ALSO
           69 .MR thread (3)