stk.3

Introduction to Library Functions                          STK(3)

NAME
     stk - data stack storage library

SYNOPSIS
     #include <stk.h>

     Stk_t *stkopen(int flags);
     Stk_t *stkinstall(Stk_t *stack, char *(overflow)(int));
     int stkclose(Stk_t *stack);
     void stklink(Stk_t *stack)

     char *stkalloc(Stk_t *stack, unsigned size);
     char *stkcopy(Stk_t *stack, const char *string);
     char *stkset(Stk_t *stack, char *address, unsigned offset);

     char *stkseek(Stk_t *stack, unsigned offset);
     int stktell(Stk_t *stack);
     char *stkptr(Stk_t *stack, unsigned offset);
     char *stkfreeze(Stk_t *stack, unsigned extra);

DESCRIPTION
     stk is a package of routines designed to  provide  efficient
     stack  oriented  dynamic  storage.  A stack abstraction con-
     sists of an  ordered  list  of  contiguous  memory  regions,
     called  stack  frames,  that  can  hold objects of arbitrary
     size.  A stack is represented by the type Stk_t  defined  in
     header  <stk.h>.  The type Stk_t is compatible with the type
     Sfio_t defined by the sfio(3) library.  At any instant there
     is  one active stack which can be referenced by the constant
     stkstd.  Variable size objects can be added  to  the  active
     stack and programs can reference these objects directly with
     pointers.   In  addition,  the  last  object  on  the  stack
     (referred to here as the current object) can be built incre-
     mentally.  The current object has an associated offset  that
     determines  its  current  size.  While the current object is
     being built incrementally, its location might change so that
     it  is  necessary  to  reference  the  object  with relative
     offsets ranging from zero  to  the  current  offset  of  the
     object.

     There is a preset initial active stack.   To  use  an  addi-
     tional stack, it is necessary to create it and to install it
     as the active stack.  A stack is created with the  stkopen()
     function.   A  flags  argument  of  STK_SMALL indicates that
     unused space on the stack  should  be  freed  whenever  this
     stack  ceases  to  be the active stack. If successful, stko-
     pen() returns a pointer to a stack whose reference count  is
     1.   Otherwise,  stkopen()  returns  a  null  pointer.   The
     stklink() function increases the  reference  count  for  the
     given  stack.  The stkinstall() function makes the specified
     stack the active stack and returns a pointer to the previous

SunOS 5.10                Last change:                          1

Introduction to Library Functions                          STK(3)

     active  stack.   When  the overflow argument is not null, it
     specifies a function that will be called whenever  malloc(3)
     fails while trying to grow the stack.  The overflow function
     will be called with the size that was passed  to  malloc(3).
     The  overflow  function can call exit(3), call longjmp(3) or
     return.  If the overflow function returns, it must return  a
     pointer  to  a memory region of the given size.  The default
     action is to write an error to standard error  and  to  call
     exit(2)  with  a  non-zero exit value.  When stack is a null
     pointer, the active stack is not changed  but  the  overflow
     function  for  the active stack can be changed and a pointer
     to the active stack is returned.   The  stkclose()  function
     decrements  the reference count and frees the memory associ-
     ated with the specified stack when the  reference  count  is
     zero.  The effect of subsequent references to objects on the
     stack are undefined.

     The stkalloc() function returns an aligned pointer to  space
     on  the  active stack that can be used to hold any object of
     the given size.  stkalloc() is similar to  malloc(3)  except
     that  individual  items  returned  by  stkalloc() can not be
     freed.  stkalloc() causes the offset of the  current  object
     to be set to zero.

     The stkcopy() function copies  the  given  string  onto  the
     stack  and  returns  a  pointer  to the string on the stack.
     stkcopy() causes the offset of the current object to be  set
     to zero.

     The stkset() function finds the frame containing  the  given
     address,  frees  all  frames that were created after the one
     containing the given address, and sets the current object to
     the  given address.  The top of the current object is set to
     offset bytes from current object.  If  address  is  not  the
     address of an object on the stack the result is undefined.

     The sfio(3) output functions can be used  to  build  current
     object incrementally.  An object that is built incrementally
     on the stack will always occupy contiguous memory  within  a
     stack frame but until stkfreeze() is called, the location in
     memory for the object can change.  There is a current offset
     associated  with  the  current  object that determines where
     subsequent operations  apply.   Initially,  this  offset  is
     zero,  and  the offset changes as a result of the operations
     you specify.  The stkseek() function is used set the  offset
     for  the  current  object.  The offset argument to stkseek()
     specifies the new offset for the current object.  The  frame
     will  be  extended or moved if offset causes the new current
     offset  to  extend  beyond  the  current  frame.   stkseek()
     returns  a  pointer  to the beginning of the current object.
     The stktell() function  gives  the  offset  of  the  current
     object.

SunOS 5.10                Last change:                          2

Introduction to Library Functions                          STK(3)

     The stkptr() function converts  the  given  offset  for  the
     current  object  into  a  memory address on the stack.  This
     address is only  valid  until  another  stack  operation  is
     given.  The result is not defined if offset exceeds the size
     of the current object.  The stkfreeze() function  terminates
     the current object on the stack and returns a pointer to the
     beginning of this object.  If extra is non-zero, extra bytes
     are  added  to  the  stack before the current object is ter-
     minated.  The first added byte will  contain  zero  and  the
     contents of the remaining bytes are undefined.

HISTORY
     The stk interface was derived from similar routines  in  the
     KornShell  code  that  is  used for building parse trees and
     carrying out expansions.  It provides an efficient mechanism
     for  grouping dynamically allocated objects so that they can
     be freed all at once rather than individually.

AUTHOR
      David Korn

SEE ALSO
     exit(2) longjmp(3) malloc(3) sfio(3)

SunOS 5.10                Last change:                          3

Generated by GNU enscript 1.6.4.