mirror of https://github.com/GnoConsortium/gno.git
187 lines
4.3 KiB
Groff
187 lines
4.3 KiB
Groff
.\" Man page by Devin Reade.
|
|
.\"
|
|
.\" $Id: stack.3,v 1.5 1999/07/03 14:44:55 gdr-ftp Exp $
|
|
.\"
|
|
.TH STACK 3 "26 March 1998" GNO "Library Routines"
|
|
.SH NAME
|
|
.BR _assertStack ,
|
|
.BR _beginStackCheck ,
|
|
.BR _endStackCheck ,
|
|
.BR _getStackBottom ,
|
|
.BR _reportStack ,
|
|
.BR __REPORT_STACK
|
|
\- report stack usage
|
|
.SH SYNOPSIS
|
|
#include <gno/gno.h>
|
|
.sp 1
|
|
void \fB_assertStack\fR (unsigned int \fIneeded\fR, int \fIline\fR,
|
|
const char *\fIfile\fR);
|
|
.br
|
|
void \fB_beginStackCheck\fR (void);
|
|
.br
|
|
int \fB_endStackCheck\fR (void);
|
|
.br
|
|
unsigned int \fB_getStackBottom\fR (void);
|
|
.br
|
|
void \fB_reportStack\fR (void);
|
|
.br
|
|
void \fB__REPORT_STACK\fR (void);
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR _beginStackCheck
|
|
and
|
|
.BR _endStackCheck
|
|
routines are intended to determine the required stack usage
|
|
for a program during the development cycle.
|
|
.BR _beginStackCheck
|
|
should be called as soon as possible after the program starts.
|
|
.BR _endStackCheck
|
|
should be called just prior to program exit.
|
|
.BR _endStackCheck
|
|
will return the number of bytes of stack space used by the program. The
|
|
result can then be used as a
|
|
.I lower
|
|
bound for the argument to
|
|
.BR occ 's
|
|
.BR -s
|
|
flag, or the
|
|
.I stacksize
|
|
pragma for ORCA/C.
|
|
.LP
|
|
Since the procedure used by most programs is to call
|
|
.BR _beginStackCheck
|
|
and then immediately register with
|
|
.BR atexit (3)
|
|
a function which prints the stack usage on exit, this functionality has been
|
|
provided by
|
|
.BR _reportStack ;
|
|
just call
|
|
.BR _reportStack
|
|
immediately after
|
|
.IR main
|
|
and nothing else is required.
|
|
Alternately, you may also call the macro
|
|
.BR __REPORT_STACK()
|
|
which resolves to a call to
|
|
.BR __reportStack
|
|
if and only if the macro
|
|
.BR __STACK_CHECK__
|
|
is defined.
|
|
.LP
|
|
The
|
|
.BR _getStackBottom
|
|
routine returns the lowest direct page address which can legally be used
|
|
for the stack. (The stack on the 65816 grows downward.) This routine is
|
|
used internally in libc and should not normally be needed by an application.
|
|
.LP
|
|
The
|
|
.BR _assertStack
|
|
routine ensures that there are at least
|
|
.I needed
|
|
bytes left unused on the stack. If this is not the case, then
|
|
.BR _assertStack
|
|
prints an appropriate error message and calls
|
|
.BR exit (3)
|
|
with a value of 1.
|
|
This routine is intended for use when you have a function that is
|
|
either directly or indirectly recursive, and you do not want to
|
|
use the ORCA/C stack checking mechanism for every function in
|
|
your source file. The
|
|
.IR needed
|
|
number of bytes is usually determined either through code inspection
|
|
or empirically
|
|
.RB ( lseg (1)
|
|
is a good tool for assisting in this determination). Either way,
|
|
you should probably make
|
|
.IR needed
|
|
slightly larger than the value you expect to need.
|
|
.LP
|
|
If
|
|
.IR file
|
|
is non-NULL, then
|
|
.BR _assertStack
|
|
will also print out the
|
|
.I file
|
|
name and
|
|
.I line
|
|
number as specified. These values are available in any C program
|
|
as the macros
|
|
.BR __FILE__
|
|
and
|
|
.BR __LINE__ ,
|
|
respectively.
|
|
.SH CAVEAT
|
|
The
|
|
.BR _assertStack
|
|
routine itself uses stack space, especially when printing out error
|
|
messages. Ensure you allow at least 100 bytes extra to allow for this.
|
|
.SH EXAMPLE
|
|
The most common way to make use of these routines is to call
|
|
.BR _reportStack
|
|
as your first step in
|
|
.IR main .
|
|
The GNO base sources make use of the macros __STACK_CHECK__ and
|
|
__REPORT_STACK to control whether or not this check is done.
|
|
You may want to use the same macros.
|
|
.nf
|
|
|
|
#include <gno/gno.h>
|
|
|
|
void main (int argc, char **argv) {
|
|
|
|
__REPORT_STACK();
|
|
... <program continues> ...
|
|
|
|
.fi
|
|
The
|
|
.BR _assertStack
|
|
routine is typically used in the following manner:
|
|
.nf
|
|
|
|
#include <gno/gno.h>
|
|
|
|
int recurse (int arg) {
|
|
int i, j;
|
|
|
|
/*
|
|
* The value 350 was determined through code
|
|
* inspection or with the help of lseg(1).
|
|
*/
|
|
_assertStack(350, __LINE__, __FILE__);
|
|
|
|
... <routine continues> ...
|
|
|
|
i = recurse(j);
|
|
|
|
... <routine continues> ...
|
|
return i;
|
|
}
|
|
|
|
.fi
|
|
.SH AUTHORS
|
|
Phillip Vandry <vandry@cam.org>
|
|
Devin Reade <gdr@gno.org>
|
|
.SH HISTORY
|
|
The
|
|
.BR _beginStackCheck
|
|
and
|
|
.BR _endStackCheck
|
|
routines first appeared as stand-along object file, under the names
|
|
.BR begin_stack_check
|
|
and
|
|
.BR end_stack_check .
|
|
They were first incorporated into GNO in v2.0.6.
|
|
.LP
|
|
The
|
|
.BR _getMinStack
|
|
and
|
|
.BR _assertStack
|
|
routines first appeared in GNO v2.0.6.
|
|
.SH "SEE ALSO"
|
|
.BR lseg (1),
|
|
.BR occ (1),
|
|
.BR atexit (3),
|
|
.BR exit (3).
|
|
.br
|
|
The ORCA/C Reference Manual, Chapter 12.
|