Stream Buffers

One of the most important concepts in the USL I/O Stream Library is the stream buffer. The streambuf class implements some of the member functions that define stream buffers, but other specialized member functions are left to the classes that are derived from streambuf: strstreambuf, stdiobuf, and filebuf.

The AT&T and UNIX System Laboratories C++ Language System documentation use the terms reserve area and buffer instead of stream buffer.

What Does a Stream Buffer Do?

A stream buffer acts as a buffer between the ultimate producer (the source of data) or ultimate consumer (the target of data) and the member functions of the classes derived from ios that format this raw data. The ultimate producer can be input from the user, a file, a device, or an array of bytes in memory. The ultimate consumer can be a file, a device, or an array of bytes in memory.

Why Use a Stream Buffer?

In most operating systems, a system call to read data from the ultimate producer or write it to the ultimate consumer is an expensive operation. If your applications can reduce the number of system calls they have to make, performance may improve. By acting as a buffer between the ultimate producer or ultimate consumer and the formatting functions, a stream buffer can reduce the number of system calls that are made.

Consider, for example, an application that is reading data from the ultimate producer. If there is no buffer, the application has to make a system call for each character that is read. However, if the application uses a stream buffer, system calls will only be made when the buffer is empty. Each system call will read enough characters from the ultimate producer (if they are available) to fill the buffer again.

z/OS The main reason to use stream buffers on z/OS is to ensure optimal portability.

How is a stream buffer implemented?

A stream buffer is implemented as an array of bytes. For each stream buffer, pointers are defined that point to elements in this array to define the get area (the space that is available to accept bytes from the ultimate producer), and the put area (the space that is available to store bytes that are on their way to the ultimate consumer).

A stream buffer does not necessarily have separate get and put areas:

The following member functions of the streambuf class return pointers to get and put boundaries of areas in a stream buffer:

Member function Description
base Returns a pointer to the beginning of the stream buffer.
eback Returns a pointer to the beginning of the space available for putback. Characters that are putback are returned to the get area of the stream buffer.
gptr Returns the get pointer (a pointer to the beginning of the get area). The space between gptr and egptr has been filled by the ultimate producer.
egptr Returns a pointer to the end of the get area.
pbase Returns a pointer to the beginning of the space available for the put area.
pptr Returns the put pointer (a pointer to the beginning of the put area). The space between pbase and pptr is filled with bytes that are waiting to be sent to the ultimate consumer. The space between pptr and epptr is available to accept characters from the application program that are on their way to the ultimate consumer.
epptr Returns a pointer to the end of the put area.
ebuf Returns a pointer to the end of the stream buffer.

In the actual implementation of stream buffers, the pointers returned by these functions point at char values. In the abstract concept of stream buffers, on the other hand, these pointers point to the boundary between char values. To establish a correspondence between the abstract concept and the actual implementation, you should think of the pointers as pointing to the boundary just before the character that they actually point at.

The following diagram is the structure of a stream buffer:

illustration of a stream buffer, as described in the preceding table

Related Concepts