STACK(3)

NAME
_assertStack, _beginStackCheck, _endStackCheck, _getStackBottom, _reportStack, __REPORT_STACK - report stack usage

SYNOPSIS
#include <gno/gno.h>

void _assertStack (unsigned int needed, int line, const char *file);
void _beginStackCheck (void);
int _endStackCheck (void);
unsigned int _getStackBottom (void);
void _reportStack (void);
void __REPORT_STACK (void);

DESCRIPTION
The _beginStackCheck and _endStackCheck routines are intended to determine the required stack usage for a program during the development cycle. _beginStackCheck should be called as soon as possible after the program starts. _endStackCheck should be called just prior to program exit. _endStackCheck will return the number of bytes of stack space used by the program. The result can then be used as a lower bound for the argument to occ's -s flag, or the stacksize pragma for ORCA/C.

Since the procedure used by most programs is to call _beginStackCheck and then immediately register with atexit(3) a function which prints the stack usage on exit, this functionality has been provided by _reportStack; just call _reportStack immediately after main and nothing else is required. Alternately, you may also call the macro __REPORT_STACK() which resolves to a call to __reportStack if and only if the macro __STACK_CHECK__ is defined.

The _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.

The _assertStack routine ensures that there are at least needed bytes left unused on the stack. If this is not the case, then _assertStack prints an appropriate error message and calls 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 needed number of bytes is usually determined either through code inspection or empirically (lseg(1) is a good tool for assisting in this determination). Either way, you should probably make needed slightly larger than the value you expect to need.

If file is non-NULL, then _assertStack will also print out the file name and line number as specified. These values are available in any C program as the macros __FILE__ and __LINE__, respectively.

CAVEAT
The _assertStack routine itself uses stack space, especially when printing out error messages. Ensure you allow at least 100 bytes extra to allow for this.

EXAMPLE
The most common way to make use of these routines is to call _reportStack as your first step in 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.
  #include <gno/gno.h>
  void main (int argc, char **argv) {
    __REPORT_STACK();
    ... <program continues> ...
The _assertStack routine is typically used in the following manner:
  #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;
  }

AUTHORS
Phillip Vandry <vandry@cam.org> Devin Reade <gdr@myrias.com>

HISTORY
The _beginStackCheck and _endStackCheck routines first appeared as stand-along object file, under the names begin_stack_check and end_stack_check. They were first incorporated into GNO in v2.0.6.

The _getMinStack and _assertStack routines first appeared in GNO v2.0.6.

SEE ALSO
lseg(1), occ(1), atexit(3), exit(3).
The ORCA/C Reference Manual, Chapter 12.