`<ios>`

ios · fpos · ios_base · locale · mbstate_t · streamoff · streampos · streamsize

boolalpha · dec · fixed · hex · internal · left · noboolalpha · noshowbase · noshowpoint · noshowpos · noskipws · nounitbuf · nouppercase · oct · right · scientific · showbase · showpoint · showpos · skipws · unitbuf · uppercase

Include the iostreams standard header <ios> to define several types and functions basic to the operation of iostreams. (This header is typically included for you by another of the iostreams headers. You seldom have occasion to include it directly.)

A large group of functions are manipulators. A manipulator declared in <ios> alters the values stored in its argument object of class ios_base. Other manipulators perform actions on streams controlled by objects of a type derived from this class, such as one of the classes istream or ostream. For example, noskipws(str) clears the format flag ios_base::skipws in the object str, which might be of one of these types.

You can also call a manipulator by inserting it into an output stream or extracting it from an input stream, thanks to some special machinery supplied in the classes derived from ios_base. For example:

istr >> noskipws;

calls noskipws(istr).

        // DECLARATIONS
typedef T1 streamoff;
typedef T2 streamsize;
class ios_base;
class ios;
class fpos;
class locale;
typedef T3 mbstate_t;
typedef fpos streampos;

        // MANIPULATORS
ios_base& boolalpha(ios_base& iosbase);
ios_base& noboolalpha(ios_base& iosbase);
ios_base& showbase(ios_base& iosbase);
ios_base& noshowbase(ios_base& iosbase);
ios_base& showpoint(ios_base& iosbase);
ios_base& noshowpoint(ios_base& iosbase);
ios_base& showpos(ios_base& iosbase);
ios_base& noshowpos(ios_base& iosbase);
ios_base& skipws(ios_base& iosbase);
ios_base& noskipws(ios_base& iosbase);
ios_base& unitbuf(ios_base& iosbase);
ios_base& nounitbuf(ios_base& iosbase);
ios_base& uppercase(ios_base& iosbase);
ios_base& nouppercase(ios_base& iosbase);
ios_base& internal(ios_base& iosbase);
ios_base& left(ios_base& iosbase);
ios_base& right(ios_base& iosbase);
ios_base& dec(ios_base& iosbase);
ios_base& hex(ios_base& iosbase);
ios_base& oct(ios_base& iosbase);
ios_base& fixed(ios_base& iosbase);
ios_base& scientific(ios_base& iosbase);
        // END OF DECLARATIONS

`ios`

bad · ios · char_type · clear · copyfmt · eof · exceptions · init · fail · good · imbue · init · int_type · narrow · off_type · operator! · operator void * · pos_type · rdbuf · rdstate · setstate · tie · traits_type · widen

class ios : public ios_base {
public:
    typedef char char_type;
    typedef char_traits traits_type;
    typedef char_traits::int_type int_type;
    typedef char_traits::pos_type pos_type;
    typedef char_traits::off_type off_type;
    explicit ios(streambuf *strbuf);
    virtual ~ios();
    operator void *() const;
    bool operator!() const;
    iostate rdstate() const;
    void clear(iostate state = goodbit);
    void setstate(iostate state);
    bool good() const;
    bool eof() const;
    bool fail() const;
    bool bad() const;
    iostate exceptions() const;
    iostate exceptions(iostate newexcept);
    ios& copyfmt(const ios& right);
    locale imbue(const locale& loc);
    char_type widen(char ch);
    char narrow(char_type ch, char dflt);
    char_type fill() const;
    char_type fill(char_type ch);
    ostream *tie() const;
    ostream *tie(ostream *newtie);
    streambuf *rdbuf() const;
    streambuf *rdbuf(streambuf *strbuf);
protected:
    void init(streambuf *strbuf);
    ios();
    ios(const facet&);     // not defined
    void operator=(const facet&) // not defined
        };

The class describes the storage and member functions common to both input streams (of class istream) and output streams (of class ostream). An object of class ios helps control a stream with elements of type char, also known as char_type, whose character traits are determined by the class char_traits.

