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(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 func-
tionality 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.
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 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 con-
sists 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 underly-
ing 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 sup-
ports 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.
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 posi-
tion, 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 posi-
tion 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 posi-
tion; 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 char-
acter 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 immedi-
ately 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 possi-
ble values for dir are
ios::beg - move off bytes from the beginning of
the stream;
ios::cur - move off bytes from the current posi-
tion;
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 posi-
tion 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 posi-
tion 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 char-
acters 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 inter-
face, but was placed in the public interface for compa-
tibility with the original stream package. This func-
tion 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(3CC4), ios(3CC4), sbufprot(3CC4),
C++ Library Reference
Chapter 3, "The Classic iostream Library",
Environment."
Chapter 4, "Using Classic iostream in a Multithreaded