no copyright!iostream-intro.3

Introducing to I/O Using C++ Streams

Abstract

The C++ standard library provides mechanisms to perform input/output known under the name IOStreams. This document provides an introduction to this component.

Synopsis

#include <iosfwd>
    

Description

Standard IOStream objects

The C++ standard library predefines a set of stream objects for access to some special streams, analogous to the standard files defined by the C standard library. These objects are defined in two flavours: a "narrow" version using the type char as character type and a "wide" version using the type wchar_t as character type. The objects directly relate to objects in the C standard library:

Purpose Narrow Wide C
Input std::cin std::wcin stdin
Output std::cout std::wcout stdout
Error std::cerr std::wcerr stderr
Logging std::clog std::wclog stderr

Unless special action is taken, the IOStream objects are synchronized with the corresponding C files. Basically, this means that I/O with these streams behaves as if it is unbuffered. See iostream-performance(3) for details on this.

Forward Declarations

The various headers in the IOStreams components provide quite a few definitions which often depend on other components of the C++ standard library. Thus, it is often desirable to use forward declarations of the IOStream classes. For example, this is the case when writing header files which only reference types from the IOStreams library, eg. to declare a function taking an object of these classes as argument. Since it is not legal for a user to declare these types (for various reasons, here are just two: there may be more template arguments used by a specific implementation and it is not possible to declare template default argument twice), a header is provided to provide forward declarations of the IOStream types: <iosfwd>.

The header <iosfwd> provides declarations of all IOStream classes except for the class ios_base (this class is not a template and declarations of this type are rarely needed). This includes the basic IOStream classes (basic_ios, basic_streambuf, basic_istream, basic_ostream, basic_iostream) as well as the classes for I/O with strings (basic_stringbuf, basic_istringstream, basic_ostringstream, basic_stringstream) and with files (basic_filebuf, basic_ifstream, basic_ofstream, basic_fstream). For all of these template classes there are typedefs for the character types char and wchar_t: The names are formed by removing the string "basic_" for the type char and replacing the string "basic_" with "w" for the type wchar_t. There are also a few other type declared (e.g. because they are needed as template default arguments). These types are: istreambuf_iterator, ostreambuf_iterator, char_traits, allocator, and fpos. All declarations in the header are, of course, put into the namespace std and it is legal to include both <iosfwd> and other headers from the IOStream library (the conflict with multiple definitions of template default arguments has to be handle by the C++ implementation).

The header comes up in conjunction with a migration issue when migrating from old-fashioned IOStreams to the IOStream library as defined in the C++ standard library: Often programs declared the classes istream and ostream in header files with a declaration like "class istream;". Such declarations now have to be replaced by an include for the header <iosfwd> (see also iostream-migration(3)).

TODO

  • Describe limitations on calling imbue (27.1.1)
  • Describe limitations on pos_type and off_type (27.1.2)

See Also

iostream-migration(3)). iostream-performance(3)).
Copyright © 1999 Dietmar Kuehl, Claas Solutions (dietmar.kuehl@claas-solutions.de)