.\" '\" tep .\" to invoke 'tbl', 'eqn', 'pic' in the proper order .\" .\" @(#)ios.3 1.2 93/06/29 SMI; .\" .TH IOS 3CC4 "18 June 1998" .\" .SH NAME ios \- basic iostreams formatting .SH SYNOPSIS .LP .nf .ft B #include .sp .5v class unsafe_ios { public: // exported types // stream status bits enum io_state { goodbit = 0x00, // no bit set: all is ok eofbit = 0x01, // at end of file failbit = 0x02, // last I/O operation failed badbit = 0x04, // invalid operation attempted hardfail = 0x80 // unrecoverable error }; // stream operation mode enum open_mode { in = 0x01, // open for reading out = 0x02, // open for writing ate = 0x04, // seek to eof upon original open app = 0x08, // append mode: all additions at eof trunc = 0x10, // truncate file if already exists nocreate = 0x20, // open fails if file doesn't exist noreplace= 0x40 // open fails if file already exists }; // stream seek direction enum seek_dir { beg=0, cur=1, end=2 }; // formatting flags enum { skipws = 0x0001, // skip whitespace on input left = 0x0002, // left-adjust output right = 0x0004, // right-adjust output internal = 0x0008, // padding after sign or base indicator dec = 0x0010, // decimal conversion oct = 0x0020, // octal conversion hex = 0x0040, // hexidecimal conversion showbase = 0x0080, // use base indicator on output showpoint = 0x0100, // force decimal point (floating output) uppercase = 0x0200, // upper-case hex output showpos = 0x0400, // add '+' to positive integers scientific= 0x0800, // use 1.2345E2 floating notation fixed = 0x1000, // use 123.45 floating notation unitbuf = 0x2000, // flush all streams after insertion stdio = 0x4000 // flush stdout, stderr after insertion }; public: // exported functions .sp .5v // format-related functions long flags(); long flags(long bits); long setf(long setbits, long field); long setf(long setbits); long unsetf(long unsetbits); int width(); int width(int len); char fill(); char fill(char ch); int precision(int len); int precision(); int skip(int doskip); // obsolete .sp .5v // state-related functions int rdstate(); int eof(); int fail(); int bad(); int good(); void clear(int state=0); .sp .5v // other functions ostream* tie(ostream* tiedstream); ostream* tie(); streambuf* rdbuf(); static long bitalloc(); static int xalloc(); long & iword(int index); void* & pword(int index); static void sync_with_stdio(); public: // exported operator and conversion functions operator void* (); int operator ! (); public: // exported constructor, destructor unsafe_ios(streambuf* sbp); virtual ~unsafe_ios(); public: // exported data members static const long basefield; // dec | oct | hex static const long adjustfield; // left | right | internal static const long floatfield; // scientific | fixed .sp .5v protected: // protected function void init(streambuf* sbp); // protected constructor unsafe_ios(); void setstate (int); static void (*stdioflush)(); .sp .5v private: // private members to prevent copying unsafe_ios(unsafe_ios&); void operator= (unsafe_ios&); }; class ios : virtual public unsafe_ios, public stream_MT { public: // format-related functions long flags(); long flags(long); long setf(long setbits, long field); long setf(long); long unsetf(long); int width(); int width(int); char fill(); char fill(char); int precision(); int precision(int); .sp .5v // state-related functions int rdstate(); int eof(); int fail(); int bad(); int good(); void clear(int state =0); .sp .5v // other functions ostream* tie(); ostream* tie(ostream*); streambuf* rdbuf(); static long bitalloc(); static int xalloc(); long& iword(int); void* & pword(int); static void sync_with_stdio(); public: // exported operator and conversion functions operator void*(); int operator!(); public: // exported operator and conversion functions ios(streambuf* sbp); virtual ~ios(); protected: init(streambuf* sbp); ios(); setstate(int); static void (*stdioflush)(); protected: static stream_rmutex static_mutlock; static int mutex_init_count; private: ios(ios&); void operator=(ios&) ; }; .sp .5v // Predefined manipulators unsafe_ostream& endl(unsafe_ostream&); unsafe_ostream& ends(unsafe_ostream&); unsafe_ostream& flush(unsafe_ostream&); ostream& endl(ostream&); ostream& ends(ostream&); ostream& flush(ostream&); unsafe_ios& dec(unsafe_ios&); unsafe_ios& hex(unsafe_ios&); unsafe_ios& oct(unsafe_ios&); ios& dec(ios&); ios& hex(ios&); ios& oct(ios&); unsafe_istream& ws(unsafe_istream&); istream& ws(istream&); .ft R .fi .\" .SH DESCRIPTION Class .B ios is a virtual base class of all stream objects. It provides the basic state and formatting data for a stream. Several enumerations are defined, and a large collection of functions. These are described below. .IX iostreams "class ios" .IX iostreams "error states" .IX iostreams "format control" .IX iostreams "manipulators" .\" .PP Class .BR unsafe_ios implements all of the functionality of this class. Class .BR ios is a "wrapper" class that implements mutex locks around each of the member functions of .BR unsafe_ios to protect against access by multiple threads. Use of the protected class does not guarantee mt-safety, however; for more information on making your application mt-safe, see the .IR "C++ Library Reference Chapter 4, "Using Classic \fIiostream\fR in a Multithreaded Environment." .PP .SS Enumerations .TP .B io_state Member functions use these enumerations to keep track of the error state of the stream. See also the ``Error States'' section below for how to test these bits. .B io_state is really a collection of bits, as follows: .in +.5i .ti -.5i .B goodbit .br This ``bit'' is really the absence of any error bits, and indicates that the stream is in a good state. .ti -.5i .B eofbit .br This bit is normally set when end of file has been reached during an extraction. It is not set as the result of a succesful extraction reaching end of file, but when end of file is reached while attempting further extractions. ``End of file'' in this sense is an abstraction as defined by the .B streambuf associated with the stream. Normally this bit is not set for output streams. .ti -.5i .B failbit .br This bit is set when an attempted extraction or conversion has failed, usually due to unexpected characters. Further attempted extractions will fail until this bit is cleared, to prevent running on after improper input. Usually the stream is still usable, and extraction may be continued after clearing the bit and dealing with the unexpected input. .ti -.5i .B badbit .br This bit indicates that some operation on the associated streambuf has failed. Typically, attempting further operations will not succeed, even after clearing the bit. Example situations would be an output error, or immediate end of file on an attempted input operation. .ti -.5i .B hardfail .br This bit is reserved to the implementation to indicate that the stream cannot be further used. Typically it represents a hardware failure of some kind. The bit cannot be cleared by any publicly-accessible function. .in -.5i .TP .B open_mode These enumerations are described in .BR fstream (3CC4), under the description of function .BR open() . .TP .B seek_dir These enumerations are described in .BR sbufpub (3CC4), under the description of function .BR seekoff() . .TP .I "formatting flags" Member functions use these enumerations of anonymous type to control input and output formatting. See the "Format Control" section below. .\" .SS "Constructors and Assignment" .TP .B ios(sbp) The streambuf pointed to by .B sbp becomes the streambuf associated with the .B ios being constructed. The pointer must not be null. .TP .BI ios() " // protected" .in -.5i .BI init(sbp) " // protected" .in +.5i Historically, a virtual base class required a default constructor (one with no arguments), because there used to be no way to pass arguments to a constructor for a virtual base class. Class .B ios therefore has a default constructor and a separate intialization function taking a pointer to a .BR streambuf . A derived class uses the protected constructor .B ios() by default, and calls initialization function .BR init(streambuf*) . The argument to .B init points to the streambuf to be associated with the .B ios being constructed, and must not be null. Example: .in +.5i .nf .ft B class istream : virtual public ios { ... }; istream::istream(streambuf* s) { ios::init(s); // ... } .ft R .fi .in -.5i .TP .BI ios(iosref) " // private" .in -.5i .BI stream2=stream1 " // private" .in +.5i The copy constructor and assignment operator are private to prevent copying of .B ios objects, since the effect of such copying is not well defined. Usually you want to copy a pointer to the object, or pass a reference to a function. .\" .SS "Error States" .LP Several functions enable testing and adjusting the error state bits, as follows. .TP .B "int i = s.rdstate()" Returns the error state bits of stream \fBs\fR as an \fBint\fR. .TP .B "s.clear(state)" Stores its \fBint\fR parameter as the error state of stream \fBs\fR. The value of \fBstate\fR should be derived only from the return of \fBrdstate\fR and/or combinations of the \fBio_state\fR bits. To clear only one bit in the stream state, use something like .B "s.clear(~ios::failbit\ &\ s.rdstate());" .TP .B "int i = s.good()" Returns non-zero if the error state is good; that is, if no bits are set. Otherwise, returns zero. In particular, returns zero if \fBeofbit\fR is set. .TP .B "int i = s.eof()" Returns non-zero if the \fBeofbit\fR is set, zero otherwise. .TP .B "int i = s.fail()" Returns non-zero if any of .BR failbit ", " badbit ", or " hardfail is set, zero otherwise. .TP .B "int i = s.bad()" Returns non-zero if either of .BR badbit " or " hardfail is set, zero otherwise. .\" .SS "Other Status Testing" .LP It is often convenient to be able to test the state of a stream directly. Since typical insertion and extraction operators return a reference to the stream, you can test the return values of the operations. Two operators are defined to permit this testing. .TP .B "operator void* ()" You may use an explict cast of a stream to \fBvoid*\fR, or use a stream in a boolean context to test its state. The result is 0 if any of .BR failbit ", " badbit ", or " hardfail is set. The result is a non-zero pointer if the stream is in a good or \fBeof\fR state. Examples: .nf .in +.5i .ft B if( cout ) ... // next output will probably succeed if( cin >> x ) ... // input to x succeeded .ft R .in -.5i .fi .TP .B "operator ! ()" This operator provides the inverse of the above testing. The result is non-zero if any of .BR failbit ", " badbit ", or " hardfail is set, zero otherwise. Examples: .nf .in +.5i .ft B if( ! cout ) ... // output will not succeed if( ! (cin >> x) ) ... // input to x failed .ft R .in -.5i .fi .\" .SS "Format Control" .LP A \fBios\fR maintains a .I "format state" which is controlled by formatting flags, and the three functions .BR fill() ", " width() ", and " precision() . The formatting flags are a collection of bits described below, declared as enumerations of an anonymous type. These format state bits are kept in a \fBlong int\fR and may be manipulated independently via two versions of the \fBflags()\fR function. .LP The formatting flags may be set and cleared independent of other operations. They change only by explicit programmer action. The flags are as follows: .TP .B skipws If this flag is set, formatted extractors will skip leading whitespace; otherwise, leading whitespace is not skipped. This flag is set by default, allowing free-format input text. Unformatted extractors do not examine this flag. .TP .B left .ti -.5i .B right .ti -.5i .B internal .br These flags control how padding is inserted during formatted operations. At most one of these three flags may be set at one time. The three flags may be addressed as a unit by the static member .BR ios::adjustfield . If \fBleft\fR is set, the value is left-adjusted in its field width, meaning that padding is added on the right. If \fBright\fR is set, the value is right-adjusted in its field width, meaning that padding is added on the left. If \fBinternal\fR is set, padding is added after any leading base or sign field, and before the value. The default (none of the flags set) is \fBright\fR. The fill character used for padding defaults to the space character, and may be set with the \fBfill\fR function. The amount of padding is determined by the field width as set by the \fBwidth\fR function. See also .BR manip (3CC4). .TP .B dec .ti -.5i .B oct .ti -.5i .B hex .br These flags control the conversion base of integer data. At most one of these three flags may be set at one time. The three flags may be addressed as a unit by the static member .BR ios::basefield . Conversions are done in decimal (base 10) if \fBdec\fR is set, in octal (base 8) if \fBoct\fR is set, or in hexadecimal (base 16) if \fBhex\fR is set. If none of the flags is set, insertions are done in decimal, and extractions are converted according to the C++ rules for representing integer constants. That is, a leading ``0x'' or ``0X'' will result in hex conversion, a leading `0' will result in octal conversion, and a leading `1' through `9' will result in decimal conversion for extraction. The default is none of these bits set. The manipulators .BR dec ", " oct ", and " hex may also be used to set the conversion base as described below in section ``Predefined Manipulators''. .TP .B showbase If this flag is set, insertions of converted integral values will be in the form used for representing C++ integer constants. That is, octal values will begin with a leading `0', and hexadecimal values will begin with a leading ``0x'' or ``0X''. (See ``\fBuppercase\fR'' below.) The default is unset. .TP .B showpos If this flag is set, a plus sign (`+') will be added to insertions of converted positive decimal values (including floating-point). The default is unset. .TP .B uppercase If this flag is set, an uppercase `X' will be used in insertions of converted hexidecimal values when \fBshowbase\fR is set, and an uppercase `E' will be used for floating-point conversions. Otherwise, lowercase `x' and `e' will be used, respectively. The default is unset. .TP .B fixed .ti -.5i .B scientific .br These flags control the type of conversion used when floating-point values are converted for insertion. The two flags may be addressed as a unit by the static member .BR ios::floatfield . The rules followed for conversion are generally the same as for the C stdio function \fBprintf\fR. (See \fBprintf\fR(3V).) If \fBscientific\fR is set, `e' format is used. If \fBfixed\fR is set, `f' format is used. If neither is set, `g' format is used. (See also \fBuppercase\fR above.) The value set by \fBwidth\fR, if any, is used as the \fBprintf\fR field width specification. The value set by \fBprecision\fR, if any, is used as the \fBprintf\fR precision specification. .TP .B showpoint If this flag is set, trailing zeros, or a trailing decimal point, will appear in the conversion of floating-point values. The default is to truncate trailing zeros or a trailing decimal point. .TP .B unitbuf If an output stream is buffered, the buffer is flushed when it fills, or when it is explicitly flushed. This can result in delayed output, or lost output if the program should crash. A stream may be unbuffered, eliminating delays and lost output, but at the cost of a system call per character output. If the \fBunitbuf\fR is set, the buffer will be flushed after each complete insertion. \fIUnit buffering\fR is thus a compromise, providing frequent output at lower cost than unbuffered output, and not requiring extra \fBflush\fR calls in the program source. In particular, unit buffering may be turned on and off at selected places in the code without changing any other source code. By default, this flag is not set. .TP .B stdio This flag causes the C stdio files \fBstdout\fR and \fBstderr\fR to be flushed after each insertion in the stream. This may be useful when C stdio on the standard files is mixed with iostreams on other files. By default, this flag is not set. .LP The format control functions are as follows: .TP .B "long theflags = s.flags()" Returns the current formatting flags of stream \fBs\fR in a \fBlong\fR. .TP .B "long oldflags = s.flags(newflags)" Uses the \fBlong\fR value of \fBnewflags\fR to replace all the formatting flags in stream \fBs\fR. Returns the previous formatting flags in a \fBlong\fR. .TP .B "long oldflags = s.setf(newflags)" Each bit which is set in the \fBlong\fR value \fBnewflags\fR is set in the formatting flags of stream \fBs\fR. The remaining formatting flags are unaffected. Returns the previous formatting flags in a \fBlong\fR. Note the \fBflags\fR function replaces all the flag bits, while the \fBsetf\fR function sets just those bits which are specified. This version of \fBsetf\fR is most useful for setting a flag which is not part of a group. See the second form of this function below for setting one of a group of flags. .TP .B "long oldflags = s.setf(newflags, field)" The bits which are set in the \fBlong\fR value \fBfield\fR mark the formatting flags which are replaced by the corresponding bits in the \fBlong\fR value \fBnewflags\fR. Returns the previous value of the designated flags. Typically, one of the constants .BR basefield ", " adjustfield ", or " floatfield is used as the value of \fBfield\fR. Example \- set to left-justification, output a value, and restore the previous justification: .in +.5i .nf .ft B long oldadjust = cout.setf(ios::left, ios::adjustfield); cout << data; cout.setf(oldadjust, ios::adjustfield); .ft R .fi .in -.5i This technique ensures that only one of the \fBadjustfield\fR bits is ever set, and allows convenient restoration of the previous status. Using zero for the new value of the field will clear just those flags. Example \- clear the integer conversion base to the default state: .ti +.5i .B "cout.setf(0, ios::basefield);" .br See also the manipulators \fBsetiosflags\fR and \fBresetiosflags\fR in \fBmanip\fR(3CC4). .TP .B "long oldflags = s.unsetf(newflags)" Each bit which is set in the \fBlong\fR value \fBnewflags\fR is unset in the formatting flags of stream \fBs\fR. The remaining formatting flags are unaffected. Returns the previous formatting flags in a \fBlong\fR. Note the \fBsetf\fR function \fIsets\fR corresponding flag bits, while the \fBunsetf\fR function \fIclears\fR them. See also the manipulator \fBresetiosflags\fR in \fBmanip\fR(3CC4) .TP .B "char thefill = s.fill()" Returns the current fill character of stream \fBs\fR. The fill character is used for padding an insertion to the designated field width. This release supports only single-byte characters for \fBfill\fR. See the discussion above for .BR left ", " right ", and " internal . .TP .B "char oldfill = s.fill(newfill)" Sets the fill character of stream \fBs\fR to \fBnewfill\fR and returns the old fill character. The default fill character is the space. See also the manipulator \fBsetfill\fR in \fBmanip\fR(3CC4). .TP .B "int theprec = s.precision()" Returns the current ``precision'' format state of stream \fBs\fR. It controls the number of significant digits converted in floating-point insertions. See the discussion above for .BR scientific " and " fixed . .TP .B "int oldprec = s.precision(newprec)" Sets the ``precision'' format state of stream \fBs\fR to \fBnewprec\fR, and returns the old value. The default value is 6. See also the manipulator \fBsetprecision\fR in \fBmanip\fR(3CC4). .TP .B "int thewidth = s.width()" Returns the current ``field width'' format state of stream \fBs\fR. If the field width is zero, inserters will insert only the characters necessary to represent the value being inserted. If the field width is greater than the number of characters needed, the field will be padded with the fill character to the specified width, as described above. If the field width is less than the number of characters needed, the width will be extended. The field width represents the minimum field width; it cannot be used to provide truncation to a maximum field width. For wide character output the width is still measured in characters, not in bytes. .TP .B "int oldwidth = s.width(newwidth)" Sets the ``field width'' format state of stream \fBs\fR to \fBnewwidth\fR, and returns the old value. The default value is 0. The field width is reset to zero automatically after every formatted insertion or extraction. It must therefore be reset for each operation requiring a field width. See also the manipulator \fBsetw\fR in \fBmanip\fR(3CC4). .\" .SS "User-defined Format Flags" .LP User-defined format flags and variables are provided for derived classes which may need their own. Once allocated for a class, the flags and variables are reserved for the duration of the program; several independent classes may allocate their own flags and variables without conflict. .TP .B "long thebit = ios::bitalloc()" This static member function returns a \fBlong\fR with one previously unallocated flag bit set. This value may then be used as a flag, for example, in calls to \fBsetf\fR, for class-specific purposes. At least 16 bits are available for allocation. When no bits are available, this function returns zero. .TP .B "int index = ios::xalloc()" This static member function returns a previously unused index into an array of \fIwords\fR. A \fIword\fR is big enough to contain a \fBlong\fR or a \fBvoid*\fR. This index may then be used with functions .BR iword " or " ipword to get a reference to a reserved status variable. .TP .B "long theword = s.iword(i)" .in -.5i .B "void* theptr = s.ipword(i)" .in +.5i When \fBi\fR is an index value returned by a call to \fBios::xalloc\fR, these functions return a reference to the \fBi\fRth user-defined status variable (word) for class \fBs\fR. Function \fBiword\fR returns the reference typed as a \fBlong\fR, and function \fBipword\fR returns the reference typed as a \fBvoid*\fR. Note: Do not depend on the returned reference being stable for an indefinite period. In particular, any call to \fBxalloc()\fR may invalidate a previous reference. .\" .SS "Miscellaneous Functions" .LP .TP .B "streambuf* sbp = s.rdbuf()" Returns a pointer to the \fBstreambuf\fR associated with the stream. This is part of the construction of a stream, and the buffer class object is not normally changed. This function may be used to get at \fBstreambuf\fR functions directly, given a stream object. .TP .B "ostream* oldosp = s.tie(osp)" A stream may be ``tied'' to one \fBostream\fR, kept track of by the ``tie'' stream variable. Whenever a stream needs to acquire more input or flush its output, the tied stream, if any, is flushed first. For example, \fBcin\fR is initially tied to \fBcout\fR, so that pending output, such as a prompt, will be flushed before new input is attempted. This function sets the tie variable of stream \fBs\fR to the \fBostream\fR pointed to by input parameter \fBosp\fR, and returns the old value of the tie variable. The sequence .in +.5i .nf .B "ostream* oldosp = s.tie(0);" .I "... do something ..." .B "s.tie(oldosp);" .fi .in -.5i will untie a stream while some work is done, then restore the previous tie. .TP .B "ostream* theosp = s.tie()" Returns the current value of the ``tie'' variable. (See above.) .TP .B "ios::sync_with_stdio()" If C stdio and C++ stream operations are performed on the \fIsame\fR standard file, synchronization problems will occur. Since each style of I/O will have its own buffering, I/O will not occur in the order of program execution. To solve this synchronization problem, call this static function prior to doing any I/O to any of the standard streams .BR cin ", " cout ", " .BR cerr ", or " clog . This function resets the standard streams to use \fBstdiobuf\fRs. I/O via stdio and streams will then be synchronized. There is a substantial performance degradation compared to using just buffered stream I/O or just buffered stdio. See .BR stdiobuf (3CC4). Note: \fBsync_with_stdio\fR is needed only when doing I/O to the \fIsame\fR standard input, output, or error file. You may use exclusively stdio input functions on \fBstdin\fR and exclusively stream output functions on \fBcout\fR with no difficulty. .\" .SS "Predefined Manipulators" .LP A \fImanipulator\fR may be used apparently as an inserted or extracted object, but really only changes the state of the stream. See .BR manip (3CC4) for more information. Several manipulators are predefined for use with streams. .TP .B "s >> dec" .in -.5i .B "s << dec" .in +.5i These set the conversion base of stream \fBs\fR to 10. .TP .B "s >> oct" .in -.5i .B "s << oct" .in +.5i These set the conversion base of stream \fBs\fR to 8. .TP .B "s >> hex" .in -.5i .B "s << hex" .in +.5i These set the conversion base of stream \fBs\fR to 16. .TP .B "s >> ws" This extracts and discards whitespace from stream \fBs\fR. See .BR istream (3CC4). .TP .B "s << endl" Inserts a newline into stream \fBs\fR and flushes the stream. See .BR ostream (3CC4). .TP .B "s << ends" Inserts a null character (`\\0') into stream \fBs\fR to end the string. See .BR strstream (3CC4). .TP .B "s << flush" Flushes the stream \fBs\fR. See .BR ostream (3CC4). .LP Additional manipulators become available when you include \fB\fR. See .BR manip (3CC4) .\" .SH "SEE ALSO" .LP .na .BR ios.intro (3CC4), .BR filebuf (3CC4), .BR fstream (3CC4), .BR istream (3CC4), .BR manip (3CC4), .BR ostream (3CC4), .BR printf (3V) .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 ????