1 058b0118 2005-01-03 devnull .TH NEEDSTACK 3
3 058b0118 2005-01-03 devnull needstack \- check for execution stack overflow
4 058b0118 2005-01-03 devnull .SH SYNOPSIS
6 058b0118 2005-01-03 devnull #include <u.h>
9 058b0118 2005-01-03 devnull #include <libc.h>
12 058b0118 2005-01-03 devnull int needstack(int n)
13 058b0118 2005-01-03 devnull .SH DESCRIPTION
14 058b0118 2005-01-03 devnull Stack overflow in the thread library leads to bugs that are
15 058b0118 2005-01-03 devnull difficult to diagnose.
16 058b0118 2005-01-03 devnull The Plan 9 libraries are careful about not allocating
17 058b0118 2005-01-03 devnull large structures on the stack, so typically four or eight kilobytes is plenty of stack
18 058b0118 2005-01-03 devnull for a thread.
19 058b0118 2005-01-03 devnull Other libraries are not always as careful.
21 058b0118 2005-01-03 devnull .I needstack
22 058b0118 2005-01-03 devnull indicates to the thread library that an external routine is about
23 058b0118 2005-01-03 devnull to be called that will require
25 058b0118 2005-01-03 devnull bytes of stack space.
26 058b0118 2005-01-03 devnull If there is not enough space left on the stack,
27 058b0118 2005-01-03 devnull the thread library prints an error and terminates
28 058b0118 2005-01-03 devnull the program.
30 058b0118 2005-01-03 devnull .B needstack(0)
31 058b0118 2005-01-03 devnull can be used to check whether the stack is
32 058b0118 2005-01-03 devnull currently overflowed.
34 058b0118 2005-01-03 devnull .I Needstack
35 058b0118 2005-01-03 devnull is defined in
36 058b0118 2005-01-03 devnull .B libc.h
37 058b0118 2005-01-03 devnull so that library functions used in threaded and non-threaded contexts
38 058b0118 2005-01-03 devnull can call it.
39 058b0118 2005-01-03 devnull The implementation of
40 058b0118 2005-01-03 devnull .I needstack
43 058b0118 2005-01-03 devnull is a no-op.
45 058b0118 2005-01-03 devnull .I Needstack
46 058b0118 2005-01-03 devnull should be thought of as a comment checked at run time,
48 058b0118 2005-01-03 devnull .IR assert (3).
49 058b0118 2005-01-03 devnull .SH EXAMPLE
50 058b0118 2005-01-03 devnull The X Window library implementation of
51 058b0118 2005-01-03 devnull .I XLookupString
52 058b0118 2005-01-03 devnull allocates some very large buffers on the stack, so
53 c3674de4 2005-01-11 devnull .B \*9/src/libdraw/x11-itrans.c
55 058b0118 2005-01-03 devnull .B needstack(20*1024)
56 058b0118 2005-01-03 devnull before making calls to
57 058b0118 2005-01-03 devnull .IR XLookupString .
58 058b0118 2005-01-03 devnull If a thread (in this case, the keyboard-reading thread used
59 058b0118 2005-01-03 devnull inside the
60 058b0118 2005-01-03 devnull .IR draw (3)
62 058b0118 2005-01-03 devnull does not allocate a large enough stack, the problem is diagnosed
63 058b0118 2005-01-03 devnull immediately rather than left to corrupt memory.
64 058b0118 2005-01-03 devnull .SH SOURCE
65 c3674de4 2005-01-11 devnull .B \*9/src/lib9/needstack.c
67 c3674de4 2005-01-11 devnull .B \*9/src/libthread
68 058b0118 2005-01-03 devnull .SH SEE ALSO
69 058b0118 2005-01-03 devnull .IR thread (3)