10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
70 lines
1.6 KiB
Groff
70 lines
1.6 KiB
Groff
.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
|
|
.MR assert 3 .
|
|
.SH EXAMPLE
|
|
The X Window library implementation of
|
|
.I XLookupString
|
|
allocates some very large buffers on the stack, so
|
|
.B \*9/src/cmd/devdraw/x11-itrans.c
|
|
calls
|
|
.B needstack(64*1024)
|
|
before making calls to
|
|
.IR XLookupString .
|
|
If a thread (in this case, the keyboard-reading thread used
|
|
inside the
|
|
.MR draw 3
|
|
library)
|
|
does not allocate a large enough stack, the problem is diagnosed
|
|
immediately rather than left to corrupt memory.
|
|
.SH SOURCE
|
|
.B \*9/src/lib9/needstack.c
|
|
.br
|
|
.B \*9/src/libthread
|
|
.SH SEE ALSO
|
|
.MR thread 3
|