![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to sbuf.pub.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.pub.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.PUB 3I+ "C++ Stream Library" " "
8: .SH NAME
9: streambuf \- public interface of character buffering class
10: .SH SYNOPSIS
11: .ft B
12: .ta1i 2i
13: .nf
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:
27: int in_avail();
28: int out_waiting();
29: int sbumpc();
30: streambuf* setbuf(char* ptr, int len, int count=0);
31: streampos seekpos(streampos,open_mode);
32: streampos seekoff(streamoff,seek_dir,open_mode);
33: int sgetc();
34: int sgetn(char* ptr,int n);
35: int snextc();
36: int sputbackc(char c);
37: int sputc(int c);
38: int sputn(const char* s,int n);
39: void stossc();
40: int sync();
41: }
42: .fi
43: .SH DESCRIPTION
44: The \f(CWstreambuf\fR
45: class supports buffers into which
46: characters can be inserted (put) or from which characters can be
47: fetched (gotten). Abstractly such a buffer is a sequence of
48: characters together with one or
49: two pointers (a get and/or a put pointer)
50: that define
51: the location at which characters are to be inserted or fetched.
52: The pointers should be thought of as pointing between characters
53: rather than at them. This makes it easier to understand the
54: boundary conditions (a pointer before the first character or after
55: the last).
56: Some of the effects of getting and putting are defined
57: by this class but most of the details are left to specialized
58: classes derived from \f(CWstreambuf\fR.
59: .PP
60: Classes derived from \f(CWstreambuf\fR vary in their
61: treatments of the get and put pointers.
62: The simplest are unidirectional buffers which permit only gets or
63: only puts. Such classes serve as pure sources (producers)
64: or sinks (consumers) of characters.
65: Queuelike buffers have a put and a get pointer which
66: move independently
67: of each other. In such buffers characters that are stored are held
68: (i.e., queued)
69: until they are later fetched.
70: Filelike buffers permit both gets and puts but
71: have only a single pointer.
72: (An alternative description is that the get
73: and put pointers are tied together
74: so that when one moves so does the other.)
75: .PP
76: Most \f(CWstreambuf\fR member functions are
77: organized into two phases.
78: As far as possible, operations are performed inline by storing into
79: or fetching
80: from arrays (the get area and the put area).
81: From time to time, virtual functions are called to
82: deal with collections of characters.
83: Generally the user of a \f(CWstreambuf\fR does not have to know
84: anything about these
85: details, but some the public members pass back information
86: about the
87: state of the areas.
88: .PP
89: Assume:
90: .br
91: \(em \fBi\fR, \fBn\fR, and \fBlen\fR are \f(CWint\fR.
92: .br
93: \(em \fBc\fR is an \f(CWint\fR. It always holds a "character"
94: value or \f(CWEOF\fR. A "character" value is always positive
95: even when \f(CWchar\fR is normally sign extended.
96: .br
97: \(em \fBsb\fR and \fBsb1\fR are \f(CWstreambuf*\fR.
98: .br
99: \(em \fBptr\fR is a \f(CWchar*\fR.
100: .br
101: \(em \fBoff\fR is a \f(CWstreamoff\fR.
102: .br
103: \(em \fBpos\fR is a \f(CWstreampos\fR.
104: .br
105: \(em \fBdir\fR is a \f(CWseekdir\fR.
106: .br
107: \(em \fBmode\fR is a \f(CWopen_mode\fR.
108: .PP
109: Public member functions:
110: .TP
111: \fBi=sb->in_avail()\fR
112: Returns the number of characters
113: that are immediately available in the get area for
114: fetching. That many characters may be fetched with
115: a guarantee that no errors will be reported.
116: .TP
117: \fBi=sb->out_waiting()\fR
118: Returns the number of characters in the put area that have not
119: been consumed by virtuals.
120: .TP
121: \fBc=sb->sbumpc()\fR
122: Moves the get pointer forward one character and returns the
123: character moved over.
124: Returns \f(CWEOF\fR if the get pointer is
125: currently at the end of the sequence.
126: .TP
127: \fBpos=sb->seekoff(off,dir,mode)\fR
128: Repositions the get and/or put pointers.
129: \fBmode\fR specifies whether the put pointer (\fBoutput\fR bit set) or
130: the get pointer (\fBinput\fR bit set) is to be modified. Both bits
131: may be set in which case both pointers should be affected.
132: \fBoff\fR is interpreted as a byte offset. (Notice that it is a
133: signed quantity.)
134: The meaning of possible values of \fBdir\fR are
135: .RS
136: .TP
137: \f(CWbeg\fR
138: The beginning of the stream.
139: .TP
140: \f(CWcur\fR
141: The current position.
142: .TP
143: \f(CWend\fR
144: The end of the stream. (End of file.)
145: .RE
146: Not all classes derived from \fBstreambuf\fR
147: support repositioning. \fBseek\fR will return \f(CWEOF\fR if
148: the class does not support repositioning. If the class does
149: support repositioning, \fBseek\fR will return the new
150: position or \f(CWEOF\fR on error.
151: .TP
152: \fBpos=sb->seekpos(pos,mode)\fR
153: Repositions the streambuf get and/or put pointer to \fBpos\fR.
154: \fBmode\fR specifies which pointers are affected as for \fBseekoff\fR.
155: Returns \fBpos\fR (the argument) or \f(CWEOF\fR if the class does
156: not support repositioning or an error occurs.
157: In general a \f(CWstreampos\fR should be treated as a "magic cookie"
158: and no arithmetic should be performed on it.
159: But two particular values have special meaning:
160: .RS
161: .TP
162: \fBstreampos(0)\fR
163: The beginning of the file.
164: .TP
165: \fBstreampos(EOF)\fR
166: Used as an error indication.
167: .RE
168: .TP
169: \fBc=sb->sgetc()\fR
170: Returns the character after the get pointer. Contrary to what most
171: people expect from the name
172: \fIIT DOES NOT MOVE THE GET POINTER\fR. Returns \f(CWEOF\fR if there is
173: no character available.
174: .TP
175: \fBsb1=sb->setbuf(ptr,len,i)
176: Offers the \fBlen\fR
177: bytes starting at \fBptr\fR.
178: as the reserve area.
179: If \fBptr\fR is null or \fBlen\fR is zero or less, then an unbuffered
180: state is requested.
181: Whether the offered area is used, or a request for unbuffered
182: state is honored depends on details of the derived class.
183: \fBsetbuf\fR normally returns \fBsb\fR, but if it does not
184: accept the offer or honor the request, it returns 0.
185: .TP
186: \fBi=sb->sgetn(ptr,n)\fR
187: Fetches the \fBn\fR
188: characters following the get pointer and copies them to the area
189: starting at \fBptr\fR.
190: When there are less than \fBn\fR characters left before the
191: end of the sequence \fBsgetn\fR fetches whatever characters
192: remain.
193: \fBsgetn\fR repositions the get pointer following
194: the fetched characters and
195: returns the number of characters fetched.
196: .TP
197: \fBc=sb->snextc()\fR
198: Moves the get pointer forward one character
199: and returns the character following the new position.
200: It returns \f(CWEOF\fR if the pointer
201: is currently at the end of the sequence or is at the end of
202: the sequence after moving forward.
203: .TP
204: \fBi=sb->sputbackc(c)
205: Moves the get pointer back one character.
206: \fBc\fR must be
207: the current content of the sequence just before the get pointer.
208: The underlying mechanism may
209: simply back up the get pointer or may rearrange its internal
210: data structures so the \fBc\fR is saved. Thus the effect
211: of \fBsputbackc\fR is undefined if \fBc\fR is not the character
212: before the get pointer.
213: \fBputbackc\fR returns \f(CWEOF\fR when it fails.
214: The conditions under which it can fail depend on the details of
215: the derived
216: class.
217: .TP
218: \fBi=sb->sputc(c)
219: Stores \fBc\fR after the put pointer, and moves the
220: put pointer over the stored character. Usually this extends
221: the sequence.
222: It returns \fBEOF\fR when an error occurs. The conditions
223: that can cause errors depend on the derived class.
224: .TP
225: \fBi=sb->sputn(ptr,n)\fR
226: Stores the \fBn\fR
227: characters starting at \fBptr\fR
228: after the put pointer. Moves the put
229: pointer over them.
230: Returns the number of characters stored successfully.
231: Normally this is \fBn\fR, but it may be less when errors occur.
232: .TP
233: \fBsb->stossc()\fR
234: Moves the get pointer forward one character. If the pointer started at the
235: end of the sequence this function has no effect.
236: .TP
237: \fBi=sb->sync()\fR
238: Establishes consistency between the internal data structures and the
239: external source or sink.
240: The details of this function depend on the derived class.
241: Usually this "flushes" any characters that have been stored
242: but not yet consumed, and "gives back" any characters that
243: may have been produced but not yet fetched.
244: .SH CAVEATS
245: \fBsetbuf\fR
246: does not really belong in the public interface.
247: It is there for compatibility with the stream package.
248: .PP
249: Requiring the program to provide
250: the previously fetched character to
251: \f(CWsputback\fR is probably a botch.
252: .SH SEE ALSO
253: iostream(3C++),
254: sbuf.prot(3C++)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.