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