![[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.