1 058b0118 2005-01-03 devnull .TH NEEDSTACK 3
 2 058b0118 2005-01-03 devnull .SH NAME
 3 058b0118 2005-01-03 devnull needstack \- check for execution stack overflow
 4 058b0118 2005-01-03 devnull .SH SYNOPSIS
 5 058b0118 2005-01-03 devnull .B
 6 058b0118 2005-01-03 devnull #include <u.h>
 7 058b0118 2005-01-03 devnull .PP
 8 058b0118 2005-01-03 devnull .B
 9 058b0118 2005-01-03 devnull #include <libc.h>
10 058b0118 2005-01-03 devnull .PP
11 058b0118 2005-01-03 devnull .B
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.
20 058b0118 2005-01-03 devnull Calling
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
24 058b0118 2005-01-03 devnull .I n
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.
29 058b0118 2005-01-03 devnull The call
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.
33 058b0118 2005-01-03 devnull .PP
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
41 058b0118 2005-01-03 devnull in
42 058b0118 2005-01-03 devnull .B lib9
43 058b0118 2005-01-03 devnull is a no-op.
44 058b0118 2005-01-03 devnull .PP
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,
47 058b0118 2005-01-03 devnull like
48 d32deab1 2020-08-16 rsc .MR 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 b546bd6e 2017-07-16 rsc .B \*9/src/cmd/devdraw/x11-itrans.c
54 058b0118 2005-01-03 devnull calls
55 b546bd6e 2017-07-16 rsc .B needstack(64*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 d32deab1 2020-08-16 rsc .MR draw (3)
61 058b0118 2005-01-03 devnull library)
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
66 058b0118 2005-01-03 devnull .br
67 c3674de4 2005-01-11 devnull .B \*9/src/libthread
68 058b0118 2005-01-03 devnull .SH SEE ALSO
69 d32deab1 2020-08-16 rsc .MR thread (3)