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