needstack.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)