Edit

Share via

ios_base Class

  • Article

The class describes the storage and member functions common to both input and output streams that don't depend on the template parameters. (The class template basic_ios describes what is common and is dependent on template parameters.)

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 precision 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.

Members

Constructors

Name Description
ios_base Constructs ios_base objects.

Typedefs

Name Description
event_callback Describes a function passed to register_call.
fmtflags Constants to specify the appearance of output.
iostate Defines constants describing the state of a stream.
openmode Describes how to interact with a stream.
seekdir Specifies starting point for offset operations.

Enums

Name Description
event Specifies event types.

Constants

Name Description
adjustfield A bitmask defined as internal | left | right.
app Specifies seeking to the end of a stream before each insertion.
ate Specifies seeking to the end of a stream when its controlling object is first created.
badbit Records a loss of integrity of the stream buffer.
basefield A bitmask defined as dec | hex | oct.
beg Specifies seeking relative to the beginning of a sequence.
binary Specifies that a file should be read as a binary stream, rather than as a text stream.
boolalpha Specifies insertion or extraction of objects of type bool as names (such as true and false) rather than as numeric values.
cur Specifies seeking relative to the current position within a sequence.
dec Specifies insertion or extraction of integer values in decimal format.
end Specifies seeking relative to the end of a sequence.
eofbit Records end-of-file while extracting from a stream.
failbit Records a failure to extract a valid field from a stream.
fixed Specifies insertion of floating-point values in fixed-point format (with no exponent field).
floatfield A bitmask defined as fixed | scientific
goodbit All state bits clear.
hex Specifies insertion or extraction of integer values in hexadecimal format.
in Specifies extraction from a stream.
internal Pads to a field width by inserting fill characters at a point internal to a generated numeric field.
left Specifies left justification.
oct Specifies insertion or extraction of integer values in octal format.
out Specifies insertion to a stream.
right Specifies right justification.
scientific Specifies insertion of floating-point values in scientific format (with an exponent field).
showbase Specifies insertion of a prefix that reveals the base of a generated integer field.
showpoint Specifies unconditional insertion of a decimal point in a generated floating-point field.
showpos Specifies insertion of a plus sign in a nonnegative generated numeric field.
skipws Specifies skipping leading white space before certain extractions.
trunc Specifies deleting contents of an existing file when its controlling object is created.
unitbuf Causes output to be flushed after each insertion.
uppercase Specifies insertion of uppercase equivalents of lowercase letters in certain insertions.

Functions

Name Description
failure The member class serves as the base class for all exceptions thrown by the member function clear in class template basic_ios.
flags Sets or returns the current flag settings.
getloc Returns the stored locale object.
imbue Changes the locale.
Init Creates the standard iostream objects when constructed.
iword Assigns a value to be stored as an iword.
precision Specifies the number of digits to display in a floating-point number.
pword Assigns a value to be stored as a pword.
register_callback Specifies a callback function.
setf Sets the specified flags.
sync_with_stdio Ensures that iostream and C run-time library operations occur in the order that they appear in source code.
unsetf Causes the specified flags to be off.
width Sets the length of the output stream.
xalloc Specifies that a variable shall be part of the stream.

Operators

Name Description
operator= The assignment operator for ios_base objects.

Requirements

Header: <ios>

Namespace: std

event

Specifies event types.

enum event {
    erase_event,
    imbue_event,
    copyfmt_event};

Remarks

The type is an enumerated type 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.

Example

See register_callback for an example.

event_callback

Describes a function passed to register_call.

typedef void (__cdecl *event_callback)(
    event _E,
    ios_base& _Base,
    int _I);

Parameters

_E
The event.

_Base
The stream in which the event was called.

_I
A user-defined number.

Remarks

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

Example

See register_call for an example that uses event_callback.

failure

The class failure defines the base class for the types of all objects thrown as exceptions, by functions in the iostreams library, to report errors detected during stream buffer operations.

