3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner\fBstak\fR \- data stack storage library (obsolete: use \fBstk\fR instead)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH SYNOPSIS
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinStak_t *stakcreate(int \fIflags\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinStak_t *stakinstall(Stak_t *\fIstack\fP, char *(\fIoverflow\fP)(int));
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint stakdelete(Stak_t *\fIstack\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinvoid staklink(Stak_t *\fIstack\fP)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar *stakalloc(unsigned \fIsize\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar *stakcopy(const char *\fIstring\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar *stakset(char *\fIaddress\fP, unsigned \fIoffset\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar *stakseek(unsigned \fIoffset\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint stakputc(int \fIc\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint stakputs(const char *\fIstring\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint stakwrite(const char *\fIaddress\fP, unsigned \fIsize\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint staktell(void);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar *stakptr(unsigned \fIoffset\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar *stakfreeze(unsigned \fIextra\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH DESCRIPTION
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5stak\fP is a package of routines designed to provide efficient
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinstack oriented dynamic storage.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA stack abstraction consists of an ordered list of contiguous
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinmemory regions, called stack frames, that can hold objects of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinarbitrary size.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA stack is represented by the type \f5Stak_t\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chindefined in header \f5<stak.h>\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAt any instant there is one active stack.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinVariable size objects can be
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinadded to the active stack
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinand programs can reference these objects directly with pointers.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIn addition, the last object on the stack
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin(referred to here as the current object)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincan be built incrementally.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe current object has an associated offset that determines its
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincurrent size.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinWhile the current object is being built incrementally,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinits location might
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchange so that it is necessary to reference the object with
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinrelative offsets ranging from zero to the current offset of the object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThere is a preset initial active stack.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinTo use an additional stack, it is necessary to create it and to
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chininstall it as the active stack.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA stack is created with the \f5stakcreate\fP() function.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA \fIflags\fP argument of \f5STAK_SMALL\fP indicates that unused
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinspace on the stack should be freed whenever this stack ceases
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto be the active stack.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf successful,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5stakcreate\fP() returns a pointer to a stack whose reference
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincount is 1.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinOtherwise, \f5stakcreate\fP() returns a null pointer.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5staklink\fP() function increases the reference count for the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chingiven \fIstack\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5stakinstall\fP() function
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinmakes the specified \fIstack\fP the active stack and returns a pointer
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto the previous active stack.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinWhen the \fIoverflow\fP argument is not null,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinit specifies a function that will
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbe called whenever \f5malloc\fP(3) fails while trying to grow the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIoverflow\fP function will be called with the size that was passed
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto \f5malloc\fP(3).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIoverflow\fP function can call \f5exit\fP(3), call \f5longjmp\fP(3)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf the \f5overflow\fP function returns,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinit must return a pointer to a memory region of the given size.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe default action is to write an error to standard error and to
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincall \f5exit\fP(2) with a non-zero exit value.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinWhen \fIstack\fP is a null pointer,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe active stack is not changed
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbut the \fIoverflow\fP function for the active stack can be changed
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinand a pointer to the active stack is returned.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5stakdelete\fP() function decrements the reference count and
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfrees the memory associated with
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe specified stack
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwhen the reference count is zero.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe effect of subsequent references to objects
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinon the stack are undefined.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5stakalloc\fP() function returns an aligned pointer to space on the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinactive stack that can be used to hold any object of the given \fIsize\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5stakalloc\fP() is similar to \f5malloc\fP(3) except that individual
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinitems returned by \f5stakalloc\fP() can not be freed.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5stakalloc\fP() causes the offset of the current object to be set to
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5stakcopy\fP() function copies the given string onto the stack
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinand returns a pointer to the \fIstring\fP on the stack.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5stakcopy\fP() causes the offset of the current object to be set to
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5stakset\fP() function finds the frame containing the given
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIaddress\fP, frees all frames that were created after the one containing
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe given \fIaddress\fP, and sets the current object to the given
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIaddress\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe top of the current object is set to \fIoffset\fP bytes from
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincurrent object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fIaddress\fP is not the address of an object on the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinstack the result is undefined.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe remaining functions are used to build the current object incrementally.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAn object that is built incrementally on the stack will
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinalways occupy contiguous memory within a stack frame but
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinuntil \f5stakfreeze\fP() is called,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe location in memory for the object can change.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThere is a current offset associated with the current object that
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chindetermines where subsequent operations apply.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinInitially, this offset is zero, and the offset changes as a result
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinof the operations you specify.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5stakseek\fP() function is used set the offset for the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincurrent object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIoffset\fP argument to \f5stakseek\fP() specifies the new
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinoffset for the current object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe frame will be extended or moved
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinif \f5offset\fP causes the new current offset to extend beyond the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincurrent frame.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5stakseek\fP() returns a pointer to the beginning of the current object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5staktell\fP() function gives the offset of the current object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5stakputc\fP() function adds a given character to the current object
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinon the stack.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe current offset is advanced by 1.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5stakputs\fP() function appends the given \fIstring\fP onto the current
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinobject in the stack and returns the length of the string.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe current offset is advanced by the length of the string.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5stakwrite\fP() function appends the given \fIsize\fP byte memory
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinregion starting at \fIaddress\fP onto the current
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinobject in the stack and advances the current offset by \fIsize\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe current offset is returned.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5stakptr\fP() function converts the given \f5offset\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfor the current object into a memory address on the stack.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis address is only valid until another stack operation is given.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe result is not defined if \fIoffset\fP exceeds the size of the current
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5stakfreeze\fP()
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfunction terminates the current object on the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinstack and returns a pointer to the beginning of this object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fIextra\fP is non-zero, \fIextra\fP bytes are added to the stack
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbefore the current object is terminated. The first added byte will
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincontain zero and the contents of the remaining bytes are undefined.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH HISTORY
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chininterface was derived from similar routines in the KornShell code
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthat is used for building parse trees and carrying out expansions.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt provides an efficient mechanism for grouping dynamically allocated
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinobjects so that they can be freed all at once rather than individually.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin David Korn
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH SEE ALSO
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5exit(2)\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5longjmp(3)\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5malloc(3)\fP