Another borrowing from Standard C is the type streamoff. It is used to represent signed offsets for positioning operations within a stream controlled by a streambuf object. That, of course, includes C-style streams controlled by objects of type FILE. A streamoff object must thus be able to represent the offsets used by the functions fseek and ftell, both declared in <stdio.h>. Hence, the type is pretty much constrained to have the same representation as type long.

Sadly, type streamoff shares the same double meaning with its Standard C counterpart:

• It can be a signed displacement relative to some position within a file. All values are meaningful.
• It can be an absolute position within some file. Negative values are nonsensical. (And a file may be so large that it has positions not representable as values of type streamoff.)

I have found it convenient in this implementation to define the secret constant _BADOFF. As in Standard C, it is the standard way to indicate an invalid absolute position. Unfortunately, it sometimes also is used to indicate an invalid relative position, for which the value —1 is a less compelling choice.

The Standard C I/O model also influences the iostreams machinery in more subtle ways. In particular, the remainder of header <streambuf> defines two classes:

• streampos, for describing arbitrary positions within a stream
• streambuf, for controlling input and output to a stream

Nevertheless, an important use for both these classes is to interface with their Standard C counterparts. Hence, class streampos is shaped internally by the needs of the Standard C functions fgetpos and fsetpos, declared in <stdio.h>. And class streambuf is obliged to work well with the streams of Standard C. Like it or not (and many C++ purists definitely do not like it), you will find artifacts of Standard C popping up in both these classes.

Conceptually, every streambuf object controls an input stream and an output stream. Often, one of the two streams doesn't really exist. All operations on the nonexistent stream simply fail. If there are indeed two streams, there need be no connection between them, but usually there is. Each stream can maintain a separate position indicator, but they can also be tied together and move in concert.

Class streambuf describes a very general engine for managing input and output character sequences. The class offers a public interface for civilian use. Typically, the inserters associated with an ostream object, such as cout, call on parts of this public interface to "insert characters into an output sequence." And the extractors associated with an istream object, such as cin, call on other parts of this public interface to "extract characters from an input sequence."

You may never have occasion to use this interface yourself. Even if you write your own inserters and extractors, you often do the low-level work by calling on existing inserters and extractors. In fact, I'd discourage you from making direct calls on a streambuf object, at least until you've had time to study some existing inserters and extractors and really understand the protocol. Any abstract description you read will never compare to first-hand practical experience. For now, I'll characterize the public interface to class streambuf in the briefest of terms.

When extracting from a sequence:

• Peek at the next character by calling sgetc(), extract (and point past) it by calling sbumpc(), or put back the last character ch you extracted by calling sputbackc(ch).
• Read up to n characters into a buffer buf by calling sgetn(buf, n). The return value tells you how many characters you actually read.
• For various reasons of performance or reliability, avoid calling snextc() or sungetc(). Also avoid calling sputbackc(ch) except as I described above.

• Write a character ch by calling sputc(ch).
• Write up to n characters from a buffer buf by calling sputn(buf, n). The return value tells you how many characters you actually wrote, which should always be n.

Similarly, the functions pubsetbuf and pubsync are really just hooks into virtual functions that are specialized for derived classes. The default behavior for the base class is to do nothing.

The first part of the protected interface you can, and should, pretty much ignore. It is used by the public members to conduct their business. Here again you will find a number of funny names and irregularities. But that should be of no concern to the typical user of a class derived from streambuf. Look at the public member functions, nearly all of which are inlined, to get a feel for what they do, if you care.

You might note, in passing, that the constructors for class streambuf are protected. That keeps you from constructing an object of this class outside captivity. The idea is to derive from the base class and specialize it to perform useful operations. (I discussed the special magic about constructors with argument type _Uninitialized last month.)

The second part of the protected interface is where the action is. Class streambuf is built around a set of virtual member functions that allow you to tailor behavior over a very wide range. Here is where insertions get turned into actual writes to some physical sink for characters. Here is where extractors get turned into actual reads from some physical source of characters. Here is where positioning operations get real, or those other hooks get something hung upon them. In short, the art of specializing streambuf is the art of writing virtual member functions that honor the basic protocol of the base class.

Until the draft C++ Standard came along, there was only one way to specialize a streambuf. Find some code for another specialization that more or less worked, and that you could more or less understand, and crib like crazy. Having access to the source for streambuf proper also helped.

Now you have a little help. You can read the draft C++ Standard to learn the protocol that must be honored by these virtual member functions. Then you can go look at some specialization that works and that you can more or less understand, and crib like crazy. I can't honestly recommend any other way to proceed.

Why is this so? Because describing the protocol for the streambuf virtual member functions is the hardest piece of standardese I've ever essayed. Jerry Schwarz, the original author of iostreams, is still not happy with what I wrote. I think it's getting reasonably accurate and precise, but I'd never accuse this part of the draft of being a decent tutorial. Learning by imitation — and by doing — is still the safest route.

Having said that, I'll give you just the briefest of hints about what the four most critical virtual member functions do:

• overflow(ch) either writes the character ch to the physical sink of characters, somehow, or it "makes a write position available" (creates an in-memory buffer with a space available for writing a character) and puts the character in it.
• pbackfail(ch) either writes the character ch back to the physical source of characters, somehow, or it "makes a putback position available" (creates an in-memory buffer with a space available for putting back a character) and puts the character in it.
• underflow() either reads a character from the physical source of characters without consuming it, somehow, or it "makes a read position available" (creates an in-memory buffer with a character available for reading) and reads the character from it without consuming it.
• uflow() either reads a character from the physical source of characters and consumes it, somehow, or it "makes a read position available" (creates an in-memory buffer with a character available for reading) and reads and consumes a character from it.