An object of class ios stores:

a tie pointer to an object of type ostream
a stream buffer pointer to an object of type streambuf
formatting information
stream state information in a base object of type ios_base
a fill character in an object of type char_type

`ios::bad`

bool bad() const;

The member function returns true if rdstate() & badbit is nonzero.

`ios::ios`

explicit ios(streambuf *strbuf);
ios();

The first constructor initializes its member objects by calling init(strbuf). The second (protected) constructor leaves its member objects uninitialized. A later call to init must initialize the object before it can be safely destroyed.

`ios::char_type`

typedef char char_type;

The type is a synonym for char.

`ios::clear`

void clear(iostate state = goodbit);

The member function replaces the stored stream state information with state | (rdbuf() != 0 ? goodbit : badbit). If state & exceptions() is nonzero, it then throws an object of class failure.

`ios::copyfmt`

ios& copyfmt(const ios& right);

The member function reports the callback event erase_event. It then copies from right into *this the fill character, the tie pointer, and the formatting information. Before altering the exception mask, it reports the callback event copyfmt_event. If, after the copy is complete, state & exceptions() is nonzero, the function effectively calls clear with the argument rdstate(). It returns *this.

`ios::eof`

bool eof() const;

The member function returns true if rdstate() & eofbit is nonzero.

`ios::exceptions`

iostate exceptions() const;
iostate exceptions(iostate newexcept);

The first member function returns the stored exception mask. The second member function stores except in the exception mask and returns its previous stored value.

`ios::fail`

bool fail() const;

The member function returns true if rdstate() & (badbit | failbit) is nonzero.

`ios::fill`

char_type fill() const;
char_type fill(char_type ch);

The first member function returns the stored fill character. The second member function stores ch in the fill character and returns its previous stored value.

`ios::good`

bool good() const;

The member function returns true if rdstate() == goodbit (no state flags are set).

`ios::imbue`

locale imbue(const locale& loc);

The member function calls ios_base::imbue(loc). If rdbuf is not a null pointer, it also calls rdbuf()->pubimbue(loc). In any case, it returns the value returned by the call to ios_base::imbue.

`ios::init`

void init(streambuf *strbuf);

The member function stores values in all member objects, so that:

rdbuf() returns strbuf
tie() returns a null pointer
rdstate() returns goodbit if strbuf is nonzero; otherwise, it returns badbit
exceptions() returns goodbit
flags() returns skipws | dec
width() returns zero
precision() returns 6
fill() returns the space character
getloc() returns locale().
iword returns zero and pword returns a null pointer for all argument value

`ios::int_type`

typedef int int_type;

The type is a synonym for int.

`ios::narrow`

char narrow(char_type ch, char dflt);

The member function returns ch.

`ios::off_type`

typedef streamoff off_type;

The type is a synonym for streamoff.

`ios::operator void *`

operator void *() const;

The operator returns a null pointer only if fail().

`ios::operator!`

bool operator!() const;

The operator returns fail().

`ios::pos_type`

typedef streampos pos_type;

The type is a synonym for streampos.

`ios::rdbuf`

streambuf *rdbuf() const;
streambuf *rdbuf(streambuf *strbuf);

The first member function returns the stored stream buffer pointer.

The second member function stores strbuf in the stored stream buffer pointer and returns the previously stored value.

`ios::rdstate`

iostate rdstate() const;

The member function returns the stored stream state information.

`ios::setstate`

void setstate(iostate state);

The member function effectively calls clear(state | rdstate()).

`ios::tie`

ostream *tie() const;
ostream *tie(ostream *newtie);

The first member function returns the stored tie pointer. The second member function stores newtie in the tie pointer and returns its previous stored value.

`ios::traits_type`

typedef char_traits traits_type;

The type is a synonym for char_traits.

`ios::widen`

char_type widen(char ch);

The member function returns ch.

`boolalpha`

ios_base& boolalpha(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: boolalpha), then returns iosbase.

`dec`

ios_base& dec(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: dec, ios_base:: basefield), then returns iosbase.

