From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/needstack.html | 98 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 man/man3/needstack.html (limited to 'man/man3/needstack.html') diff --git a/man/man3/needstack.html b/man/man3/needstack.html new file mode 100644 index 00000000..bba5fbe8 --- /dev/null +++ b/man/man3/needstack.html @@ -0,0 +1,98 @@ + +needstack(3) - Plan 9 from User Space + + + + +
+
+
NEEDSTACK(3)NEEDSTACK(3) +
+
+

NAME
+ +
+ + needstack – check for execution stack overflow
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + int    needstack(int n)
+ +
+

DESCRIPTION
+ +
+ + Stack overflow in the thread library leads to bugs that are difficult + to diagnose. The Plan 9 libraries are careful about not allocating + large structures on the stack, so typically four or eight kilobytes + is plenty of stack for a thread. Other libraries are not always + as careful. Calling needstack indicates to the thread library + that an external routine is about to be called that will require + n bytes of stack space. If there is not enough space left on the + stack, the thread library prints an error and terminates the program. + The call needstack(0) can be used to check whether the stack is + currently overflowed. +
+ + Needstack is defined in libc.h so that library functions used + in threaded and non-threaded contexts can call it. The implementation + of needstack in lib9 is a no-op. +
+ + Needstack should be thought of as a comment checked at run time, + like assert(3).
+ +
+

EXAMPLE
+ +
+ + The X Window library implementation of XLookupString allocates + some very large buffers on the stack, so /usr/local/plan9/src/libdraw/x11−itrans.c + calls needstack(20*1024) before making calls to XLookupString. + If a thread (in this case, the keyboard-reading thread used inside + the draw(3) + library) does not allocate a large enough stack, the problem is + diagnosed immediately rather than left to corrupt memory.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/needstack.c
+ /usr/local/plan9/src/libthread
+ +
+

SEE ALSO
+ +
+ + thread(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + -- cgit v1.2.3