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