IOS.INTRO(3CC4)IOS.INTRO(3CC4)NAMEios.intro - introduction to iostreams and the man pages
SYNOPSIS
#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 ;
DESCRIPTION
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 ver‐
sions 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 informa‐
tion on this subject see the C++ Library Reference Chapter 4, "Using
Classic iostream in a Multithreaded Environment."
History
The original edition of The C++ Programming Language, by Bjarne Strous‐
trup, 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 enumer‐
ated 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 dis‐
cuss implementation details which are not exposed to public view, and
which should not be relied on in portable programs.
Fundamental Classes
Iostreams are basically a collection of class hierarchies. The funda‐
mental classes are as follows:
unsafe_ios
This class contains state variables that are common to the vari‐
ous stream classes, for example, error states and formatting
states. This class is not protected against multi-threaded
access. See ios(3CC4).
ios 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).
streambuf
Class streambuf is the virtual base class for all stream buf‐
fers. 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 sbuf‐
prot(3CC4).
unsafe_istream
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).
istream
Class istream provides formatted and unformatted input opera‐
tions on an associated streambuf. This class is further
described in istream(3CC4).
unsafe_ostream
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).
ostream
Class ostream provides formatted and unformatted output opera‐
tions on an associated streambuf. This class is further
described in ostream(3CC4).
iostream
Class iostream combines the functionality of istream and
ostream. iostream provides both input and output on a single
bidirectional stream.
istream_withassign
ostream_withassign
iostream_withassign
Classes istream_withassign, ostream_withassign, and
iostream_withassign add the assignment operator to their corre‐
sponding classes: istream, ostream, and iostream. The prede‐
fined streams cin, cout, cerr, and clog (described below)
require the assignment operator for technical reasons, and are
objects of these class types.
Derived Buffer Classes
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 buf‐
fer classes are provided with iostreams:
filebuf
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 (dis‐
tinguished 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).
stdiobuf
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).
strstreambuf
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 (dis‐
tinguished 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)
Derived Stream Classes
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:
ifstream
ofstream
fstream
These classes support file I/O by using a filebuf as the associ‐
ated 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 fur‐
ther described in fstream(3CC4).
istrstream
ostrstream
strstream
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)
stdiostream
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).
Predefined Streams
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:
cin connected to standard input (file descriptor 0).
cout connected to standard output (file descriptor 1).
cerr 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.
clog 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 protec‐
tion may be disabled by calling the member function
set_safe_flag defined by class stream_MT.
Header Files
<iostream.h>
This header provides the basic functionality of iostreams,
including the use of the predefined streams.
<fstream.h>
This header includes <iostream.h> and also defines the filebuf
and fstream classes.
<strstream.h>
This header includes <iostream.h> and also defines the
strstreambuf and strstream classes.
<stdiostream.h>
This header includes <iostream.h> and also defines the stdiobuf
and stdiostream classes.
<manip.h>
This header defines some standard manipulators. Manipulators
are described in the tutorial, as well as in manip(3CC4).
SEE ALSOfilebuf(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",
Chapter 4, "Using Classic iostream in a Multithreaded Environ‐
ment."
14 March 1995 IOS.INTRO(3CC4)
