ios.intro(C++)

Syntax

#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

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.

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

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(C++) and the protected interface (for derived classes) is described in sbuf.prot(C++).

ios

This class contains state variables that are common to the various stream classes, for example, error states and formatting states. See ios(C++).

istream

This class supports formatted and unformatted conversion from sequences of characters fetched from streambufs. See istream(C++).

ostream

This class supports formatted and unformatted conversion to sequences of characters stored into streambufs. See ostream(C++).

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(C++).

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(C++), ostream(C++), and ios(C++).

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 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

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(C++) and ios::unitbuf in ios(C++).)

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

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(C++).

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(C++).

strstreambuf

This buffer class stores and fetches characters from arrays of bytes in memory (i.e., strings). See ssbuf(C++).

Classes derived from istream, ostream, and iostream

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(C++).

istrstream
ostrstream

These classes support ``in core'' formatting. They use a strstreambuf. See strstream(C++).

stdiostream

This class specializes iostream for stdio FILEs. See stdiostream.h.

Caveats

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 manual pages) are present only for backward compatibility with the stream package.

See also