ios.intro - introduction to iostreams and the man pages
#include <iostream.h> class stream_MT ; class streambuf : public stream_MT ; class unsafe_ios ; class ios : virtual public unsafe_ios, public stream_MT ; class unsafe_istream : virtual public unsafe_ios ; class istream : virtual public ios, public unsafe_istream ; class unsafe_ostream : virtual public unsafe_ios ; class ostream : virtual public ios, public unsafe_ostream ; class unsafe_iostream : public unsafe_istream, public unsafe_ostream ; class iostream : public istream, public ostream ; class istream_withassign : public istream ; class ostream_withassign : public ostream ; class iostream_withassign : public iostream ;
class Iostream_init ;
extern istream_withassign cin ; extern ostream_withassign cout ; extern ostream_withassign cerr ; extern ostream_withassign clog ;
#include <fstream.h> class filebuf : public streambuf ; class unsafe_fstreambase : virtual public unsafe_ios ; class fstreambase : virtual public ios, public unsafe_fstreambase ; class fstream : public fstreambase, public iostream ; class ifstream : public fstreambase, public istream ; class ofstream : public fstreambase, public ostream ;
#include <strstream.h> class strstreambuf : public streambuf ; class unsafe_strstreambase : public virtual unsafe_ios ; class strstreambase : public virtual ios, public unsafe_strstreambase ; class istrstream : public strstreambase, public istream ; class ostrstream : public strstreambase, public ostream ; class strstream : public strstreambase, public iostream ;
#include <stdiostream.h> class stdiobuf : public streambuf ; class stdiostream : public ios ;
These man pages provide the reference material needed to understand the details of the individual functions and classes which make up C++ stream I/O. The term ``stream'' as used here has nothing to do with stdio files in C (also called streams), or Unix System V streams.
The iostream package has been extended to support the sharing of iostream objects among multiple cooperating threads under the libthread library. Most iostream classes are now defined in two forms, an ``unsafe'' version which does not protect against simultaneous access by multiple threads, and a ``safe'' version which uses mutex locks to protect objects from concurrent access. Two exceptions are the class streambuf and class filebuf; these objects support both locked and unlocked versions of all relevant member functions. The unlocked versions are distinguished by the suffix _unlocked, which is appended to the function names.
Use of the ``safe'' versions does not guarantee that an application will behave properly in a multi-threaded environment; for more information on this subject see the C++ Library Reference Chapter 4, "Using Classic iostream in a Multithreaded Environment."
The original edition of The C++ Programming Language, by Bjarne Stroustrup, introduced C++ stream I/O which appeared in early releases of C++ compilers. A new version of stream I/O, usually called iostreams, appeared beginning with the ``2.0'' release of C++. Compared with original stream I/O, iostreams made more effective use of C++ language features, especially new language features not available in earlier versions of C++. Basic stream I/O still worked the same way in both versions of streams, and iostreams included some backward-compatibility features to further ease the transition. This latest release of iostreams has further modifications due to additional language changes. The changes fall into two categories: changes in the char types, and changes in the rules for nested types.
Although earlier implementations of C++ had only two character types, C++ now has three distinct versions of the char type: ``plain'' char, signed char, and unsigned char. Earlier versions of iostreams had function versions taking ``plain'' char, which was signed, and other versions taking unsigned char. Because these functions (mostly) deal only with characters and arrays of characters, there is now (mostly) only one version of such functions, taking ``plain'' char.
Earlier versions of C++ used the C rule that a type defined inside a class was treated as though it were defined outside the class. The C++ language rule is now that any type defined inside a class is local to that class, and may be referenced only with the outer class qualifier. This affects iostreams in only a few places. For example, the enumerated type names defined inside class ios must now be qualified. That is, instead of using io_state or seek_dir, you should now use ios::io_state or ios::seek_dir.
In these man pages we describe the public and protected interfaces needed for writing portable programs using iostreams. We do not discuss implementation details which are not exposed to public view, and which should not be relied on in portable programs.
Iostreams are basically a collection of class hierarchies. The fundamental classes are as follows:
This class contains state variables that are common to the various stream classes, for example, error states and formatting states. This class is not protected against multi-threaded access. See ios(3CC4).
Class ios is a virtual base class of every stream. It maintains formatting and status information. This class is further described in ios(3CC4). This class uses mutex locks to protect against multi-threaded access. See ios(3CC4).
Class streambuf is the virtual base class for all stream buffers. This class defines the basic functionality for buffering, supporting insertion (storing, also known as putting) and extraction (fetching, also known as getting). Each non-virtual member function is defined in two versions: an unlocked version (distinguished by the suffix _unlocked appended to the function name) which does not protect against multi-threaded access; and a locked version (the default) which is mt-safe. The public interface for the class, used for programming I/O, is described in sbufpub(3CC4). The protected interface for the class, used when deriving new buffer classes, is described in sbufprot(3CC4).
This class supports formatted and unformatted conversion from sequences of characters fetched from streambufs. This class is not protected against multi-threaded access. See istream(3CC4).
Class istream provides formatted and unformatted input operations on an associated streambuf. This class is further described in istream(3CC4).
This class supports formatted and unformated conversion to sequences of characters stored into streambufs. This class is not protected against multi-threaded access. See ostream(3CC4).
Class ostream provides formatted and unformatted output operations on an associated streambuf. This class is further described in ostream(3CC4).
Class iostream combines the functionality of istream and ostream. iostream provides both input and output on a single bidirectional stream.
Classes istream_withassign, ostream_withassign, and iostream_withassign add the assignment operator to their corresponding classes: istream, ostream, and iostream. The predefined streams cin, cout, cerr, and clog (described below) require the assignment operator for technical reasons, and are objects of these class types.
The buffer class associated with a stream defines the way in which characters are fetched or stored. You may derive your own buffer class from streambuf, as explained in sbufprot(3CC4). Three predefined buffer classes are provided with iostreams:
This buffer class provides I/O for files, through low-level file descriptors; C ``standard I/O'' (stdio) is not used by filebufs. Member functions support file open, close, and seek operations. When you get from or put to a filebuf, the buffer class reads or writes the associated file as required. Each non-virtual member function is defined in two versions: an unlocked version (distinguished by the suffix _unlocked appended to the function name) which does not protect against multi-threaded access; and a locked version (the default) which is mt-safe. This class is further described in filebuf(3CC4).
This buffer class provides I/O using C stdio FILE structures. This form of I/O is much less efficient than using filesbufs. If you must mix I/O to the same file using iostream and C stdio, use a stdiobuf as the stream buffer class. Otherwise, use a filebuf. This class is further described in stdiobuf(3CC4).
This class provides formatted and unformatted memory transfer betweeen streams and character arrays. Each non-virtual member function is defined in two versions: an unlocked version (distinguished by the suffix _unlocked appended to the function name) which does not protect against multi-threaded access; and a locked version (the default) which is mt-safe. This class is further described in ssbuf(3CC4)
You normally define a stream class by deriving from one of istream, ostream, or iostream, and using a specialized buffer class. There are several predefined stream classes for the most common needs:
These classes support file I/O by using a filebuf as the associated buffer class. They are, respectively, for input, output, and bidirectional use. These classes are protected against multi-threaded access with mutex locks. These classes are further described in fstream(3CC4).
These classes support ``I/O'' with in-memory character arrays by using a strstreambuf as the associated buffer class. They are, respectively, for input, output, and bidirectional use. These classes are protected against multi-threaded access with mutex locks. These classes are further described in strstream(3CC4).
This class uses a stdiobuf as its associated buffer class. As noted above, this is much less efficient than using an fstream or other stream using a filebuf. The only reason to use a stdiostream is to be able to perform I/O to the same file from both iostreams code and C stdio code. This class is further described in stdiobuf(3CC4).
C and C++ programs traditionally begin execution with three predefined files for I/O: the standard input, output and error files. When you include <iostream.h> in your program, four predefined iostreams become available for use:
Connected to standard input (file descriptor 0).
Connected to standard output (file descriptor 1).
Connected to standard error (file descriptor 2). Data written to cerr is by default unit-buffered, meaning that characters are flushed after each complete insertion operation.
Connected to standard error (file descriptor 2). By default, this stream is fully buffered, which is the only difference from using cerr.
The streams cin, cerr, and clog are tied to cout, meaning that cout is flushed before extracting from cin or inserting to cerr or clog. The pre-defined streams are, by default, protected against multi-threaded access by the use of mutex locks. This protection may be disabled by calling the member function set_safe_flag defined by class stream_MT.
This header provides the basic functionality of iostreams, including the use of the predefined streams.
This header includes <iostream.h> and also defines the filebuf and fstream classes.
This header includes <iostream.h> and also defines the strstreambuf and strstream classes.
This header includes <iostream.h> and also defines the stdiobuf and stdiostream classes.
This header defines some standard manipulators. Manipulators are described in the tutorial, as well as in manip(3CC4).
filebuf(3CC4), fstream(3CC4), ios(3CC4), istream(3CC4), manip(3CC4), ostream(3CC4), sbufprot(3CC4), sbufpub(3CC4), ssbuf(3CC4) stdiobuf(3CC4), strstream(3CC4), stream_locker(3CC4), stream_MT(3CC4)
C++ Library Reference, Chapter 3, "The Classic iostream Library" and Chapter 4, "Using Classic iostreams in a Multithreaded Environment."