usr/src/lib/libast/common/man/stk.3

   1 .fp 5 CW
   2 .TH STK 3
   3 .SH NAME
   4 \fBstk\fR \- data stack storage library
   5 .SH SYNOPSIS
   6 .ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i
   7 .PP
   8 .nf
   9 \f5
  10 #include <stk.h>
  11
  12 Stk_t *stkopen(int \fIflags\fP);
  13 Stk_t *stkinstall(Stk_t *\fIstack\fP, char *(\fIoverflow\fP)(int));
  14 int stkclose(Stk_t *\fIstack\fP);
  15 void stklink(Stk_t *\fIstack\fP)
  16
  17 char *stkalloc(Stk_t *\fIstack\fP, unsigned \fIsize\fP);
  18 char *stkcopy(Stk_t *\fIstack\fP, const char *\fIstring\fP);
  19 char *stkset(Stk_t *\fIstack\fP, char *\fIaddress\fP, unsigned \fIoffset\fP);
  20
  21 char *stkseek(Stk_t *\fIstack\fP, unsigned \fIoffset\fP);
  22 int stktell(Stk_t *\fIstack\fP);
  23 char *stkptr(Stk_t *\fIstack\fP, unsigned \fIoffset\fP);
  24 char *stkfreeze(Stk_t *\fIstack\fP, unsigned \fIextra\fP);
  25 int stkon(Stk *\fIstack\fP, char* \fIaddr\fP)
  26 \fR
  27 .fi
  28 .SH DESCRIPTION
  29 .PP
  30 \f5stk\fP is a package of routines designed to provide efficient
  31 stack oriented dynamic storage.
  32 A stack abstraction consists of an ordered list of contiguous
  33 memory regions, called stack frames, that can hold objects of
  34 arbitrary size.
  35 A stack is represented by the type \f5Stk_t\fP
  36 defined in header \f5<stk.h>\fP.
  37 The type \f5Stk_t\fP is compatible with the type \f5Sfio_t\fP
  38 defined by the \f5sfio\fP(3) library.
  39 At any instant there is one active stack which can be referenced
  40 by the constant \f5stkstd\fP.
  41 Variable size objects can be
  42 added to the active stack
  43 and programs can reference these objects directly with pointers.
  44 In addition, the last object on the stack
  45 (referred to here as the current object)
  46 can be built incrementally.
  47 The current object has an associated offset that determines its
  48 current size.
  49 While the current object is being built incrementally,
  50 its location might
  51 change so that it is necessary to reference the object with
  52 relative offsets ranging from zero to the current offset of the object.
  53 .PP
  54 There is a preset initial active stack.
  55 To use an additional stack, it is necessary to create it and to
  56 install it as the active stack.
  57 A stack is created with the \f5stkopen\fP() function.
  58 A \fIflags\fP argument of \f5STK_SMALL\fP indicates that unused
  59 space on the stack should be freed whenever this stack ceases
  60 to be the active stack.
  61 If successful,
  62 \f5stkopen\fP() returns a pointer to a stack whose reference
  63 count is 1.
  64 Otherwise, \f5stkopen\fP() returns a null pointer.
  65 The \f5stklink\fP() function increases the reference count for the
  66 given \fIstack\fP.
  67 The \f5stkinstall\fP() function
  68 makes the specified \fIstack\fP the active stack and returns a pointer
  69 to the previous active stack.
  70 When the \fIoverflow\fP argument is not null,
  71 it specifies a function that will
  72 be called whenever \f5malloc\fP(3) fails while trying to grow the
  73 stack.
  74 The \fIoverflow\fP function will be called with the size that was passed
  75 to \f5malloc\fP(3).
  76 The \fIoverflow\fP function can call \f5exit\fP(3), call \f5longjmp\fP(3)
  77 or return.
  78 If the \f5overflow\fP function returns,
  79 it must return a pointer to a memory region of the given size.
  80 The default action is to write an error to standard error and to
  81 call \f5exit\fP(2) with a non-zero exit value.
  82 When \fIstack\fP is a null pointer,
  83 the active stack is not changed
  84 but the \fIoverflow\fP function for the active stack can be changed
  85 and a pointer to the active stack is returned.
  86 The \f5stkclose\fP() function decrements the reference count and
  87 frees the memory associated with
  88 the specified stack
  89 when the reference count is zero.
  90 The effect of subsequent references to objects
  91 on the stack are undefined.
  92 .PP
  93 The
  94 \f5stkalloc\fP() function returns an aligned pointer to space on the
  95 active stack that can be used to hold any object of the given \fIsize\fP.
  96 \f5stkalloc\fP() is similar to \f5malloc\fP(3) except that individual
  97 items returned by \f5stkalloc\fP() can not be freed.
  98 \f5stkalloc\fP() causes the offset of the current object to be set to
  99 zero.
 100 .PP
 101 The
 102 \f5stkcopy\fP() function copies the given string onto the stack
 103 and returns a pointer to the \fIstring\fP on the stack.
 104 \f5stkcopy\fP() causes the offset of the current object to be set to
 105 zero.
 106 .PP
 107 The \f5stkset\fP() function finds the frame containing the given
 108 \fIaddress\fP, frees all frames that were created after the one containing
 109 the given \fIaddress\fP, and sets the current object to the given
 110 \fIaddress\fP.
 111 The top of the current object is set to \fIoffset\fP bytes from
 112 current object.
 113 If \fIaddress\fP is not the address of an object on the
 114 stack the result is undefined.
 115 .PP
 116 The \f5sfio\fP(3) output functions can be used to build
 117 current object incrementally.
 118 An object that is built incrementally on the stack will
 119 always occupy contiguous memory within a stack frame but
 120 until \f5stkfreeze\fP() is called,
 121 the location in memory for the object can change.
 122 There is a current offset associated with the current object that
 123 determines where subsequent operations apply.
 124 Initially, this offset is zero, and the offset changes as a result
 125 of the operations you specify.
 126 The \f5stkseek\fP() function is used set the offset for the
 127 current object.
 128 The \fIoffset\fP argument to \f5stkseek\fP() specifies the new
 129 offset for the current object.
 130 The frame will be extended or moved
 131 if \f5offset\fP causes the new current offset to extend beyond the
 132 current frame.
 133 \f5stkseek\fP() returns a pointer to the beginning of the current object.
 134 The \f5stktell\fP() function gives the offset of the current object.
 135 .PP
 136 The \f5stkptr\fP() function converts the given \f5offset\fP
 137 for the current object into a memory address on the stack.
 138 This address is only valid until another stack operation is given.
 139 The result is not defined if \fIoffset\fP exceeds the size of the current
 140 object.
 141 The \f5stkfreeze\fP()
 142 function terminates the current object on the
 143 stack and returns a pointer to the beginning of this object.
 144 If \fIextra\fP is non-zero, \fIextra\fP bytes are added to the stack
 145 before the current object is terminated.  The first added byte will
 146 contain zero and the contents of the remaining bytes are undefined.
 147 .PP
 148 The \f5stkon\fP()
 149 function returns non-zero if the address given by \fIaddr\fP is
 150 on the stack \fIstack\fP and \f50\fP otherwise.
 151 .PP
 152 .SH HISTORY
 153 The
 154 \f5stk\fP
 155 interface was derived from similar routines in the KornShell code
 156 that is used for building parse trees and carrying out expansions.
 157 It provides an efficient mechanism for grouping dynamically allocated
 158 objects so that they can be freed all at once rather than individually.
 159 .SH AUTHOR
 160  David Korn
 161 .SH SEE ALSO
 162 \f5exit(2)\fP
 163 \f5longjmp(3)\fP
 164 \f5malloc(3)\fP
 165 \f5sfio(3)\fP