intro(3C++)
iostream - buffering, formatting and input/output
Showing IRIX 6.5. First release of IRIX 6.5.
NAME iostream - 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. 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 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++). 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++)