Return to stak.3 CVS log

Up to [Research Unix] / researchv10no / cmd / odist / pax / man / man3

Annotation of researchv10no/cmd/odist/pax/man/man3/stak.3, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.