1.fp 5 CW 2.TH STAK 3 3.SH NAME 4\fBstak\fR \- data stack storage library (obsolete: use \fBstk\fR instead) 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 <stak.h> 11 12Stak_t *stakcreate(int \fIflags\fP); 13Stak_t *stakinstall(Stak_t *\fIstack\fP, char *(\fIoverflow\fP)(int)); 14int stakdelete(Stak_t *\fIstack\fP); 15void staklink(Stak_t *\fIstack\fP) 16 17char *stakalloc(unsigned \fIsize\fP); 18char *stakcopy(const char *\fIstring\fP); 19char *stakset(char *\fIaddress\fP, unsigned \fIoffset\fP); 20 21char *stakseek(unsigned \fIoffset\fP); 22int stakputc(int \fIc\fP); 23int stakputs(const char *\fIstring\fP); 24int stakwrite(const char *\fIaddress\fP, unsigned \fIsize\fP); 25int staktell(void); 26char *stakptr(unsigned \fIoffset\fP); 27char *stakfreeze(unsigned \fIextra\fP); 28\fR 29.fi 30.SH DESCRIPTION 31.PP 32\f5stak\fP is a package of routines designed to provide efficient 33stack oriented dynamic storage. 34A stack abstraction consists of an ordered list of contiguous 35memory regions, called stack frames, that can hold objects of 36arbitrary size. 37A stack is represented by the type \f5Stak_t\fP 38defined in header \f5<stak.h>\fP. 39At any instant there is one active stack. 40Variable size objects can be 41added to the active stack 42and programs can reference these objects directly with pointers. 43In addition, the last object on the stack 44(referred to here as the current object) 45can be built incrementally. 46The current object has an associated offset that determines its 47current size. 48While the current object is being built incrementally, 49its location might 50change so that it is necessary to reference the object with 51relative offsets ranging from zero to the current offset of the object. 52.PP 53There is a preset initial active stack. 54To use an additional stack, it is necessary to create it and to 55install it as the active stack. 56A stack is created with the \f5stakcreate\fP() function. 57A \fIflags\fP argument of \f5STAK_SMALL\fP indicates that unused 58space on the stack should be freed whenever this stack ceases 59to be the active stack. 60If successful, 61\f5stakcreate\fP() returns a pointer to a stack whose reference 62count is 1. 63Otherwise, \f5stakcreate\fP() returns a null pointer. 64The \f5staklink\fP() function increases the reference count for the 65given \fIstack\fP. 66The \f5stakinstall\fP() function 67makes the specified \fIstack\fP the active stack and returns a pointer 68to the previous active stack. 69When the \fIoverflow\fP argument is not null, 70it specifies a function that will 71be called whenever \f5malloc\fP(3) fails while trying to grow the 72stack. 73The \fIoverflow\fP function will be called with the size that was passed 74to \f5malloc\fP(3). 75The \fIoverflow\fP function can call \f5exit\fP(3), call \f5longjmp\fP(3) 76or return. 77If the \f5overflow\fP function returns, 78it must return a pointer to a memory region of the given size. 79The default action is to write an error to standard error and to 80call \f5exit\fP(2) with a non-zero exit value. 81When \fIstack\fP is a null pointer, 82the active stack is not changed 83but the \fIoverflow\fP function for the active stack can be changed 84and a pointer to the active stack is returned. 85The \f5stakdelete\fP() function decrements the reference count and 86frees the memory associated with 87the specified stack 88when the reference count is zero. 89The effect of subsequent references to objects 90on the stack are undefined. 91.PP 92The 93\f5stakalloc\fP() function returns an aligned pointer to space on the 94active stack that can be used to hold any object of the given \fIsize\fP. 95\f5stakalloc\fP() is similar to \f5malloc\fP(3) except that individual 96items returned by \f5stakalloc\fP() can not be freed. 97\f5stakalloc\fP() causes the offset of the current object to be set to 98zero. 99.PP 100The 101\f5stakcopy\fP() function copies the given string onto the stack 102and returns a pointer to the \fIstring\fP on the stack. 103\f5stakcopy\fP() causes the offset of the current object to be set to 104zero. 105.PP 106The \f5stakset\fP() function finds the frame containing the given 107\fIaddress\fP, frees all frames that were created after the one containing 108the given \fIaddress\fP, and sets the current object to the given 109\fIaddress\fP. 110The top of the current object is set to \fIoffset\fP bytes from 111current object. 112If \fIaddress\fP is not the address of an object on the 113stack the result is undefined. 114.PP 115The remaining functions are used to build the current object incrementally. 116An object that is built incrementally on the stack will 117always occupy contiguous memory within a stack frame but 118until \f5stakfreeze\fP() is called, 119the location in memory for the object can change. 120There is a current offset associated with the current object that 121determines where subsequent operations apply. 122Initially, this offset is zero, and the offset changes as a result 123of the operations you specify. 124The \f5stakseek\fP() function is used set the offset for the 125current object. 126The \fIoffset\fP argument to \f5stakseek\fP() specifies the new 127offset for the current object. 128The frame will be extended or moved 129if \f5offset\fP causes the new current offset to extend beyond the 130current frame. 131\f5stakseek\fP() returns a pointer to the beginning of the current object. 132The \f5staktell\fP() function gives the offset of the current object. 133.PP 134The \f5stakputc\fP() function adds a given character to the current object 135on the stack. 136The current offset is advanced by 1. 137The \f5stakputs\fP() function appends the given \fIstring\fP onto the current 138object in the stack and returns the length of the string. 139The current offset is advanced by the length of the string. 140The \f5stakwrite\fP() function appends the given \fIsize\fP byte memory 141region starting at \fIaddress\fP onto the current 142object in the stack and advances the current offset by \fIsize\fP. 143The current offset is returned. 144.PP 145The \f5stakptr\fP() function converts the given \f5offset\fP 146for the current object into a memory address on the stack. 147This address is only valid until another stack operation is given. 148The result is not defined if \fIoffset\fP exceeds the size of the current 149object. 150The \f5stakfreeze\fP() 151function terminates the current object on the 152stack and returns a pointer to the beginning of this object. 153If \fIextra\fP is non-zero, \fIextra\fP bytes are added to the stack 154before the current object is terminated. The first added byte will 155contain zero and the contents of the remaining bytes are undefined. 156.PP 157.SH HISTORY 158The 159\f5stak\fP 160interface was derived from similar routines in the KornShell code 161that is used for building parse trees and carrying out expansions. 162It provides an efficient mechanism for grouping dynamically allocated 163objects so that they can be freed all at once rather than individually. 164.SH AUTHOR 165 David Korn 166.SH SEE ALSO 167\f5exit(2)\fP 168\f5longjmp(3)\fP 169\f5malloc(3)\fP 170