.\" '\" tep .\" to invoke 'tbl', 'eqn', 'pic' in the proper order .\" .\" @(#)sbufpub.3 1.1 93/04/27 SMI; .\" .TH SBUFPUB 3CC4 "18 June 1998" .\" .SH NAME sbufpub \- public interface of the stream buffer base class .SH SYNOPSIS .LP .nf .ft B #include .sp .5v typedef long streampos; typedef long streamoff; class ios : virtual public unsafe_ios, public stream_MT { public: enum open_mode { in = 0x01, // open for reading out = 0x02, // open for writing ate = 0x04, // seek to eof upon original open app = 0x08, // append mode: all additions at eof trunc = 0x10, // truncate file if already exists nocreate = 0x20, // open fails if file doesn't exist noreplace= 0x40 // open fails if file already exists }; // stream seek direction enum seek_dir { beg=0, cur=1, end=2 }; // \fIsee \fBios\fR(3CC4)\fI for remainder ...\fB } ; class streambuf : public stream_MT { public : int in_avail(); int out_waiting(); int sbumpc(); streambuf* setbuf(char* ptr, int len); streampos seekpos(streampos, int =ios::in|ios::out); streampos seekoff(streamoff, seek_dir, int =ios::in|ios::out); int sgetc(); int sgetn(char* ptr, int n); int snextc(); int sputbackc(char); int sputc(int c); int sputn(const char* s, int n); void stossc(); virtual int sync(); int in_avail_unlocked(); int out_waiting_unlocked(); int sbumpc_unlocked(); int sgetc_unlocked(); int sgetn_unlocked(char* ptr, int n); int snextc_unlocked(); int sputbackc_unlocked(char); int sputc_unlocked(int c); int sputn_unlocked(const char* s, int n); void stossc_unlocked(); }; .ft R .fi .\" .SH DESCRIPTION .LP The .B streambuf class defines the basic buffer-class functionality from which actual buffer classes are derived. This public interface represents the functions which any stream class might need to call upon to perform its buffer-related functions. No object of type .Bstreambuf is expected to be created. Rather, buffer objects must be of a class type derived from .B streambuf. See .B sbufprot (3CC4) for a discussion of the protected interface necessary for such derivations. .SS ENVIRONMENT .LP To make streambuf multi-threaded safe (MT safe), that is, able to work correctly in a multi-threaded environment, locks have been used in each public member function. An alternative set of public member functions without locks has been introduced for use in single threaded applications where performance is critical. These member functions share the same name as the original function with the addition of the suffix: _unlocked. Other than being MT unsafe these member functions have identical functionality. .LP Class \fBstreambuf\fR supports an abstract buffer class. It consists logically of a sequence of characters and one or two pointers defining the location where the next character will be stored and/or fetched. A buffer class intended only for input (or output) will have only the \fIget\fR (or \fIput\fR) pointer. A buffer class intended for both input and output will have both pointers. .LP The get and put pointers should be understood as pointing \fIbetween\fR characters in the sequence. The next character to be fetched from an input buffer is the one just after the get pointer. The next character placed into an output stream will be stored just after the put pointer. When at the beginning of the sequence, a pointer points just before the first character; at the end of the sequence it points just after the last character. .LP There can be different kinds of buffers (also called reserve areas) with different strategies, due to different underlying devices. \fIQueue-like\fR buffers, such as \fBstrstreambuf\fR (see \fBssbuf\fR(3CC4)), have independent get and put pointers. The \fBstrstreambuf\fR is an in-memory array of characters and supports stores and fetches at arbitrary locations. \fIFile-like\fR buffers, such as \fBfilebuf\fR (see \fBfilebuf\fR(3CC4)), may permit both get and put operations, but there is effectively only one pointer; the next get \fIor\fR put will always be at the current location. (In practice there may be two pointers, but they always point to the same place.) .LP The \fBstreambuf\fR uses an array of characters as the buffer, and calls upon virtual functions to fill an empty input buffer or to flush a full output buffer. (See \fBsbufprot\fR(3CC4) for details.) The storing, fetching, and pointer manipulation functions are generally inline for maximum efficiency. These are described below. .\" .SS "Input functions" .TP .B "int c = sbuf.sgetc()" This function returns the character after the get pointer, or \fBEOF\fR if the get pointer is at the end of the sequence. Despite its name, this function does NOT move the get pointer. .TP .B "int c = sbuf.snextc()" This function moves the get pointer forward one position, then returns the character after the get pointer's new position. If the get pointer is at the end of the sequence before or after the call to this function (no character is available), this function returns \fBEOF\fR. Example: Suppose the input buffer looks like this: .ti +.5i .BR abc | def .br where `|' marks the position of the get pointer. This function will advance the get pointer and return `e'. .TP .B "int c = sbuf.sbumpc()" This function should probably have been called ``sgetc''. It moves the get pointer forward one position and returns the character it moved past. If the get pointer is currently at the end of the sequence, this function returns \fBEOF\fR. .TP .B "sbuf.stossc()" This function moves the get pointer forward one position; it returns nothing. The combination of \fBsgetc\fR and \fBstossc\fR can be used to implement a scanner without using putback, since \fBsgetc\fR provides lookahead. .TP .B "int i = sbuf.sgetn(ptr, len)" This function gets the next \fBlen\fR characters following the get pointer, copying them to the \fBchar\fR array pointed to by \fBptr\fR; it advances the get pointer past the last character fetched. If fewer than \fBlen\fR characters are left, it gets as many as are available. It returns the number of characters fetched. .TP .B "int c = sbuf.sputbackc(c)" This function attempts to move the get pointer back one character and put \fBc\fR at the new location. Depending on the underlying buffer mechanism, it may not be possible to move the pointer back, or it may not be possible to store \fBc\fR at that location. Therefore, the effect of the function is uncertain if \fBc\fR is not the same as the character just ahead of the get pointer. Again depending on the underlying mechanism, this function might require resynchronization with an external device. This function returns \fBEOF\fR if the attempted putback fails. What constitutes failure depends on the details of the actual buffer class, but would probably include already being at the beginning of a device. .TP .B "int i = sbuf.in_avail()" This function returns the number of characters immediately available in the get area. It is certain that \fBi\fR characters may be fetched without error, and without accessing any external device. .\" .SS "Output functions" .TP .B "int i = sbuf.sputc(c)" This function stores \fBc\fR just after the put pointer, and advances the pointer one position, possibly extending the sequence. It returns \fBc\fR, or \fBEOF\fR on error. What constitutes an error depends on the actual derived buffer class. .TP .B "int i = sbuf.sputn(ptr, len)" From the location pointed to by \fBptr\fR, stores exactly \fBlen\fR characters after the put pointer, advancing the put pointer just past the last character. It returns the number of characters stored, which ought to be \fBlen\fR. Fewer than \fBlen\fR characters stored indicates some sort of error. .TP .B "int i = sbuf.out_waiting()" This function returns the number of characters in the put area; that is, the number of characters pending output to the ultimate destination. .\" .SS "Positioning functions" .TP .B "streampos pos = sbuf.seekoff(off, dir, mode)" This function repositions the get and/or the put pointers, depending on the bits set in \fBmode\fR. If \fBios::in\fR is set in \fBmode\fR, the get pointer is moved; if \fBios::out\fR is set in \fBmode\fR, the put pointer is moved. The distance to move is \fBoff\fR, a signed quantity. The possible values for \fBdir\fR are .in +.5i \fBios::beg\fR \- move \fBoff\fR bytes from the beginning of the stream; .br \fBios::cur\fR \- move \fBoff\fR bytes from the current position; .br \fBios::end\fR \- move \fBoff\fR bytes from the end of the stream. .in -.5i This function returns the new position, or \fBEOF\fR if the stream could not be positioned as requested. Note: not all streams support positioning. Note: the position returned (of type \fBstreampos\fR) should not be the subject of any arithmetic operations, but should be treated as a ``magic'' value. .TP .B "streampos newpos = sbuf.seekpos(pos, mode)" This function repositions the get and/or the put pointers, depending on the bits set in \fBmode\fR, to position \fBpos\fR. If \fBios::in\fR is set in \fBmode\fR, the get pointer is moved; if \fBios::out\fR is set in \fBmode\fR, the put pointer is moved. The value of \fBpos\fR should be one which was returned by a previous call of \fBseekoff\fR or \fBseekpos\fR, but there are two special values which have conventional meanings: .in +.5i \fB(streampos)0\fR \- the beginning of the stream; .br \fB(streampos)EOF\fR \- error indicator. .in -.5i .TP .B "int i = sbuf.sync()" This function synchronizes the \fBstreambuf\fR with its actual stream of characters. The details depend on the particular derived buffer class. Generally, any characters in the put area will be flushed to their final destination, and any characters in the input buffer will be given back to their source, if possible. This generally means that \fBin_avail()\fR and \fBout_waiting()\fR will both return zero after a \fBsync\fR. This function returns \fBEOF\fR on any error, zero on success. .\" .SS "Miscellaneous functions" .TP .B "streambuf* sb = sbuf.setbuf(ptr, len)" This function logically belongs in the protected interface, but was placed in the public interface for compatibility with the original stream package. This function attempts to use the array of \fBlen\fR bytes starting at the location pointed to by \fBptr\fR as the buffer area. Setting \fBptr\fR to zero or \fBlen\fR to less than or equal to zero requests an unbuffered state. Depending on the details of the derived class, it may not be possible to honor the request. This function returns a pointer to the \fBstreambuf\fR on success, zero if the request could not be honored. .\" .SH "SEE ALSO" .LP .na .BR ios.intro (3CC4), .BR ios (3CC4), .BR sbufprot (3CC4), .TP .I C++ Library Reference .TP Chapter 3, "The Classic \fIiostream\fR Library", .TP Chapter 4, "Using Classic \fIiostream\fR in a Multithreaded Environment." .\" .TZ ????