.\" ident @(#)ios_base.3 .\" Standard Template Library .\" $$RW_INSERT_HEADER "slyrs.man" .TH ios_base 3C++ "02 Apr 1998" "Rogue Wave Software" "-" .ce2 Standard C++ Library Copyright 1998, Rogue Wave Software, Inc. .SH NAME \f2ios_base\fP \ - Defines member types and maintains data for classes that inherit from it. .SH SYNOPSIS .RE .RS 0 #include .br class ios_base; .SH DESCRIPTION The class_ios_base defines several member types: .HP .5i \(bu A class \f2failure\fP derived from \f2exception\fP. .HP .5i \(bu A class \f2Init.\fP .HP .5i \(bu Three bitmask types: \f2fmtflags\fP, \f2iostate\fP, and \f2openmode.\fP .HP .5i \(bu Two enumerated types: \f2seekdir\fP and \f2event.\fP .HP 0 It maintains several kinds of data: .HP .5i \(bu Control information that influences how to interpret (format) input sequences and how to generate (format) output sequences. .HP .5i \(bu Locale object used within the stream classes. .HP .5i \(bu Additional information that is stored by the program for its private use. .HP 0 .SH INTERFACE .br class ios_base { .RE .RS 2 .RE .RS 0 public: .br .RE .RS 2 class failure : public exception { .RE .RS 6 .RE .RS 5 public: .RE .RS 0 .RE .RS 9 explicit failure(const string& msg); .br virtual ~failure() throw(); .br virtual const char* what() const throw(); .RE .RS 4 }; .RE .RS 0 .RE .RS 2 typedef int fmtflags; .RE .RS 0 .RE .RS 2 enum fmt_flags { .RE .RS 19 boolalpha = 0x0001, .br dec = 0x0002, .br fixed = 0x0004, .br hex = 0x0008, .br internal = 0x0010, .br left = 0x0020, .br oct = 0x0040, .br right = 0x0080, .br scientific = 0x0100, .br showbase = 0x0200, .br showpoint = 0x0400, .br showpos = 0x0800, .br skipws = 0x1000, .br unitbuf = 0x2000, .br uppercase = 0x4000, .br adjustfield = left | right | internal, .br basefield = dec | oct | hex, .br floatfield = scientific | fixed .RE .RS 18 }; .RE .RS 0 .RE .RS 2 typedef int iostate; .RE .RS 0 .RE .RS 2 enum io_state { .RE .RS 18 goodbit = 0x00, .br badbit = 0x01, .br eofbit = 0x02, .br failbit = 0x04 .RE .RS 17 }; .RE .RS 0 .RE .RS 2 typedef int openmode; .RE .RS 0 .RE .RS 2 enum open_mode { .RE .RS 19 app = 0x01, .br binary = 0x02, .br in = 0x04, .br out = 0x08, .br trunc = 0x10, .br ate = 0x20 .RE .RS 18 }; .RE .RS 0 .RE .RS 2 typedef int seekdir; .RE .RS 0 .RE .RS 2 enum seek_dir { .RE .RS 20 beg = 0x0, .br cur = 0x1, .br end = 0x2 .RE .RS 17 }; .RE .RS 0 .br .RE .RS 2 class Init; .RE .RS 4 .RE .RS 2 fmtflags flags() const; .br fmtflags flags(fmtflags fmtfl); .br fmtflags setf(fmtflags fmtfl); .br fmtflags setf(fmtflags fmtfl, fmtflags mask); .br void unsetf(fmtflags mask); .RE .RS 0 .RE .RS 2 streamsize precision() const; .br streamsize precision(streamsize prec); .br streamsize width() const; .br streamsize width(streamsize wide); .RE .RS 0 .RE .RS 2 locale imbue(const locale& loc); .br locale getloc() const .RE .RS 0 .RE .RS 2 static int xalloc(); .br long& iword(int index); .br void*& pword(int index); .RE .RS 0 .RE .RS 2 ios_base& copyfmt(const ios_base& rhs); .RE .RS 0 .RE .RS 2 enum event { .RE .RS 19 erase_event = 0x0001, .br imbue_event = 0x0002, .br copyfmt_event = 0x004 .RE .RS 18 }; .RE .RS 0 .RE .RS 2 typedef void (*event_callback) (event, ios_base&, .RE .RS 16 int index); .RE .RS 2 void register_callback(event_callback fn, int index); .RE .RS 0 .RE .RS 2 bool synch_with_stdio(bool sync = true); .br bool is_synch(); .RE .RS 0 .RE .RS 1 protected: .RE .RS 0 .RE .RS 2 ios_base(); .br virtual ~ios_base(); .RE .RS 0 .RE .RS 1 private: .RE .RS 0 .RE .RS 2 union ios_user_union { .RE .RS 26 long lword; .br void* pword; .RE .RS 24 }; .RE .RS 0 .RE .RS 2 union ios_user_union *userwords_; .RE .RS 0 }; .br .br ios_base& boolalpha(ios_base&); .br ios_base& noboolalpha(ios_base&); .br ios_base& showbase(ios_base&); .br ios_base& noshowbase(ios_base&); .br ios_base& showpoint(ios_base&); .br ios_base& noshowpoint(ios_base&); .br ios_base& showpos(ios_base&); .br ios_base& noshowpos(ios_base&); .br ios_base& skipws(ios_base&); .br ios_base& noskipws(ios_base&); .br ios_base& uppercase(ios_base&); .br ios_base& nouppercase(ios_base&); .br ios_base& internal(ios_base&); .br ios_base& left(ios_base&); .br ios_base& right(ios_base&); .br ios_base& dec(ios_base&); .br ios_base& hex(ios_base&); .br ios_base& oct(ios_base&); .br ios_base& fixed(ios_base&); .br ios_base& scientific(ios_base&); .br ios_base& unitbuf(ios_base&); .br ios_base& nounitbuf(ios_base&); .SH TYPES .br fmtflags .RE .RS 3 The type \f2fmtflags\fP is a bitmask type. Setting its elements has the following effects: .HP 10 \f2showpos\fP\f2 \fPGenerates a + sign in non-negative generated numeric output. .HP 0 .HP 11 \f2showbase\fP\f2 \fPGenerates a prefix indicating the numeric base of generated integer output .HP 0 .HP 12 \f2uppercase\fP\f2 \fPReplaces certain lowercase letters with their uppercase equivalents in generated output .HP 0 .HP 12 \f2showpoint\fP\f2 \fPGenerates a decimal-point character unconditionally in generated floating-point output .HP 0 .HP 12 \f2boolalpha\fP\f2 \fPInserts and extracts bool type in alphabetic format .HP 0 .HP 10 \f2unitbuf\fP\f2 \fPFlushes output after each output operation .HP 0 .HP 11 \f2internal\fP\f2 \fPAdds fill characters at a designated internal point in certain generated output. If no such point is designated, it's identical to \f2right\fP. .HP 0 .HP 7 \f2left\fP\f2 \fPAdds fill characters on the right (final positions) of certain generated output .HP 0 .HP 8 \f2right\fP\f2 \fPAdds fill characters on the left (initial positions) of certain generated output .HP 0 .HP 6 \f2dec\fP\f2 \fPConverts integer input or generates integer output in decimal base .HP 0 .HP 6 \f2hex\fP\f2 \fPConverts integer input or generates integer output in hexadecimal base .HP 0 .HP 6 \f2oct\fP\f2 \fPConverts integer input or generates integer output in octal base .HP 0 .HP 8 \f2fixed\fP\f2 \fPGenerates floating-point output in fixed-point notation .HP 0 .HP 13 \f2scientific\fP\f2 \fPGenerates floating-point output in scientific notation .HP 0 .HP 9 \f2skipws \fPSkips leading white space before certain input operation. .HP 0 .RE .br iostate .RS 3 The type \f2iostate\fP is a bitmask type. Setting its elements has the following effects: .HP 9 \f2badbit \fPIndicates a loss of integrity in an input or output sequence. .HP 0 .HP 9 \f2eofbit \fPIndicates that an input operation reached the end of an input sequence. .HP 0 .HP 10 \f2failbit \fPIndicates that an input operation failed to read the expected characters, or that an output operation failed to generate the desired characters. .HP 0 .RE .br openmode .RS 3 The type \f2openmode\fP is a bitmask type. Setting its elements has the following effects: .HP 6 \f2app \fPSeeks to the end before writing. .HP 0 .HP 6 \f2ate \fPOpens and seeks to the end immediately after opening. .HP 0 .HP 9 \f2binary \fPPerforms input and output in binary mode. .HP 0 .HP 5 \f2in \fPOpens for input. .HP 0 .HP 6 \f2out \fPOpens for output. .HP 0 .HP 8 \f2trunc \fPTruncates an existing stream when opening. .HP 0 .RE .br seekdir .RS 3 The type \f2seekdir\fP is a bitmask type. Setting its elements has the following effects: .HP 6 \f2beg \fPRequests a seek relative to the beginning of the stream. .HP 0 .HP 6 \f2cur \fPRequests a seek relative to the current position within the sequence. .HP 0 .HP 6 \f2end \fPRequests a seek relative to the current end of the sequence. .HP 0 .RE .br event_callback .RS 3 The type \f2event_callback\fP is the type of the callback function used as a parameter in the function \f2register_callback\fP. These functions allow you to use the \f2iword\fP, \f2pword\fP mechanism in an exception-safe environment. .RE .SH PUBLIC CONSTRUCTORS .br ios_base(); .RE .RS 3 The \f2ios_base\fP members have an indeterminate value after construction. .RE .SH PUBLIC DESTRUCTORS .br virtual .br ~ios_base(); .RE .RS 3 Destroys an object of class \f2ios_base\fP. Calls each registered callback pair \f2(fn, index)\fP as \f2(*fn)(erase_event,*this, index)\fP at such a time that any \f2ios_base\fP member function called from within \f2fn\fP has well-defined results. .RE .SH PUBLIC MEMBER FUNCTIONS .br ios_base& .br copyfmt(const ios_base& rhs); .RE .RS 3 Assigns to the member objects of \f2*this\fP the corresponding member objects of \f2rhs\fP. The contents of the union pointed to by \f2pword\fP and \f2iword\fP are copied, not the pointers themselves. Before copying any part of \f2rhs\fP, calls each registered callback pair \f2(fn,index)\fP as \f2(*fn)(erase_even,*this, index)\fP. After all parts have been replaced, calls each callback pair that was copied from \f2rhs\fP as \f2(*fn)(copy_event,*this,index)\fP. .RE .br fmtflags .br flags() const; .RE .RS 3 Returns the format control information for both input and output. .RE .br fmtflags .br flags(fmtflags fmtfl); .RE .RS 3 Saves the format control information, then sets it to \f2fmtfl\fP and returns the previously saved value. .RE .br locale .br getloc() const; .RE .RS 3 Returns the imbued locale, which is used to perform locale-dependent input and output operations. The default locale, \f2locale::locale()\fP, is used if no other locale object has been imbued in the stream by a call to the \f2imbue\fP function. .RE .br locale .br imbue(const locale& loc); .RE .RS 3 Saves the value returned by \f2getloc()\fP, then assigns \f2loc\fP to a private variable and calls each registered callback pair \f2(fn, index)\fP as \f2(*fn)(imbue_event,*this, index)\fP. It then returns the previously saved value. .RE .br bool .br is_sync(); .RE .RS 3 Returns \f2true\fP if the C++ standard streams and the standard C streams are synchronized. Otherwise returns \f2false\fP. This function is not part of the C++ standard. .RE .br long& .br iword(int idx); .RE .RS 3 Returns \f2userwords_[idx].iword\fP. If \f2userwords_\fP is a null pointer, allocates a union of \f2long\fP and \f2void*\fP of unspecified size and stores a pointer to its first element in \f2userwords_\fP. The function then extends the union pointed to by \f2userwords_\fP to include the element \f2userwords_[idx]\fP. Each newly allocated element of the union is initialized to zero. The reference returned may become invalid after another call to the object's \f2iword \fPor \f2pword\fP member with a different index, after a call to its \f2copyfmt\fP member, or when the object is destroyed. .RE .br streamsize .br precision() const; .RE .RS 3 Returns the precision (number of digits after the decimal point) to generate on certain output conversions. .RE .br streamsize .br precision(streamsize prec); .RE .RS 3 Saves the precision, then sets it to \f2prec\fP and returns the previously saved value. .RE .br void*& .br pword(int idx); .RE .RS 3 Returns \f2userword_[idx].pword\fP. If \f2userwords_\fP is a null pointer, allocates a union of \f2long\fP and \f2void*\fP of unspecified size and stores a pointer to its first element in \f2userwords_\fP. The function then extends the union pointed to by \f2userwords_\fP to include the element \f2userwords_[idx]\fP. Each newly allocated element of the array is initialized to zero. The reference returned may become invalid after another call to the object's \f2pword\fP or \f2iword\fP member with a different index, after a call to its \f2copyfmt\fP member, or when the object is destroyed. .RE .br void .br register_callback(event_callback fn, int index); .RE .RS 3 Registers the pair \f2(fn, index)\fP such that during calls to \f2imbue()\fP, \f2copyfmt()\fP, or \f2~ios_base()\fP, the function \f2fn\fP is called with argument \f2index\fP. Functions registered are called when an event occurs, in opposite order of registration. Functions registered while a callback function is active are not called until the next event. Identical pairs are not merged; a function registered twice is called twice per event. .RE .br fmtflags .br setf(fmtflags fmtfl); .RE .RS 3 Saves the format control information, then sets it to \f2fmtfl\fP and returns the previously saved value. .RE .br fmtflags .br setf(fmtflags fmtfl, fmtflags mask); .RE .RS 3 Saves the format control information, then clears \f2mask\fP in \f2flags()\fP, sets \f2fmtfl & mask in flags()\fP and returns the previously saved value. .RE .br bool .br sync_with_stdio(bool sync = true); .RE .RS 3 When called with a \f2false\fP argument, allows the C++ standard streams to operate independently of the standard C streams, which greatly improves performance. When called with a \f2true\fP argument, restores the default synchronization. The return value of the function is the status of the synchronization at the time of the call. .RE .br void .br unsetf(fmtflags mask); .RE .RS 3 Clears \f2mask\fP in \f2flags()\fP. .RE .br streamsize .br width() const; .RE .RS 3 Returns the field width (number of characters) to generate on certain output conversions. .RE .br streamsize .br width(streamsize wide); .RE .RS 3 Saves the field width, then sets it to \f2wide\fP and returns the previously saved value. .RE .br static int .br xalloc(); .RE .RS 3 Returns the next static index that can be used with \f2pword\fP and \f2iword\fP. This is useful if you want to share data between several stream objects. .RE .SH CLASS FAILURE The class failure defines the base class for the types of all objects thrown as exceptions by functions in the iostreams library. It reports errors detected during stream buffer operations. .br explicit failure(const string& msg); .RE .RS 3 Constructs an object of class \f2failure\fP, initializing the base class with \f2exception(msg).\fP .RE .br const char* .br what() const; .RE .RS 3 Returns the message \f2msg\fP with which the exception was created. .RE .SH CLASS INIT The class Init describes an object whose construction ensures the construction of the eight objects declared in \f2\fP, which associate file stream buffers with the standard C streams. .SH NON-MEMBER FUNCTIONS .br ios_base& .br boolalpha(ios_base& str); .RE .RS 3 Calls \f2str.setf(ios_base::boolalpha)\fP and returns \f2str.\fP .RE .br ios_base& .br dec(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::dec, ios_base::basefield)\fP and returns\f2 str\fP. .RE .br ios_base& .br fixed(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::fixed, ios_base::floatfield)\fP and returns\f2 str\fP. .RE .br ios_base& .br hex(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::hex, ios_base::basefield)\fP and returns\f2 str\fP. .RE .br ios_base& .br internal(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::internal, ios_base::adjustfield)\fP and returns\f2 str\fP. .RE .br ios_base& .br left(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::left, ios_base::adjustfield) \fPand returns\f2 str\fP. .RE .br ios_base& .br noboolalpha(ios_base& str); .RE .RS 3 Calls \f2str.unsetf(ios_base::boolalpha)\fP and returns \f2str.\fP .RE .br ios_base& .br noshowbase(ios_base& str); .RE .RS 3 Calls\f2 str.unsetf(ios_base::showbase)\fP and returns\f2 str\fP. .RE .br ios_base& .br noshowpoint(ios_base& str); .RE .RS 3 Calls\f2 str.unsetf(ios_base::showpoint) \fPand returns\f2 str\fP. .RE .br ios_base& .br noshowpos(ios_base& str); .RE .RS 3 Calls\f2 str.unsetf(ios_base::showpos)\fP and returns\f2 str\fP. .RE .br ios_base& .br noskipws(ios_base& str); .RE .RS 3 Calls\f2 str.unsetf(ios_base::skipws)\fP and returns\f2 str\fP. .RE .br ios_base& .br nounitbuf(ios_base& str); .RE .RS 3 Calls\f2 str.unsetf(ios_base::unitbuf)\fP and returns\f2 str\fP. .RE .br ios_base& .br nouppercase(ios_base& str); .RE .RS 3 Calls\f2 str.unsetf(ios_base::uppercase)\fP and returns\f2 str\fP. .RE .br ios_base& .br oct(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::oct, ios_base::basefield)\fP and returns\f2 str\fP. .RE .br ios_base& .br right(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::right, ios_base::adjustfield)\fP and returns\f2 str\fP. .RE .br ios_base& .br scientific(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::scientific, ios_base::floatfield)\fP and returns\f2 str\fP. .RE .br ios_base& .br showbase(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::showbase)\fP and returns\f2 str\fP. .RE .br ios_base& .br showpoint(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::showpoint)\fP and returns\f2 str\fP. .RE .br ios_base& .br showpos(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::showpos)\fP and returns\f2 str\fP. .RE .br ios_base& .br skipws(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::skipws)\fP and returns\f2 str\fP. .RE .br ios_base& .br unitbuf(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::unitbuf)\fP and returns\f2 str\fP. .RE .br ios_base& .br uppercase(ios_base& str); .RE .RS 3 Calls\f2 str.setf(ios_base::uppercase)\fP and returns\f2 str\fP. .RE .SH SEE ALSO basic_ios(3C++), basic_istream(3C++), basic_ostream(3C++), char_traits(3C++) Working Paper for Draft Proposed International Standard for Information Systems--Programming Language C++, Section 27.4.2 .SH STANDARDS CONFORMANCE ANSI X3J16/ISO WG21 Joint C++ Committee