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)