.\" Man page by Devin Reade.
.\"
.\" $Id: stack.3,v 1.2 1997/12/08 15:39:11 gdr Exp $
.\"
.TH STACK 3 "11 December 1996" GNO "Library Routines"
.SH NAME
.BR _beginStackCheck ,
.BR _endStackCheck
\- 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);
.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
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
An easy way to use the first two routines is to make use of the 
.BR atexit (3)
function, so that you don't have to determine all the possible exit
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

  #include <stdio.h>
  #include <gno/gno.h>

  #ifdef __STACK_CHECK__
  void cleanup (void) {
    fprintf(stderr,"Stack Usage: %d bytes\n", _endStackCheck());
  }
  #endif

  void main (int argc, char **argv) {

  #ifdef __STACK_CHECK__
    _beginStackCheck();
    atexit(cleanup);
  #endif

    ... <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@myrias.com>
.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.