namespace std {
    class failure : public system_error {
    public:
        explicit failure(
            const string& _Message,
            const error_code& _Code = io_errc::stream);

        explicit failure(
            const char* str,
            const error_code& _Code = io_errc::stream);
    };
}

Remarks

The value returned by what() is a copy of _Message, possibly augmented with a test based on _Code. If _Code isn't specified, the default value is make_error_code(io_errc::stream).

Example

// ios_base_failure.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main ( )
{
    using namespace std;
    fstream file;
    file.exceptions(ios::failbit);
    try
    {
        file.open( "rm.txt", ios_base::in );
        // Opens nonexistent file for reading
    }
    catch( ios_base::failure f )
    {
        cout << "Caught an exception: " << f.what() << endl;
    }
}

Caught an exception: ios_base::failbit set

flags

Sets or returns the current flag settings.

fmtflags flags() const;
fmtflags flags(fmtflags fmtfl);

Parameters

fmtfl
The new fmtflags setting.

Return Value

The previous or current fmtflags setting.

Remarks

See ios_base::fmtflags for a list of the flags.

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

Example

// ios_base_flags.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main ( )
{
    using namespace std;
    cout << cout.flags( ) << endl;
    cout.flags( ios::dec | ios::boolalpha );
    cout << cout.flags( );
}

513
16896

fmtflags

Constants to specify the appearance of output.

class ios_base {
public:
   typedef implementation-defined-bitmask-type fmtflags;
   static const fmtflags boolalpha;
   static const fmtflags dec;
   static const fmtflags fixed;
   static const fmtflags hex;
   static const fmtflags internal;
   static const fmtflags left;
   static const fmtflags oct;
   static const fmtflags right;
   static const fmtflags scientific;
   static const fmtflags showbase;
   static const fmtflags showpoint;
   static const fmtflags showpos;
   static const fmtflags skipws;
   static const fmtflags unitbuf;
   static const fmtflags uppercase;
   static const fmtflags adjustfield;
   static const fmtflags basefield;
   static const fmtflags floatfield;
   // ...
};

Remarks

Supports the manipulators in ios.

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

  • dec, to insert or extract integer values in decimal format.

  • hex, to insert or extract integer values in hexadecimal format.

  • oct, to insert or extract integer values in octal format.

  • showbase, to insert a prefix that reveals the base of a generated integer field.

  • internal, to pad to a field width as needed by inserting fill characters at a point internal to a generated numeric field. (For information on setting the field width, see setw).

  • left, to pad to a field width as needed by inserting fill characters at the end of a generated field (left justification).

  • right, to pad to a field width as needed by inserting fill characters at the beginning of a generated field (right justification).

  • boolalpha, to insert or extract objects of type bool as names (such as true and false) rather than as numeric values.

  • fixed, to insert floating-point values in fixed-point format (with no exponent field).

  • scientific, to insert floating-point values in scientific format (with an exponent field).

  • showpoint, to insert a decimal point unconditionally in a generated floating-point field.

  • showpos, to insert a plus sign in a nonnegative 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, a bitmask defined as internal | left | right

  • basefield, defined as dec | hex | oct

  • floatfield, defined as fixed | scientific

For examples of functions that modify these format flags, see <iomanip>.

getloc

Returns the stored locale object.

locale getloc() const;

Return Value

The stored locale object.

Example

// ios_base_getlock.cpp
// compile with: /EHsc
#include <iostream>

int main( )
{
    using namespace std;
    cout << cout.getloc( ).name( ).c_str( ) << endl;
}

C

imbue

Changes the locale.

locale imbue(const locale& _Loc);

Parameters

_Loc
The new locale setting.

Return Value

The previous locale.

Remarks

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

Example

See basic_ios::imbue for a sample.

Init

Creates the standard iostream objects when constructed.

class Init { };

Remarks

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

ios_base

Constructs ios_base objects.

ios_base();

Remarks

The (protected) constructor does nothing. A later call to basic_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 class template basic_ios.

iostate

The type of constants that describe the state of a stream.

