IOS.INTRO(3C++) IOS.INTRO(3C++)
NAMEiostream - buffering, formatting and input/output
SYNOPSIS
#include <iostream.h>
class streambuf ;
class ios ;
class istream : virtual public ios ;
class ostream : virtual public ios ;
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 fstream : public iostream ;
class ifstream : public istream ;
class ofstream : public ostream ;
#include <strstream.h>
class strstreambuf : public streambuf ;
class istrstream : public istream ;
class ostrstream : public ostream ;
#include <stdiostream.h>
class stdiobuf : public streambuf ;
class stdiostream : public ios ;
DESCRIPTION
The C++ iostream package declared in iostream.h and other header files
consists primarily of a collection of classes. Although originally
intended only to support input/output, the package now supports related
activities such as incore formatting. This package is a mostly source-
compatible extension of the earlier stream I/O package, described in The
C++ Programming Language by Bjarne Stroustrup.
In the iostream man pages, character refers to a value that can be held
in either a char or unsigned char. When functions that return an int are
said to return a character, they return a positive value. Usually such
functions can also return EOF (-1) as an error indication. The piece of
memory that can hold a character is referred to as a byte. Thus, either
a char* or an unsigned char* can point to an array of bytes.
Page 1
IOS.INTRO(3C++) IOS.INTRO(3C++)
The iostream package consists of several core classes, which provide the
basic functionality for I/O conversion and buffering, and several
specialized classes derived from the core classes. Both groups of
classes are listed below.
Core Classes
The core of the iostream package comprises the following classes:
streambuf
This is the base class for buffers. It supports insertion
(also known as storing or putting) and extraction (also known
as fetching or getting) of characters. Most members are
inlined for efficiency. The public interface of class
streambuf is described in sbuf.pub(3C++) and the protected
interface (for derived classes) is described in
sbuf.prot(3C++).
ios This class contains state variables that are common to the
various stream classes, for example, error states and
formatting states. See ios(3C++).
istream
This class supports formatted and unformatted conversion from
sequences of characters fetched from streambufs. See
istream(3C++).
ostream
This class supports formatted and unformated conversion to
sequences of characters stored into streambufs. See
ostream(3C++).
iostream
This class combines istream and ostream. It is intended for
situations in which bidirectional operations (inserting into
and extracting from a single sequence of characters) are
desired. See ios(3C++).
istream_withassign
ostream_withassign
iostream_withassign
These classes add assignment operators and a constructor with
no operands to the corresponding class without assignment. The
predefined streams (see below) cin, cout, cerr, and clog, are
objects of these classes. See istream(3C++), ostream(3C++),
and ios(3C++).
Iostream_init
This class is present for technical reasons relating to
initialization. It has no public members. The Iostream_init
constructor initializes the predefined streams (listed below).
Because an object of this class is declared in the iostream.h
header file, the constructor is called once each time the
Page 2
IOS.INTRO(3C++) IOS.INTRO(3C++)
header is included (although the real initialization is only
done once), and therefore the predefined streams will be
initialized before they are used. In some cases, global
constructors may need to call the Iostream_init constructor
explicitly to ensure the standard streams are initialized
before they are used.
Predefined streams
The following streams are predefined:
cin The standard input (file descriptor 0).
cout The standard output (file descriptor 1).
cerr Standard error (file descriptor 2). Output through this stream
is unit-buffered, which means that characters are flushed after
each inserter operation. (See ostream::osfx() in ostream(3C++)
and ios::unitbuf in ios(3C++).)
clog This stream is also directed to file descriptor 2, but unlike
cerr its output is buffered.
cin, cerr, and clog are tied to cout so that any use of these will
cause cout to be flushed.
In addition to the core classes enumerated above, the iostream package
contains additional classes derived from them and declared in other
headers. Programmers may use these, or may choose to define their own
classes derived from the core iostream classes.
Classes derived from streambuf
Classes derived from streambuf define the details of how characters are
produced or consumed. Derivation of a class from streambuf (the
protected interface) is discussed in sbuf.prot(3C++). The available
buffer classes are:
filebuf
This buffer class supports I/O through file descriptors.
Members support opening, closing, and seeking. Common uses do
not require the program to manipulate file descriptors. See
filebuf(3C++).
stdiobuf
This buffer class supports I/O through stdio FILE structs. It
is intended for use when mixing C and C++ code. New code
should prefer to use filebufs. See stdiobuf(3C++).
strstreambuf
This buffer class stores and fetches characters from arrays of
bytes in memory (i.e., strings). See ssbuf(3C++).
Page 3
IOS.INTRO(3C++) IOS.INTRO(3C++)
Classes derived from istream, ostream, and iostream
Classes derived from istream, ostream, and iostream specialize the core
classes for use with particular kinds of streambufs. These classes are:
ifstream
ofstream
fstream
These classes support formatted I/O to and from files. They
use a filebuf to do the I/O. Common operations (such as
opening and closing) can be done directly on streams without
explicit mention of filebufs. See fstream(3C++).
istrstream
ostrstream
These classes support ``in core'' formatting. They use a
strstreambuf. See strstream(3C++).
stdiostream
This class specializes iostream for stdio FILEs. See
stdiostream.h.
CAVEATS
Parts of the streambuf class of the old stream package that should have
been private were public. Most normal usage will compile properly, but
any code that depends on details, including classes that were derived
from streambufs, will have to be rewritten.
Performance of programs that copy from cin to cout may sometimes be
improved by breaking the tie between cin and cout and doing explicit
flushes of cout.
The header file stream.h exists for compatibility with the earlier stream
package. It includes iostream.h, stdio.h, and some other headers, and it
declares some obsolete functions, enumerations, and variables. Some
members of streambuf and ios (not discussed in these man pages) are
present only for backward compatibility with the stream package.
SEE ALSO
ios(3C++), sbuf.pub(3C++), sbuf.prot(3C++), filebuf(3C++),
stdiobuf(3C++), ssbuf(3C++), istream(3C++), ostream(3C++), fstream(3C++),
strstream(3C++), and manip(3C++)
Page 4
