.\" 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.