From 058b0118a52061ad57694c01fc8763b22b789c4d Mon Sep 17 00:00:00 2001
From: rsc <devnull@localhost>
Date: Mon, 3 Jan 2005 06:40:20 +0000
Subject: Some man pages.

---
 man/man3/needstack.3 | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 man/man3/needstack.3

(limited to 'man/man3/needstack.3')

diff --git a/man/man3/needstack.3 b/man/man3/needstack.3
new file mode 100644
index 00000000..31588f68
--- /dev/null
+++ b/man/man3/needstack.3
@@ -0,0 +1,69 @@
+.TH NEEDSTACK 3
+.SH NAME
+needstack \- check for execution stack overflow
+.SH SYNOPSIS
+.B
+#include <u.h>
+.PP
+.B
+#include <libc.h>
+.PP
+.B
+int	needstack(int n)
+.SH 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
+.I needstack
+indicates to the thread library that an external routine is about
+to be called that will require
+.I 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
+.B needstack(0)
+can be used to check whether the stack is
+currently overflowed.
+.PP
+.I Needstack
+is defined in
+.B libc.h
+so that library functions used in threaded and non-threaded contexts
+can call it.
+The implementation of
+.I needstack
+in
+.B lib9
+is a no-op.
+.PP
+.I Needstack
+should be thought of as a comment checked at run time,
+like
+.IR assert (3).
+.SH EXAMPLE
+The X Window library implementation of
+.I XLookupString
+allocates some very large buffers on the stack, so
+.B /usr/local/plan9/src/libdraw/x11-itrans.c
+calls
+.B needstack(20*1024)
+before making calls to
+.IR XLookupString .
+If a thread (in this case, the keyboard-reading thread used
+inside the
+.IR draw (3)
+library)
+does not allocate a large enough stack, the problem is diagnosed
+immediately rather than left to corrupt memory.
+.SH SOURCE
+.B /usr/local/plan9/src/lib9/needstack.c
+.br
+.B /usr/local/plan9/src/libthread
+.SH SEE ALSO
+.IR thread (3)
-- 
cgit v1.2.3