![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to sbuf.prot.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / man / mana|
Return to sbuf.prot.3 CVS log | Up to [Research Unix] / researchv10dc / man / mana |
1.1 root 1: . \"ident "%W%"
2: . \"Copyright (c) 1984 AT&T
3: . \"All Rights Reserved
4: . \"THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF AT&T
5: . \"The copyright notice above does not evidence any
6: . \"actual or intended publication of such source code.
7: .TH SBUF.PROT 3I+ "C++ Stream Library" " "
8: .SH NAME
9: streambuf \- interface for derived classes
10: .SH SYNOPSIS
11: .nf
12: .ta1i 2i
13: .ft B
14: #include <iostream.h>
15:
16: typedef long streamoff, streampos;
17: class ios {
18: public:
19: enum seek_dir { beg, cur, end };
20: enum open_mode { in, out, ate, app } ;
21: // \fIand lots of other stuff ... \fP
22: } ;
23:
24: class streambuf {
25: public:
26: streambuf() ;
27: streambuf(char* p, int len, int i=0);
28:
29: void dbp() ;
30: protected:
31: int allocate();
32: char* base();
33: int blen();
34: char* eback();
35: char* ebuf();
36: char* egptr();
37: char* epptr();
38: void gbump(int n);
39: char* gptr();
40: char* pbase();
41: void pbump(int n);
42: char* pptr();
43: void setg(char* eb,char* g, char* eg);
44: void setp(char* p, char* ep);
45: void setb(char* b, char* eb, int a = 0 );
46: int unbuffered();
47: void unbuffered(int);
48:
49: virtual int doallocate();
50: virtual int pbackfail(int c);
51: virtual ~streambuf() ;
52: public:
53: virtual int overflow(int c=EOF);
54: virtual int underflow();
55: virtual streambuf*
56: setbuf(char* p, int len);
57: virtual streampos
58: seekpos(streampos,open_mode=input|output);
59: virtual streampos
60: seekoff(streamoff,seek_dir,open_mode=input|output);
61: virtual int sync();
62: };
63: .fi
64: .ft R
65: .SH DESCRIPTION
66: \f(CWstreambuf\fRs implement the buffer abstraction described in
67: \fIsbuf.pub\fR(3C++). But the \f(CWstreambuf\fR class itself contains
68: only basic members for manipulating the characters and normally
69: a class derived from \f(CWstreambuf\fR will be used. This man page
70: describes the interface needed by programmers who are
71: coding a derived class.
72: Broadly speaking there are two kinds of members described here.
73: The non-virtual functions are provided for manipulating a \fBstreambuf\fR
74: in ways that are appropriate in a derived class.
75: Their descriptions reveal details of the implementation that would
76: be inappropriate in the public interface.
77: The virtual functions permit the derived class to specialize the
78: \fBstreambuf\fR class in ways appropriate to the specific sources
79: and sinks that it is implementing.
80: The descriptions of virtuals explain the obligations of the
81: virtuals of the derived class. If the virtuals behave as specified,
82: the \fBstreambuf\fR will behave as specified in the
83: public interface. However, if the virtuals do not behave as
84: specified, then the \f(CWstreambuf\fR may not behave properly,
85: and an \f(CWiostream\fR (or any other code) that relies on proper
86: behavior of the \f(CWstreambuf\fR may not behave properly either.
87: .PP
88: Assume
89: .br
90: \(em \fBsb\fR is a \f(CWstreambuf*\fR.
91: .br
92: \(em \fBi\fR and \fBn\fR are \f(CWint\fR.
93: .br
94: \(em \fBptr\fR, \fBb\fR, \fBeb\fR, \fBp\fR, \fBep\fR, \fBeb\fR, \fBg\fR,
95: and \fBeg\fR are \f(CWchar*\fR.
96: .br
97: \(em \fBc\fR is an \f(CWint\fR character (positive or \f(CWEOF\fR)).
98: .br
99: \(em \fBpos\fR is a \f(CWstreampos\fR. (See \fIiostream\fR(3C++).)
100: .br
101: \(em \fBoff\fR is a \f(CWstreamoff\fR.
102: .br
103: \(em \fBdir\fR is a \f(CWseekdir\fR.
104: .br
105: \(em \fBmode\fR is a \f(CWopen_mode\fR.
106: .PP
107: Constructors:
108: .TP
109: \fBstreambuf()\fR
110: Constructs
111: an empty buffer corresponding to an empty sequence.
112: .TP
113: \fBstreambuf(b,len,i)\fR
114: Constructs an empty buffer and then sets up the reserve area
115: to be the \fBlen\fR bytes starting at \fBb\fR. (\fBi\fR is present
116: for backward compatibility with the stream package\fR. The effect
117: if it is not 0 is undefined.)
118: .PP
119: The protected members of
120: \f(CWstreambuf\fR
121: present an interface to derived classes organized around
122: three areas (arrays of bytes) managed cooperatively by
123: the base and derived classes.
124: They are the get area, the put area, and the reserve area.
125: The get and the put area are normally disjoint, but they
126: may both overlap the reserve area, whose primary purpose is
127: to be a a resource in which
128: space for the put and get areas can be allocated. The get and
129: the put areas are changed as characters are put into and
130: gotten from the buffer, but the reserve area normally remains
131: fixed.
132: The areas are defined by a collection of \f(CWchar*\fR values.
133: The buffer abstraction is described in terms of pointers that point
134: between characters, but the \f(CWchar*\fR values must point at
135: \f(CWchar\fRs.
136: To establish a correspondence the \f(CWchar*\fR values should be thought
137: of as pointing just before the byte they really point at.
138: .PP
139: Functions to examine the pointers are:
140: .TP
141: \fBptr=sb->base()\fR
142: Returns a pointer to the first byte of the reserve area.
143: Space between \fBsb->base()\fR
144: and \fBsb->ebase()\fR is the reserve area.
145: .TP
146: \fBptr=sb->eback()\fR
147: Returns a pointer to a lower bound on
148: \fBsb->gptr()\fR.
149: Space between \fBsb->eback()\fR and \fBsb->gptr()\fR is available
150: for putback.
151: .TP
152: \fBptr=sb->ebuf()\fR
153: Returns a pointer to the byte after the last byte of the reserve area.
154: .TP
155: \fBptr=sb->egptr()\fR
156: Returns a pointer to the byte after the last byte of the get area.
157: .TP
158: \fBptr=sb->epptr()\fR
159: Returns a pointer to the byte after the last byte of the put area.
160: .TP
161: \fBptr=sb->gptr()\fR
162: Returns a pointer to the first byte of the get area.
163: The available characters are those between \fBsb->gptr()\fR
164: and \fBsb->egptr()\fR. The next character fetched will
165: be \fB*sb->gptr()\fR unless \fBsb->egptr()\fR is less than
166: or equal to \fBsb->gptr()\fR.
167: .TP
168: \fBptr=sb->pbase()\fR
169: Returns a pointer to the put area base.
170: Characters between \fBsb->pbase()\fR and \fBsb->pptr()\fR
171: have been storeded into the buffer and not yet consumed.
172: .TP
173: \fBptr=sb->pptr()\fR
174: Returns a pointer to the first byte of the put area.
175: The space between \fBsb->pptr()\fR
176: and \fBsb->epptr()\fR is the put area and characters will be storeed
177: here.
178: .PP
179: The member functions for setting the pointers:
180: .TP
181: \fBsb->setb(b,eb,i)\fR
182: Sets \fBbase\fR and \fBebase\fR to \fBb\fR and \fBeb\fR respectively.
183: \fBi\fR controls whether the area will be subject to
184: automatic deletion.
185: If \fBi\fR is non zero, then
186: \f(CWdelete\fB b\fR will be done when \fBbase\fR is changed by
187: another call of \fBsetb\fR, or when the destructor is called for
188: \fB*sb\fR.
189: If \fBb\fR and \fBeb\fR
190: are both null then we say that there is no reserve area.
191: If \fBb\fR is non-null, there is a reserve area even if
192: \fBeb\fR is less than \fBb\fR and so the reserve area
193: has zero length.
194: .TP
195: \fBsb->setp(p,ep)\fR
196: Sets \fBpptr\fR to \fBp\fR, \fBpbase\fR to \fBp\fR, and \fBepptr\R
197: to \fBep\fR.
198: .TP
199: \fBsb->setg(eb,g,eg)\fR
200: Sets \fBeback\fR to \fBeb\fR, \fBgptr\fR to \fBg\fR, and \fBegptr\fR
201: to \fBeg\fR.
202: .PP
203: Other non-virtual members:
204: .TP
205: \fBi=sb->allocate()\fR
206: Tries to set up a reserve area.
207: If a reserve area already exists or if \fBsb->unbuffered()\fR
208: is nonzero returns 0 without doing anything.
209: If the attempt to allocate space fails \fBallocate\fR
210: returns \f(CWEOF\fR. Otherwise (allocation succeeds)
211: \fBallocate\fR returns 1. \fBallocate\fR is not called by
212: any member of \f(CWstreambuf\fR except virtuals.
213: .TP
214: \fBi=sb->blen()\fR
215: Returns the current size (in chars) of the current reserve area.
216: .TP
217: \fBdbp()\fR
218: Writes directly on file descriptor 1
219: information in ASCII about the state of the
220: buffer. It is intended for debugging and nothing
221: is specified about the form of the output. It is considered part
222: of the protected interface because the information it prints can
223: only be understood in relation to that interface, but it is a public
224: function so that it can be called anywhere during debugging.
225: .TP
226: \fBsb->gbump(n)\fR
227: Increments \fBgptr\fR by \fBn\fR
228: which may be positive or negative.
229: No checks are made on whether the new
230: value of \fBgptr\fR is in bounds.
231: .TP
232: \fBsb->pbump(n)\fR
233: Increments \fBpptr\fR by \fBn\fR
234: which may be positive or negative.
235: No checks are made on whether the new
236: value of \fBpptr\fR is in bounds.
237: .sp
238: .nf
239: .in -.5i
240: \fBsb->unbuffered(i)\fR
241: \fBi=sb->unbuffered()\fR
242: .in
243: .fi
244: There is a private variable known as \fBsb\fR's buffering state.
245: \fBsb->unbuffered(i)\fR sets the value of this variable
246: to \fBi\fR and \fBsb->unbuffered()\fR returns the current value.
247: This state is independent of the actual
248: allocation of a reserve area. Its primary purpose is to
249: control whether a reserve area is allocated automatically
250: by \fBallocate\fR.
251: .PP
252: Virtual functions must be redefined in
253: derived classes to specialize the behavior of \fBstreambuf\fRs:
254: .TP
255: \fBi=sb->doallocate()\fR
256: Is called when \fBallocate\fR determines
257: that space is needed.
258: \fBdoallocate\fR is required to call \fBsetb\fR to provide a reserve
259: area or to return \f(CWEOF\fR if it cannot. It is only called
260: if \fBsb->unbuffered()\fR is non-zero and \fBsb->base()\fR is non-zero.
261: .TP
262: \fBi=overflow(c)\fR
263: Is called to consume characters. If \fBc\fR is not \f(CWEOF\fR
264: it also must either save \fBc\fR or consume it.
265: Usually it is called when the put area is full and
266: an attempt is being made to store a new character, but
267: it can be called at other times.
268: The normal action is to consume the characters between \fBpbase\fR
269: and \fBpptr\fR, call \fBsetp\fR to establish a new put area, and
270: if \fBc\f(CW!=EOF\fR store it (using \fBsputc\fR).
271: If \fBsb->unbuffered()\fR is non-zero,
272: \fBoverflow\fR is not allowed to call \fBsetp\fR and
273: so must consume \fBn\fR
274: \fBsb->overflow\fR
275: should return \fBEOF\fR to indicate an error; otherwise it should
276: return something else.
277: .TP
278: \fBi=sb->pbackfail(c)
279: Is called when \fBeback\fR equals \fBgptr\fR and an attempt
280: has been made to putback \fBc\fR.
281: If this situation can be dealt with (e.g., by repositioning
282: an external file), \fBpbackfail\fR should return \fBc\fR;
283: otherwise it should return \f(CWEOF\fR.
284: .TP
285: \fBpos=sb->seekoff(off,dir,mode)\fR
286: Repositions the get and/or put pointers (i.e., the abstract
287: get and put pointers, not \fBpptr\fR and \fBgptr\fR). The
288: meanings of \fBoff\fR and \fBdir\fR
289: are discussed in
290: \fIsbuf.pub\fR(3C++).
291: \fBmode\fR specifies whether the put pointer (\fBoutput\fR bit set) or
292: the get pointer (\fBinput\fR bit set) is to be modified. Both bits
293: may be set in which case both pointers should be affected.
294: A class derived from \fBstreambuf\fR is not required to
295: support repositioning. \fBseekoff\fR should return \f(CWEOF\fR if
296: the class does not support repositioning. If the class does
297: support repositioning, \fBseekoff\fR should return the new
298: position or \f(CWEOF\fR on error.
299: .TP
300: \fBpos=sb->seekpos(pos,mode)\fR
301: Repositions the streambuf get and/or put pointer to \fBpos\fR.
302: \fBmode\fR specifies which pointers are affected as for \fBseekoff\fR.
303: Returns \fBpos\fR (the argument) or \f(CWEOF\fR if the class does
304: not support repositioning or an error occurs.
305: .TP
306: \fBsb=sb->setbuf(ptr,len)\fR
307: Offers the array at \fBptr\fR with \fBlen\fR bytes should
308: be used as a reserve
309: area. The normal interpretation is that
310: if \fBptr\fR or \fBlen\fR are zero then this is a request
311: to make the \fBsb\fR unbuffered.
312: The derived class may use this area or not as it chooses.
313: If may accept or ignore the request for unbuffered state as it
314: chooses.
315: \fBsetbuf\fR should return \fBsb\fR if it honors the request.
316: Otherwise it should return 0.
317: .TP
318: \fBi=sb->sync()\fR
319: Is called to give the derived class
320: a chance to
321: look at the state of the areas, and synchronize
322: them with any external representation.
323: Normally \fBsync\fR should
324: consume any characters that have been storeed into the put area,
325: and if possible give back to the source any characters in the get area
326: that have not been fetched. When \fBsync\fR returns there should not
327: be any unconsumed characters, and the get area should be empty.
328: \fBsync\fR should return \fBEOF\fR if some kind of failure occurs.
329: .TP
330: \fBi=sb->underflow()\fR
331: Is called to supply characters for fetching, i.e.,
332: to create a condition in which the get area is not empty.
333: If it is called when there are characters in the get area
334: it should return the first character. If the get area is empty
335: it should create a nonempty get area
336: and return the next character (which it should also
337: leave in the get area).
338: If there are no more characters available
339: \fBunderflow\fR
340: should return \f(CWEOF\fR and leave an empty put area.
341: .PP
342: The default definitions of the virtual functions:
343: .TP
344: \fBi=sb->streambuf::doallocate()\fR
345: Attempts to allocate a reserve area using \f(CWoperator new\fR.
346: .TP
347: \fBi=sb->streambuf::overflow(n)\fR
348: Is compatible
349: with the old stream package, but that behavior is not
350: considered part of the specification of the iostream package.
351: So \fBstreambuf::overflow\fR should be treated as if
352: it had undefined behavior. That is, derived classes should
353: always define it.
354: .TP
355: \fBi=sb->streambuf::pbackfail(n)
356: Returns \f(CWEOF\fR.
357: .TP
358: \fBpos=sb->streambuf::seekpos(pos,mode)\fR
359: Returns \fBsb->seekoff(streamoff(pos),seek_beg,mode)\fR.
360: Thus to define seeking in a derived class, it is frequently
361: only necessary to define
362: \fBseekoff\fR and use the inherited \fBstreambuf::seekpos\fR.
363: .TP
364: \fBpos=sb->streambuf::seekoff(off,dir,mode)\fR
365: Returns \f(CWEOF\fR.
366: .TP
367: \fBsb=sb->streambuf::setbuf(ptr,len)\fR
368: Will honor the request when ever there is no reserve area.
369: .TP
370: \fBi=sb->streambuf::sync()\fR
371: Returns 0 if the get area is empty and there are no unconsumed
372: characters. Otherwise it returns \f(CWEOF\fR.
373: .TP
374: \fBi=sb->streambuf::underflow()\fR
375: Is compatible
376: with the old stream package, but that behavior is not
377: considered part of the specification of the iostream package.
378: So \fBstreambuf::underflow\fR should be treated as if
379: it had undefined behavior. That is, it should always be defined
380: in derived classes.
381: .SH CAVEATS
382: The constructors are public for compatibility with the
383: old stream package.
384: They ought to be protected.
385: .PP
386: The interface for unbuffered actions is awkward.
387: It's hard to write \fBunderflow\fR and \fBoverflow\fR
388: virtuals that behave properly
389: for unbuffered \f(CWstreambuf\fRs without special casing.
390: Also there is no way for the virtuals to react sensibly to
391: multi character gets or puts.
392: .PP
393: Although the public interface to \f(CWstreambuf\fRs
394: deals in characters and bytes,
395: the interface to derived classes deals in \f(CWchar\fRs.
396: Since a decision had to be made on the types of the real data
397: pointers, it seemed easier to reflect that choice in the
398: types of the protected members than to duplicate all
399: the members with both plain and unsigned char versions.
400: But perhaps all these uses of \f(CWchar*\fR ought to have been
401: with a typedef.
402: .PP
403: The implementation contains a variant
404: of \fBsetbuf\fR that accepts a third argument.
405: It is present only for compatibility
406: with the old stream package.
407: .SH SEE ALSO
408: sbuf.pub(3C++)
409: streambuf(3C++)
410: iostream(3C++)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.