`fixed`

ios_base& fixed(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: fixed, ios_base:: floatfield), then returns iosbase.

`fpos`

class fpos {
public:
    typedef mbstate_t St;
    fpos(streamoff off);
    fpos(St state, fpos_t filepos);
    St state() const;
    void state(St state);
    operator streamoff() const;
    streamoff operator-(const fpos& right) const;
    fpos& operator+=(streamoff off);
    fpos& operator-=(streamoff off);
    fpos operator+(streamoff off) const;
    fpos operator-(streamoff off) const;
    bool operator==(const fpos& right) const;
    bool operator!=(const fpos& right) const;
    };

The class describes an object that can store all the information needed to restore an arbitrary file-position indicator within any stream. An object of class fpos effectively stores at least two member objects:

a byte offset, of type streamoff
a conversion state, for use by an object of class filebuf, of type St, which is an unofficial synonym for mbstate_t

It can also store an arbitrary file position, for use by an object of class filebuf, of type fpos_t. For an environment with limited file size, however, streamoff and fpos_t may sometimes be used interchangeably. So the number of member objects stored may vary.

`fpos::fpos`

fpos(streamoff off);
fpos(St state, fpos_t filepos);

The first constructor stores the offset off, relative to the beginning of file. If off is -1, the resulting object represents an invalid stream position.

The second constructor stores the object state and a file position determined by filepos.

`fpos::operator!=`

bool operator!=(const fpos& right) const;

The member function returns !(*this == right).

`fpos::operator+`

fpos operator+(streamoff off) const;

The member function returns fpos(*this) += off.

`fpos::operator+=`

fpos& operator+=(streamoff off);

The member function adds off to the stored offset member object, then returns *this. For positioning within a file, the result is generally valid only for binary streams.

`fpos::operator-`

streamoff operator-(const fpos& right) const;
fpos operator-(streamoff off) const;

The first member function returns (streamoff)*this - (streamoff)right. The second member function returns fpos(*this) -= off.

`fpos::operator-=`

fpos& operator-=(streamoff off);

The member function returns fpos(*this) -= off. For positioning within a file, the result is generally valid only for binary streams.

`fpos::operator==`

bool operator==(const fpos& right) const;

The member function returns (streamoff)*this == (streamoff)right.

`fpos::operator streamoff`

operator streamoff() const;

The member function returns the stored offset member object, plus any additional offset stored as part of the fpos_t member object.

`fpos::state`

St state() const;
void state(St state);

The first member function returns the value stored in the St member object. The second member function stores state in the St member object.

`hex`

ios_base& hex(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: hex, ios_base:: basefield), then returns iosbase.

`internal`

ios_base& internal(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: internal, ios_base:: adjustfield), then returns iosbase.

`ios_base`

event · event_callback · failure · flags · fmtflags · getloc · imbue · Init · ios_base · iostate · iword · openmode · operator= · precision · pword · register_callback · seekdir · setf · streamoff · streampos · sync_with_stdio · unsetf · width · xalloc

