.\" to invoke 'tbl', 'eqn', 'pic' in the proper order .\" '\" tep .\" .\" @(#)ios.intro.3 1.1 93/04/27 SMI; .\" .TH IOS.INTRO 3CC4 "14 March 1995" .\" .SH NAME ios.intro \- introduction to iostreams and the man pages .\" .SH SYNOPSIS .LP .nf #include 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 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 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 class stdiobuf : public streambuf ; class stdiostream : public ios ; .ft B .ft R .fi .\" .SH DESCRIPTION .IX iostreams "introduction to" .IX introduction "to iostreams" 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 \fIstdio\fR files in C (also called streams), or Unix System V streams. .PP 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 versions are distinguished by the suffix \fB_unlocked\fR, which is appended to the function names. .PP Use of the ``safe'' versions does not guarantee that an application will behave properly in a multi-threaded environment; for more information on this subject see the .IR "C++ Library Reference Chapter 4, "Using Classic \fIiostream\fR in a Multithreaded Environment." .PP .SS History .LP The original edition of .IR "The C++ Programming Language" , by Bjarne Stroustrup, introduced C++ stream I/O which appeared in early releases of C++ compilers. A new version of stream I/O, usually called .IR 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 .B char types, and changes in the rules for nested types. .LP Although earlier implementations of C++ had only two character types, C++ now has three distinct versions of the .B char type: ``plain'' .BR char , .BR "signed char" , and .BR "unsigned char" . Earlier versions of iostreams had function versions taking ``plain'' .BR char , which was signed, and other versions taking .BR "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'' .BR char . .LP 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 enumerated type names defined inside class .B ios must now be qualified. That is, instead of using .BR io_state " or " seek_dir , you should now use .BR ios::io_state " or " ios::seek_dir . .LP In these man pages we describe the public and protected interfaces needed for writing portable programs using iostreams. We do not discuss implementation details which are not exposed to public view, and which should not be relied on in portable programs. .SS "Fundamental Classes" .LP Iostreams are basically a collection of class hierarchies. The fundamental classes are as follows: .\" .TP .BR unsafe_ios This class contains state variables that are common to the various stream classes, for example, error states and formatting states. This class is not protected against multi-threaded access. See \fIios(3CC4)\fP. .TP .B ios Class .B ios is a virtual base class of every stream. It maintains formatting and status information. This class is further described in .BR ios (3CC4). This class uses mutex locks to protect against multi-threaded access. See \fIios(3CC4)\fP. .\" .TP .B streambuf Class .B streambuf is the virtual base class for all stream buffers. This class defines the basic functionality for buffering, supporting .I insertion (storing, also known as .IR putting ) and .I extraction (fetching, also known as .IR getting ). Each non-virtual member function is defined in two versions: an unlocked version (distinguished by the suffix \fB_unlocked\fR 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 .BR sbufpub (3CC4). The protected interface for the class, used when deriving new buffer classes, is described in .BR sbufprot (3CC4). .\" .TP .BR unsafe_istream This class supports formatted and unformatted conversion from sequences of characters fetched from .BR streambuf s. This class is not protected against multi-threaded access. See \fIistream(3CC4)\fP. .TP .B istream Class .B istream provides formatted and unformatted input operations on an associated \fBstreambuf\fR. This class is further described in .BR istream (3CC4). .\" .TP .BR unsafe_ostream This class supports formatted and unformated conversion to sequences of characters stored into .BR streambuf s. This class is not protected against multi-threaded access. See \fIostream(3CC4)\fP. .TP .B ostream Class .B ostream provides formatted and unformatted output operations on an associated \fBstreambuf\fR. This class is further described in .BR ostream (3CC4). .\" .TP .B iostream Class .B iostream combines the functionality of \fBistream\fR and \fBostream\fR. .B iostream provides both input and output on a single bidirectional stream. .TP .B istream_withassign .in -.5i .br .B ostream_withassign .br .B iostream_withassign .br .in +.5i Classes .BR istream_withassign ", " ostream_withassign ", and " iostream_withassign add the assignment operator to their corresponding classes: .BR istream ", " ostream ", and " iostream . The predefined streams .BR cin ", " cout ", " cerr ", and " .B clog (described below) require the assignment operator for technical reasons, and are objects of these class types. .SS "Derived Buffer Classes" .LP 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 .BR streambuf , as explained in .BR sbufprot (3CC4). Three predefined buffer classes are provided with iostreams: .TP .B filebuf This buffer class provides I/O for files, through low-level file descriptors; C ``standard I/O'' .RI ( stdio ) is not used by .BR filebuf s. Member functions support file open, close, and seek operations. When you get from or put to a .BR 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 (distinguished by the suffix \fB_unlocked\fR 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 .BR filebuf (3CC4). .TP .B stdiobuf This buffer class provides I/O using C stdio .B FILE structures. This form of I/O is much less efficient than using .BR filesbuf s. If you must mix I/O to the same file using iostream and C stdio, use a .B stdiobuf as the stream buffer class. Otherwise, use a .BR filebuf. This class is further described in .BR stdiobuf (3CC4). .TP .B 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 (distinguished by the suffix \fB_unlocked\fR 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 .BR ssbuf (3CC4) .SS "Derived Stream Classes" .LP You normally define a stream class by deriving from one of .BR istream ", " ostream ", or " iostream , and using a specialized buffer class. There are several predefined stream classes for the most common needs: .TP .B ifstream .in -.5i .br .B ofstream .br .B fstream .br .in +.5i These classes support file I/O by using a .B filebuf 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 .BR fstream (3CC4). .TP .B istrstream .in -.5i .br .B ostrstream .br .B strstream .br .in +.5i These classes support ``I/O'' with in-memory character arrays by using a .B 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 .BR strstream (3CC4) .TP .B stdiostream This class uses a .B stdiobuf as its associated buffer class. As noted above, this is much less efficient than using an .B fstream or other stream using a .BR filebuf . The only reason to use a .B 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 .BR stdiobuf (3CC4). .SS "Predefined Streams" .LP C and C++ programs traditionally begin execution with three predefined files for I/O: the standard input, output and error files. When you include .B in your program, four predefined iostreams become available for use: .TP .B cin connected to standard input (file descriptor 0). .TP .B cout connected to standard output (file descriptor 1). .TP .B cerr connected to standard error (file descriptor 2). Data written to .B cerr is by default .IR unit-buffered, meaning that characters are flushed after each complete insertion operation. .TP .B clog connected to standard error (file descriptor 2). By default, this stream is fully buffered, which is the only difference from using .BR cerr . .HP The streams .BR cin ", " cerr ", and " clog are .I tied to .BR cout , meaning that .B cout is flushed before extracting from .B cin or inserting to .BR cerr " or " clog . The pre-defined streams are, by default, protected against multi-threaded access by the use of mutex locks. This protection may be disabled by calling the member function .BR set_safe_flag defined by class .BR stream_MT . .SS "Header Files" .TP .B This header provides the basic functionality of iostreams, including the use of the predefined streams. .TP .B This header includes .B and also defines the .BR filebuf " and " fstream classes. .TP .B This header includes .B and also defines the .BR strstreambuf " and " strstream classes. .TP .B This header includes .B and also defines the .BR stdiobuf " and " stdiostream classes. .TP .B This header defines some standard .IR manipulators . Manipulators are described in the tutorial, as well as in .BR manip (3CC4). .\" .SH "SEE ALSO" .na .BR filebuf (3CC4), .BR fstream (3CC4), .BR ios (3CC4), .BR istream (3CC4), .BR manip (3CC4), .BR ostream (3CC4), .BR sbufprot (3CC4), .BR sbufpub (3CC4), .BR ssbuf (3CC4) .BR stdiobuf (3CC4), .BR strstream (3CC4), .BR stream_locker (3CC4), .BR stream_MT (3CC4), .TP .I C++ Library Reference .TP Chapter 3, "The Classic \fIiostream\fR Library", .TP Chapter 4, "Using Classic \fIiostream\fR in a Multithreaded Environment." .\" .TZ ????