class ios_base {
public:
   typedef implementation-defined-bitmask-type iostate;
   static const iostate badbit;
   static const iostate eofbit;
   static const iostate failbit;
   static const iostate goodbit;
   // ...
};

Remarks

The type is a bitmask type 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, where none of the previously mentioned bits are set (goodbit is guaranteed to be zero).

iword

Assigns a value to be stored as an iword.

long& iword(int idx);

Parameters

idx
The index of the value to store as an iword.

Remarks

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 basic_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.

Example

See xalloc for a sample of how to use iword.

openmode

Describes how to interact with a stream.

class ios_base {
public:
   typedef implementation-defined-bitmask-type openmode;
   static const openmode  in;
   static const openmode  out;
   static const openmode  ate;
   static const openmode  app;
   static const openmode  trunc;
   static const openmode  binary;
   // ...
};

Remarks

The opening mode for several iostream objects. The flag values are:

Constant Effect
app Seek to the end of the stream before each write
ate Seek to the end of the stream immediately after open
binary Open in binary mode. (See fopen for a description of binary mode.)
in Open for reading
out Open for writing
trunc Delete the contents of the file after open

Example

// ios_base_openmode.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main ( )
{
    using namespace std;
    fstream file;
    file.open( "rm.txt", ios_base::out | ios_base::trunc );

    file << "testing";
}

operator=

The assignment operator for ios_base objects.

ios_base& operator=(const ios_base& right);

Parameters

right
An object of type ios_base.

Return Value

The object being assigned to.

Remarks

The operator copies the stored formatting information, making a new copy of any extensible arrays. It then returns *this. The callback stack isn't copied.

This operator is only used by classes derived from ios_base.

precision

Specifies the number of digits to display in a floating-point number.

streamsize precision() const;
streamsize precision(streamsize _Prec);

Parameters

_Prec
The number of significant digits to display, or the number of digits after the decimal point in fixed notation.

Return Value

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

Remarks

Floating-point numbers are displayed in fixed notation with fixed.

Example

// ios_base_precision.cpp
// compile with: /EHsc
#include <iostream>

int main( )
{
    using namespace std;
    float i = 31.31234F;

    cout.precision( 3 );
    cout << i << endl;          // display three significant digits
    cout << fixed << i << endl; // display three digits after decimal
                                // point
}

31.3
31.312

pword

Assigns a value to be stored as a pword.

void *& pword(int index);

Parameters

index
The index of the value to store as a pword.

Remarks

The member function returns a reference to element index 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 basic_ios::copyfmt, or after the object is destroyed.

If index 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.

Example

See xalloc for an example of using pword.

register_callback

Specifies a callback function.

void register_callback(
    event_callback pfn, int idx);

Parameters

pfn
Pointer to the callback function.

idx
A user-defined number.

Remarks

The member function pushes the pair {pfn, idx} onto the stored callback stack 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).

Example

// ios_base_register_callback.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

using namespace std;

void callback1( ios_base::event e, ios_base& stream, int arg )
{
    cout << "in callback1" << endl;
    switch ( e )
    {
    case ios_base::erase_event:
        cout << "an erase event" << endl;
        break;
    case ios_base::imbue_event:
        cout << "an imbue event" << endl;
        break;
    case ios_base::copyfmt_event:
        cout << "an copyfmt event" << endl;
        break;
    };
}

void callback2( ios_base::event e, ios_base& stream, int arg )
{
    cout << "in callback2" << endl;
    switch ( e )
    {
    case ios_base::erase_event:
        cout << "an erase event" << endl;
        break;
    case ios_base::imbue_event:
        cout << "an imbue event" << endl;
        break;
    case ios_base::copyfmt_event:
        cout << "an copyfmt event" << endl;
        break;
    };
}

