mirror of
https://github.com/GnoConsortium/gno.git
synced 2024-05-29 02:41:28 +00:00
Added documentation for _assertStack and _getMinStack.
This commit is contained in:
parent
6065babc81
commit
be57edaf08
|
@ -1,6 +1,6 @@
|
||||||
.\" Man page by Devin Reade.
|
.\" Man page by Devin Reade.
|
||||||
.\"
|
.\"
|
||||||
.\" $Id: stack.3,v 1.1 1997/02/27 07:32:25 gdr Exp $
|
.\" $Id: stack.3,v 1.2 1997/12/08 15:39:11 gdr Exp $
|
||||||
.\"
|
.\"
|
||||||
.TH STACK 3 "11 December 1996" GNO "Library Routines"
|
.TH STACK 3 "11 December 1996" GNO "Library Routines"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
|
@ -8,16 +8,23 @@
|
||||||
.BR _endStackCheck
|
.BR _endStackCheck
|
||||||
\- report stack usage
|
\- report stack usage
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.nf
|
|
||||||
#include <gno/gno.h>
|
#include <gno/gno.h>
|
||||||
|
.sp 1
|
||||||
void _beginStackCheck(void);
|
void \fB_assertStack\fR (unsigned int \fIneeded\fR, int \fIline\fR,
|
||||||
int _endStackCheck(void);
|
const char *\fIfile\fR);
|
||||||
.nf
|
.br
|
||||||
|
void \fB_beginStackCheck\fR (void);
|
||||||
|
.br
|
||||||
|
int \fB_endStackCheck\fR (void);
|
||||||
|
.br
|
||||||
|
unsigned int \fB_getStackBottom\fR (void);
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
These routines are intended to determine the required stack usage
|
The
|
||||||
|
.BR _beginStackCheck
|
||||||
|
and
|
||||||
|
.BR _endStackCheck
|
||||||
|
routines are intended to determine the required stack usage
|
||||||
for a program during the development cycle.
|
for a program during the development cycle.
|
||||||
.LP
|
|
||||||
.BR _beginStackCheck
|
.BR _beginStackCheck
|
||||||
should be called as soon as possible after the program starts.
|
should be called as soon as possible after the program starts.
|
||||||
.BR _endStackCheck
|
.BR _endStackCheck
|
||||||
|
@ -31,38 +38,131 @@ bound for the argument to
|
||||||
.BR -s
|
.BR -s
|
||||||
flag, or the
|
flag, or the
|
||||||
.I stacksize
|
.I stacksize
|
||||||
pragma for Orca/C.
|
pragma for ORCA/C.
|
||||||
|
.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
|
.SH EXAMPLE
|
||||||
An easy way to use these set of routines is to make use of the
|
An easy way to use the first two routines is to make use of the
|
||||||
.BR atexit (3)
|
.BR atexit (3)
|
||||||
function, so that you don't have to determine all the possible exit
|
function, so that you don't have to determine all the possible exit
|
||||||
points of your program.
|
points of your program. The GNO base sources make use of the
|
||||||
|
macro __STACK_CHECK__ to control whether or not this check is done.
|
||||||
|
You may want to use the same macro.
|
||||||
.nf
|
.nf
|
||||||
|
|
||||||
#include <stdio.h>
|
#include <stdio.h>
|
||||||
#include <gno/gno.h>
|
#include <gno/gno.h>
|
||||||
|
|
||||||
|
#ifdef __STACK_CHECK__
|
||||||
void cleanup (void) {
|
void cleanup (void) {
|
||||||
fprintf(stderr,"Stack Usage: %d bytes\n", _endStackCheck());
|
fprintf(stderr,"Stack Usage: %d bytes\n", _endStackCheck());
|
||||||
}
|
}
|
||||||
|
#endif
|
||||||
|
|
||||||
void main (int argc, char **argv) {
|
void main (int argc, char **argv) {
|
||||||
|
|
||||||
|
#ifdef __STACK_CHECK__
|
||||||
_beginStackCheck();
|
_beginStackCheck();
|
||||||
atexit(cleanup);
|
atexit(cleanup);
|
||||||
|
#endif
|
||||||
|
|
||||||
... <program continues> ...
|
... <program continues> ...
|
||||||
|
|
||||||
.fi
|
.fi
|
||||||
.SH AUTHOR
|
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>
|
Phillip Vandry <vandry@cam.org>
|
||||||
|
Devin Reade <gdr@myrias.com>
|
||||||
.SH HISTORY
|
.SH HISTORY
|
||||||
These routines first appeared as stand-along object file, under the names
|
The
|
||||||
|
.BR _beginStackCheck
|
||||||
|
and
|
||||||
|
.BR _endStackCheck
|
||||||
|
routines first appeared as stand-along object file, under the names
|
||||||
.BR begin_stack_check
|
.BR begin_stack_check
|
||||||
and
|
and
|
||||||
.BR end_stack_check .
|
.BR end_stack_check .
|
||||||
They were first incorporated into GNO in v2.0.6.
|
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"
|
.SH "SEE ALSO"
|
||||||
|
.BR lseg (1),
|
||||||
.BR occ (1),
|
.BR occ (1),
|
||||||
.BR atexit (1),
|
.BR atexit (3),
|
||||||
Orca/C Reference Manual, Chapter 12.
|
.BR exit (3).
|
||||||
|
.br
|
||||||
|
The ORCA/C Reference Manual, Chapter 12.
|
||||||
|
|
Loading…
Reference in New Issue
Block a user