SBUFPUB(3C++)

NAME
sbufpub - public interface of the stream buffer base class

SYNOPSIS

#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(3C++) 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();
};

DESCRIPTION

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 (3C++) for a discussion of the protected interface necessary for such derivations.

  ENVIRONMENT
The discussion about thread safety applies only to Solaris 2.x.

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(3C++)), 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(3C++)), 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(3C++) for details.) The storing, fetching, and pointer manipulation functions are generally inline for maximum efficiency. These are described below.

  Input functions

int c = sbuf.sgetc()
    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.

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 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'.

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 EOF.

sbuf.stossc()
    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.

int i = sbuf.sgetn(ptr, len)
    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.

int c = sbuf.sputbackc(c)
    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.

int i = sbuf.in_avail()
    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.

  Output functions

int i = sbuf.sputc(c)
    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.

int i = sbuf.sputn(ptr, len)
    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.

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.

  Positioning functions

streampos pos = sbuf.seekoff(off, dir, mode)
    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
    ios::beg - move off bytes from the beginning of the stream;
    ios::cur - move off bytes from the current position;
    ios::end - 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.

streampos newpos = sbuf.seekpos(pos, mode)
    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.

int i = sbuf.sync()
    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.

  Miscellaneous functions

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

SEE ALSO

ios.intro(3C++), ios(3C++), sbufprot(3C++),

C++ 4.1 Library Reference Manual:

Chapter 4, "The Iostream Library",

Chapter 5, "Using libC in a Multithreaded Environment."