SBUFPUB(3CC4)SBUFPUB(3CC4)NAMEsbufpub - 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(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();
};
DESCRIPTION
The streambuf class defines the basic buffer-class functionality from
which actual buffer classes are derived. This public interface repre‐
sents 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.
ENVIRONMENT
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 applica‐
tions 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 iden‐
tical functionality.
Class streambuf supports an abstract buffer class. It consists logi‐
cally 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 char‐
acters 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 char‐
acters 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 out‐
put buffer. (See sbufprot(3CC4) 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 char‐
acter 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 charac‐
ter 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 func‐
tion returns EOF if the attempted putback fails. What consti‐
tutes 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 charac‐
ters 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 indi‐
cates 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 quan‐
tity. 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 opera‐
tions, 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 ALSOios.intro(3CC4), ios(3CC4), sbufprot(3CC4),
C++ Library Reference
Chapter 3, "The Classic iostream Library",
Chapter 4, "Using Classic iostream in a Multithreaded Environ‐
ment."
18 June 1998 SBUFPUB(3CC4)
