![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to stak.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10no / cmd / odist / pax / man / man3|
Return to stak.3 CVS log | Up to [Research Unix] / researchv10no / cmd / odist / pax / man / man3 |
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.