int main( )
{
    // Make sure the imbue will not throw an exception
    // assert( setlocale( LC_ALL, "german" )!=NULL );

    cout.register_callback( callback1, 0 );
    cin.register_callback( callback2, 0 );

    try
    {
        // If no exception because the locale's not found,
        // generate an imbue_event on callback1
        cout.imbue(locale("german"));
    }
    catch(...)
    {
        cout << "exception" << endl;
    }

    // This will
    // (1) erase_event on callback1
    // (2) copyfmt_event on callback2
    cout.copyfmt(cin);

    // We get two erase events from callback2 at the end because
    // both cin and cout have callback2 registered when cin and cout
    // are destroyed at the end of program.
}

in callback1
an imbue event
in callback1
an erase event
in callback2
an copyfmt event
in callback2
an erase event
in callback2
an erase event

seekdir

Specifies starting point for offset operations.

namespace std {
    class ios_base {
    public:
        typedef implementation-defined-enumerated-type seekdir;
        static const seekdir beg;
        static const seekdir cur;
        static const seekdir end;
        // ...
    };
}

Remarks

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

  • beg, to seek (alter the current read or write position) relative to the beginning of 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.

Example

// ios_base_seekdir.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main ( )
{
    using namespace std;
    fstream file;
    file.open( "rm.txt", ios_base::out | ios_base::trunc );

    file << "testing";
    file.seekp( 0, ios_base::beg );
    file << "a";
    file.seekp( 0, ios_base::end );
    file << "a";
}

setf

Sets the specified flags.

fmtflags setf(
    fmtflags _Mask
);
fmtflags setf(
    fmtflags _Mask,
    fmtflags _Unset
);

Parameters

_Mask
The flags to turn on.

_Unset
The flags to turn off.

Return Value

The previous format flags

Remarks

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

Example

// ios_base_setf.cpp
// compile with: /EHsc
#include <iostream>

int main( )
{
    using namespace std;
    int i = 10;
    cout << i << endl;

    cout.unsetf( ios_base::dec );
    cout.setf( ios_base::hex );
    cout << i << endl;

    cout.setf( ios_base::dec );
    cout << i << endl;
    cout.setf( ios_base::hex, ios_base::dec );
    cout << i << endl;
}

sync_with_stdio

Ensures that iostream and C run-time library operations occur in the order that they appear in source code.

static bool sync_with_stdio(
   bool _Sync = true
);

Parameters

_Sync
Whether all streams are in sync with stdio.

Return Value

Previous setting for this function.

Remarks

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 functions defined in the C++ Standard Library. Otherwise, synchronization may or may not be guaranteed, but performance may be improved. The function stores _Sync 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.

unsetf

Turns off the specified flags.

void unsetf(
   fmtflags _Mask
);

Parameters

_Mask
The flags that you want to turn off.

Remarks

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

Example

See ios_base::setf for a sample of using unsetf.

width

Sets the length of the output stream.

streamsize width( ) const;
streamsize width(
   streamsize _Wide
);

Parameters

_Wide
The desired size of the output stream.

Return Value

The current width setting.

Remarks

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

Example

// ios_base_width.cpp
// compile with: /EHsc
#include <iostream>

int main( ) {
    using namespace std;

    cout.width( 20 );
    cout << cout.width( ) << endl;
    cout << cout.width( ) << endl;
}

20
0

xalloc

Specifies that a variable is part of the stream.

static int xalloc( );

Return Value

The static member function returns a stored static value, which it increments on each call.

Remarks

You can use the return value as a unique index argument when calling the member functions iword or pword.

Example

// ios_base_xalloc.cpp
// compile with: /EHsc
// Lets you store user-defined information.
// iword, jword, xalloc
#include <iostream>

int main( )
{
    using namespace std;

    static const int i = ios_base::xalloc();
    static const int j = ios_base::xalloc();
    cout.iword( i ) = 11;
    cin.iword( i ) = 13;
    cin.pword( j ) = "testing";
    cout << cout.iword( i ) << endl;
    cout << cin.iword( i ) << endl;
    cout << ( char * )cin.pword( j ) << endl;
}

11
13
testing

See also

Thread Safety in the C++ Standard Library
iostream Programming
iostreams Conventions