class ios_base {
public:
    class failure;
    typedef T1 fmtflags;
    static const fmtflags boolalpha, dec, fixed, hex,
        internal, left, oct, right, scientific,
        showbase, showpoint, showpos, skipws, unitbuf,
        uppercase, adjustfield, basefield, floatfield;
    typedef T2 iostate;
    static const iostate badbit, eofbit, failbit,
        goodbit;
    typedef T3 openmode;
    static const openmode app, ate, binary, in, out,
        trunc;
    typedef T4 seekdir;
    typedef ::streamoff streamoff;
    typedef ::streampos streampos;
    static const seekdir beg, cur, end;
    enum event {
        copyfmt_event, erase_event,
        imbue_event};
    static const event copyfmt_event, erase_event,
        copyfmt_event;
    class Init;
    ios_base& operator=(const ios_base& right);
    fmtflags flags() const;
    fmtflags flags(fmtflags newfmtflags);
    fmtflags setf(fmtflags newfmtflags);
    fmtflags setf(fmtflags newfmtflags, fmtflags mask);
    void unsetf(fmtflags mask);
    streamsize precision() const;
    streamsize precision(streamsize newprecision);
    streamsize width() const;
    stramsize width(streamsize newwidth);
    locale imbue(const locale& loc);
    locale getloc() const;
    static int xalloc();
    long& iword(int idx);
    void *& pword(int idx);
    typedef void *(event_callback(event ev,
        ios_base& iosbase, int idx);
    void register_callback(event_callback pfn, int idx);
    static bool sync_with_stdio(bool newsync = true);
protected:
    ios_base();
    };

The class describes the storage and member functions common to both input and output streams. The class ios describes additional common features.

An object of class ios_base stores formatting information, which consists of:

format flags in an object of type fmtflags
an exception mask in an object of type iostate
a field width in an object of type int
a display precison in an object of type int
a locale object in an object of type locale
two extensible arrays, with elements of type long and void pointer

An object of class ios_base also stores stream state information, in an object of type iostate, and a callback stack.

`ios_base::event`

enum event {
    copyfmt_event, erase_event,
    imbue_event};

The type is an enumeration that describes an object that can store the callback event used as an argument to a function registered with register_callback. The distinct event values are:

copyfmt_event, to identify a callback that occurs near the end of a call to copyfmt, just before the exception mask is copied.
erase_event, to identify a callback that occurs at the beginning of a call to copyfmt, or at the beginning of a call to the destructor for *this.
imbue_event, to identify a callback that occurs at the end of a call to imbue, just before the function returns.

`ios_base::event_callback`

typedef void *(event_callback(event ev,
        ios_base& iosbase, int idx);

The type describes a pointer to a function that can be registered with register_callback. Such a function must not throw an exception.

`ios_base::failure`

class failure : public exception {
public:
    explicit failure(const string& what_arg) {
    };

The member class serves as the base class for all exceptions thrown by the member function clear in template class ios. The value returned by what() is what_arg.data().

`ios_base::flags`

fmtflags flags() const;
fmtflags flags(fmtflags newfmtflags);

The first member function returns the stored format flags. The second member function stores newfmtflags in the format flags and returns its previous stored value.

`ios_base::fmtflags`

typedef T1 fmtflags;
static const fmtflags boolalpha, dec, fixed, hex,
    internal, left, oct, right, scientific,
    showbase, showpoint, showpos, skipws, unitbuf,
    uppercase, adjustfield, basefield, floatfield;

The type is a bitmask type T1 that describes an object that can store format flags. The distinct flag values (elements) are:

boolalpha, to insert or extract objects of type bool as names (such as true and false) rather than as numeric values
dec, to insert or extract integer values in decimal format
fixed, to insert floating-point values in fixed-point format (with no exponent field)
hex, to insert or extract integer values in hexadecimal format
internal, to pad to a field width as needed by inserting fill characters at a point internal to a generated numeric field
left, to pad to a field width as needed by inserting fill characters at the end of a generated field (left justification)
oct, to insert or extract integer values in octal format
right, to pad to a field width as needed by inserting fill characters at the beginning of a generated field (right justification)
scientific, to insert floating-point values in scientific format (with an exponent field)
showbase, to insert a prefix that reveals the base of a generated integer field
showpoint, to insert a decimal point unconditionally in a generated floating-point field
showpos, to insert a plus sign in a non-negative generated numeric field
skipws, to skip leading white space before certain extractions
unitbuf, to flush output after each insertion
uppercase, to insert uppercase equivalents of lowercase letters in certain insertions

In addition, several useful values are:

adjustfield, internal | left | right
basefield, dec | hex | oct
floatfield, fixed | scientific

`ios_base::getloc`

locale getloc() const;

The member function returns the stored locale object.

`ios_base::imbue`

locale imbue(const locale& loc);

The member function stores loc in the locale object, then reports the callback event imbue_event. It returns the previous stored value.

`ios_base::Init`

class Init {
    };

The nested class describes an object whose construction ensures that the standard iostreams objects are properly constructed, even before the execution of a constructor for an arbitrary static object.

`ios_base::ios_base`

ios_base();

The (protected) constructor does nothing. A later call to ios::init must initialize the object before it can be safely destroyed. Thus, the only safe use for class ios_base is as a base class for template class ios.

`ios_base::iostate`

typedef T2 iostate;
static const iostate badbit, eofbit, failbit, goodbit;

The type is a bitmask type T2 that describes an object that can store stream state information. The distinct flag values (elements) are:

badbit, to record a loss of integrity of the stream buffer
eofbit, to record end-of-file while extracting from a stream
failbit, to record a failure to extract a valid field from a stream

In addition, a useful value is:

goodbit, no bits set

`ios_base::iword`

long& iword(int idx);

The member function returns a reference to element idx of the extensible array with elements of type long. All elements are effectively present and initially store the value zero. The returned reference is invalid after the next call to iword for the object, after the object is altered by a call to ios::copyfmt, or after the object is destroyed.

If idx is negative, or if unique storage is unavailable for the element, the function calls setstate(badbit) and returns a reference that might not be unique.

To obtain a unique index, for use across all objects of type ios_base, call xalloc.

`ios_base::openmode`

typedef T3 openmode;
static const openmode app, ate, binary, in, out, trunc;

The type is a bitmask type T3 that describes an object that can store the opening mode for several iostreams objects. The distinct flag values (elements) are:

app, to seek to the end of a stream before each insertion
ate, to seek to the end of a stream when its controlling object is first created
binary, to read a file as a binary stream, rather than as a text stream
in, to permit extraction from a stream
out, to permit insertion to a stream
trunc, to truncate an existing file when its controlling object is first created

`ios_base::operator=`

ios_base& operator=(const ios_base& right);

The operator copies the stored formatting information, making a new copy of any extensible arrays. It then returns *this. Note that the callback stack is not copied.

`ios_base::precision`

streamsize precision() const;
streamsize precision(streamsize newprecision);

The first member function returns the stored display precision. The second member function stores newprecision in the display precision and returns its previous stored value.

`ios_base::pword`

void *& pword(int idx);

The member function returns a reference to element idx of the extensible array with elements of type void pointer. All elements are effectively present and initially store the null pointer. The returned reference is invalid after the next call to pword for the object, after the object is altered by a call to ios::copyfmt, or after the object is destroyed.

If idx is negative, or if unique storage is unavailable for the element, the function calls setstate(badbit) and returns a reference that might not be unique.

To obtain a unique index, for use across all objects of type ios_base, call xalloc.

`ios_base::register_callback`

void register_callback(event_callback pfn, int idx);

The member function pushes the pair {pfn, idx} onto the stored callback stack. When a callback event ev is reported, the functions are called, in reverse order of registry, by the expression (*pfn)(ev, *this, idx).

`ios_base::seekdir`

typedef T4 seekdir;
static const seekdir beg, cur, end;

The type is an enumerated type T4 that describes an object that can store the seek mode used as an argument to the member functions of several iostreams classes. The distinct flag values are:

beg, to seek (alter the current read or write position) relative to the beginning oc a sequence (array, stream, or file)
cur, to seek relative to the current position within a sequence
end, to seek relative to the end of a sequence

`ios_base::setf`

void setf(fmtflags newfmtflags);
fmtflags setf(fmtflags newfmtflags, fmtflags mask);

The first member function effectively calls flags(newfmtflags | flags()) (set selected bits), then returns the previous format flags. The second member function effectively calls flags(mask & newfmtflags, flags() & ~mask) (replace selected bits under a mask), then returns the previous format flags.

`ios_base::streamoff`

typedef ::streamoff streamoff;

The type is a synonym for ::streamoff.

`ios_base::streampos`

typedef ::streampos streampos;

The type is a synonym for ::streampos.

`ios_base::sync_with_stdio`

static bool sync_with_stdio(bool newsync = true);

The static member function stores a stdio sync flag, which is initially true. When true, this flag ensures that operations on the same file are properly synchronized between the iostreams functions and those defined in the Standard C library. Otherwise, synchronization may or may not be guaranteed, but performance may be improved. The function stores newsync in the stdio sync flag and returns its previous stored value. You can call it reliably only before performing any operations on the standard streams.

`ios_base::unsetf`

void unsetf(fmtflags mask);

The member function effectively calls flags(~mask & flags()) (clear selected bits).

`ios_base::width`

streamsize width() const;
streamsize width(streamsize newwidth);

The first member function returns the stored field width. The second member function stores newwidth in the field width and returns its previous stored value.

`ios_base::xalloc`

static int xalloc();

The static member function returns a stored static value, which it increments on each call. You can use the return value as a unique index argument when calling the member functions iword or pword.

`left`

ios_base& left(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: left, ios_base:: adjustfield), then returns iosbase.

`locale`

class locale {
    };

The class serves as a placeholder for the much more elaborate locale machinery mandated by Standard C++.

`mbstate_t`

typedef T3 mbstate_t;

The type is an unspecified type T3 that serves as a placeholder for the more elaborate conversion-state machinery, used to convert between multibyte and wide-character encodings, mandated by Standard C.

`noboolalpha`

ios_base& noboolalpha(ios_base& iosbase);

The manipulator effectively calls iosbase.unsetf(ios_base:: boolalpha), then returns iosbase.

`noshowbase`

ios_base& noshowbase(ios_base& iosbase);

The manipulator effectively calls iosbase.unsetf(ios_base:: showbase), then returns iosbase.

`noshowpoint`

ios_base& noshowpoint(ios_base& iosbase);

The manipulator effectively calls iosbase.unsetf(ios_base:: showpoint), then returns iosbase.

`noshowpos`

ios_base& noshowpos(ios_base& iosbase);

The manipulator effectively calls iosbase.unsetf(ios_base:: showpos"), then returns iosbase.

`noskipws`

ios_base& noskipws(ios_base& iosbase);

The manipulator effectively calls iosbase.unsetf(ios_base:: skipws), then returns iosbase.

`nounitbuf`

ios_base& nounitbuf(ios_base& iosbase);

The manipulator effectively calls iosbase.unsetf(ios_base:: unitbuf), then returns iosbase.

`nouppercase`

ios_base& nouppercase(ios_base& iosbase);

The manipulator effectively calls iosbase.unsetf(ios_base:: uppercase), then returns iosbase.

`oct`

ios_base& oct(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: oct, ios_base:: basefield), then returns iosbase.

`right`

ios_base& right(ios_base& iosbase);

The maiipulator effectively calls iosbase.setf(ios_base:: right, ios_base:: adjustfield), then returns iosbase.

`scientific`

ios_base& scientific(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: scientific, ios_base:: floatfield), then returns iosbase.

`showbase`

ios_base& showbase(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: showbase), then returns iosbase.

`showpoint`

ios_base& showpoint(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: showpoint), then returns iosbase.

`showpos`

ios_base& showpos(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: showpos), then returns iosbase.

`skipws`

ios_base& skipws(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: skipws), then returns iosbase.

`streamoff`

typedef T1 streamoff;

The type is a signed integer type T1 that describes an object that can store a byte offset involved in various stream positioning operations. Its representation has at least 32 value bits. It is not necessarily large enough to represent an arbitrary byte position within a stream. The value streamoff(-1) generally indicates an erroneous offset.

`streampos`

typedef fpos streampos;

The type is a synonym for fpos.

`streamsize`

typedef T2 streamsize;

The type is a signed integer type T3 that describes an object that can store a count of the number of elements involved in various stream operations. Its representation has at least 16 bits. It is not necessarily large enough to represent an arbitrary byte position within a stream.

`unitbuf`

ios_base& unitbuf(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: unitbuf), then returns iosbase.

`uppercase`

ios_base& uppercase(ios_base& iosbase);

The manipulator effectively calls iosbase.setf(ios_base:: uppercase), then returns iosbase.

See also the Table of Contents and the Index.