sbufpub - public interface of the stream buffer base class
#include <iostream.h> 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 };
// see ios(3CC4) for remainder ...
} ;
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();
};
The 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 is expected to be created. Rather, buffer objects must be of a class type derived from streambuf. See sbufprot (3CC4) for a discussion of the protected interface necessary for such derivations.
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.
Class streambuf 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 get (or put) pointer. A buffer class intended for both input and output will have both pointers.
The get and put pointers should be understood as pointing between 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.
There can be different kinds of buffers (also called reserve areas) with different strategies, due to different underlying devices. Queue-like buffers, such as strstreambuf (see ssbuf(3cc4)), have independent get and put pointers. The strstreambuf is an in-memory array of characters and supports stores and fetches at arbitrary locations. File-like buffers, such as filebuf (see filebuf(3cc4)), may permit both get and put operations, but there is effectively only one pointer; the next get or put will always be at the current location. (In practice there may be two pointers, but they always point to the same place.)
The streambuf 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 sbufprot(3cc4) for details.) The storing, fetching, and pointer manipulation functions are generally inline for maximum efficiency. These are described below.
This function returns the character after the get pointer, or EOF if the get pointer is at the end of the sequence. Despite its name, this function does NOT move the get pointer.
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 EOF. Example: Suppose the input buffer looks like this:
abc|def
where `|' marks the position of the get pointer. This function will advance the get pointer and return `e'.
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 EOF.
This function moves the get pointer forward one position; it returns nothing. The combination of sgetc and stossc can be used to implement a scanner without using putback, since sgetc provides lookahead.
This function gets the next len characters following the get pointer, copying them to the char array pointed to by ptr; it advances the get pointer past the last character fetched. If fewer than len characters are left, it gets as many as are available. It returns the number of characters fetched.
This function attempts to move the get pointer back one character and put c 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 c at that location. Therefore, the effect of the function is uncertain if c 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 EOF 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.
This function returns the number of characters immediately available in the get area. It is certain that i characters may be fetched without error, and without accessing any external device.
This function stores c just after the put pointer, and advances the pointer one position, possibly extending the sequence. It returns c, or EOF on error. What constitutes an error depends on the actual derived buffer class.
From the location pointed to by ptr, stores exactly len 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 len. Fewer than len characters stored indicates some sort of error.
This function returns the number of characters in the put area; that is, the number of characters pending output to the ultimate destination.
This function repositions the get and/or the put pointers, depending on the bits set in mode. If ios::in is set in mode, the get pointer is moved; if ios::out is set in mode, the put pointer is moved. The distance to move is off, a signed quantity. The possible values for dir are
Move off bytes from the beginning of the stream.
Move off bytes from the current position.
Move off bytes from the end of the stream.
This function returns the new position, or EOF if the stream could not be positioned as requested. Note: not all streams support positioning. Note: the position returned (of type streampos) should not be the subject of any arithmetic operations, but should be treated as a ``magic'' value.
This function repositions the get and/or the put pointers, depending on the bits set in mode, to position pos. If ios::in is set in mode, the get pointer is moved; if ios::out is set in mode, the put pointer is moved. The value of pos should be one which was returned by a previous call of seekoff or seekpos, but there are two special values which have conventional meanings:
(streampos)0 - the beginning of the stream; (streampos)EOF - error indicator.
This function synchronizes the streambuf 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 in_avail() and out_waiting() will both return zero after a sync. This function returns EOF on any error, zero on success.
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 len bytes starting at the location pointed to by ptr as the buffer area. Setting ptr to zero or len 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 streambuf on success, zero if the request could not be honored.
ios (3CC4) , ios.intro (3CC4) , sbufprot (3CC4)
C++ Library Reference, Chapter 3, "The Classic iostream Library" and Chapter 4, "Using Classic iostreams in a Multithreaded Environment."