\rSec0[input.output]{Input/output library}

\rSec1[input.output.general]{General}

\pnum

This Clause describes components that \Cpp programs may use to perform

input/output operations.

\pnum

The following subclauses describe

requirements for stream parameters,

and components for

forward declarations of iostreams,

predefined iostreams objects,

base iostreams classes,

stream buffering,

stream formatting and manipulators,

string streams,

and file streams,

as summarized in Table~\ref{tab:iostreams.lib.summary}.

\begin{libsumtab}{Input/output library summary}{tab:iostreams.lib.summary}

\ref{iostreams.requirements} & Requirements & \\ \rowsep

\ref{iostream.forward} & Forward declarations & \tcode{<iosfwd>} \\ \rowsep

\ref{iostream.objects} & Standard iostream objects & \tcode{<iostream>} \\ \rowsep

\ref{iostreams.base} & Iostreams base classes & \tcode{<ios>} \\ \rowsep

\ref{stream.buffers} & Stream buffers & \tcode{<streambuf>} \\ \rowsep

\ref{iostream.format} & Formatting and manipulators & \tcode{<istream>} \\

& & \tcode{<ostream>} \\

& & \tcode{<iomanip>} \\ \rowsep

\ref{string.streams} & String streams & \tcode{<sstream>} \\ \rowsep

\ref{file.streams} & File streams & \tcode{<fstream>} \\

& & \tcode{<cstdio>} \\

& & \tcode{<cinttypes>} \\

\end{libsumtab}

\pnum

Figure~\ref{fig:streampos} illustrates relationships among various types

described in \DIFdelbegin \DIFdel{ths }\DIFdelend \DIFaddbegin \DIFadd{this }\DIFaddend clause. A line from \textbf{A} to \textbf{B} indicates that \textbf{A}

is an alias (e.g. a typedef) for \textbf{B} or that \textbf{A} is defined in terms of

\textbf{B}.

\begin{importgraphic}

{Stream position, offset, and size types [non-normative]}

{fig:streampos}

{figstreampos.pdf}

\end{importgraphic}

\rSec1[iostreams.requirements]{Iostreams requirements}

\rSec2[iostream.limits.imbue]{Imbue limitations}

\pnum

No function described in Clause~\ref{input.output} except for

\tcode{ios_base::imbue}

and \tcode{basic_filebuf::pubimbue}

causes any instance of

\tcode{basic_ios::imbue}

or

\tcode{basic_streambuf::imbue}

to be called.

If any user function called from a function declared in Clause~\ref{input.output} or

as an overriding virtual function of any class declared in Clause~\ref{input.output}

calls

\tcode{imbue},

the behavior is undefined.

\rSec2[iostreams.limits.pos]{Positioning type limitations}

\pnum

The classes of Clause~\ref{input.output} with template arguments

\tcode{charT}

and

\tcode{traits}

behave as described if

\tcode{traits::pos_type}

and

\tcode{traits::off_type}

are

\tcode{streampos}

and

\tcode{streamoff}

respectively.

Except as noted explicitly below, their behavior when

\tcode{traits::pos_type}

and

\tcode{traits::off_type}

are other types is

\indextext{\idxcode{streambuf}!implementation-defined}%

\impldef{behavior of iostream classes when \tcode{traits::pos_type} is not \tcode{streampos} or when \tcode{traits::off_type} is not \tcode{streamoff}}.

\pnum

In the classes of Clause~\ref{input.output}, a template formal parameter with name

\tcode{charT} represents a member of the set of types containing \tcode{char}, \tcode{wchar_t},

and any other implementation-defined character types that satisfy the requirements for

a character on which any of the iostream components can be instantiated.

\rSec2[iostreams.threadsafety]{Thread safety}

\pnum

Concurrent access to a stream object (\ref{string.streams},~\ref{file.streams}), stream buffer

object~(\ref{stream.buffers}), or C Library stream~(\ref{c.files}) by multiple threads may result in

a data race~(\ref{intro.multithread}) unless otherwise specified~(\ref{iostream.objects}).

\enternote Data races result in undefined behavior~(\ref{intro.multithread}). \exitnote

\pnum

If one thread makes a library call \textit{a} that writes a value to a stream

and, as a result, another thread reads this value from the stream through a

library call \textit{b} such that this does not result in a data race, then

\textit{a}'s write synchronizes with

\textit{b}'s read.

\rSec1[iostream.forward]{Forward declarations}

\synopsis{Header \tcode{<iosfwd>} synopsis}

\indexlibrary{\idxhdr{iosfwd}}%

\indexlibrary{\idxcode{basic_ios}}%

\indexlibrary{\idxcode{basic_streambuf}}%

\indexlibrary{\idxcode{basic_istream}}%

\indexlibrary{\idxcode{basic_ostream}}%

\indexlibrary{\idxcode{basic_stringbuf}}%

\indexlibrary{\idxcode{basic_istringstream}}%

\indexlibrary{\idxcode{basic_ostringstream}}%

\indexlibrary{\idxcode{basic_stringstream}}%

\indexlibrary{\idxcode{basic_filebuf}}%

\indexlibrary{\idxcode{basic_ifstream}}%

\indexlibrary{\idxcode{basic_ofstream}}%

\indexlibrary{\idxcode{basic_fstream}}%

\indexlibrary{\idxcode{basic_istreambuf_iterator}}%

\indexlibrary{\idxcode{basic_ostreambuf_iterator}}%

\indexlibrary{\idxcode{ios}}%

\indexlibrary{\idxcode{streambuf}}%

\indexlibrary{\idxcode{istream}}%

\indexlibrary{\idxcode{ostream}}%

\indexlibrary{\idxcode{stringbuf}}%

\indexlibrary{\idxcode{istringstream}}%

\indexlibrary{\idxcode{ostringstream}}%

\indexlibrary{\idxcode{stringstream}}%

\indexlibrary{\idxcode{filebuf}}%

\indexlibrary{\idxcode{ifstream}}%

\indexlibrary{\idxcode{ofstream}}%

\indexlibrary{\idxcode{fstream}}%

\indexlibrary{\idxcode{wstreambuf}}%

\indexlibrary{\idxcode{wistream}}%

\indexlibrary{\idxcode{wostream}}%

\indexlibrary{\idxcode{wstringbuf}}%

\indexlibrary{\idxcode{wistringstream}}%

\indexlibrary{\idxcode{wostringstream}}%

\indexlibrary{\idxcode{wstringstream}}%

\indexlibrary{\idxcode{wfilebuf}}%

\indexlibrary{\idxcode{wifstream}}%

\indexlibrary{\idxcode{wofstream}}%

\indexlibrary{\idxcode{wfstream}}%

\begin{codeblock}

namespace std {

template<class charT> class char_traits;

template<> class char_traits<char>;

template<> class char_traits<char16_t>;

template<> class char_traits<char32_t>;

template<> class char_traits<wchar_t>;

template<class T> class allocator;

template <class charT, class traits = char_traits<charT> >

class basic_ios;

template <class charT, class traits = char_traits<charT> >

class basic_streambuf;

template <class charT, class traits = char_traits<charT> >

class basic_istream;

template <class charT, class traits = char_traits<charT> >

class basic_ostream;

template <class charT, class traits = char_traits<charT> >

class basic_iostream;

template <class charT, class traits = char_traits<charT>,

class Allocator = allocator<charT> >

class basic_stringbuf;

template <class charT, class traits = char_traits<charT>,

class Allocator = allocator<charT> >

class basic_istringstream;

template <class charT, class traits = char_traits<charT>,

class Allocator = allocator<charT> >

class basic_ostringstream;

template <class charT, class traits = char_traits<charT>,

class Allocator = allocator<charT> >

class basic_stringstream;

template <class charT, class traits = char_traits<charT> >

class basic_filebuf;

template <class charT, class traits = char_traits<charT> >

class basic_ifstream;

template <class charT, class traits = char_traits<charT> >

class basic_ofstream;

template <class charT, class traits = char_traits<charT> >

class basic_fstream;

template <class charT, class traits = char_traits<charT> >

class istreambuf_iterator;

template <class charT, class traits = char_traits<charT> >

class ostreambuf_iterator;

typedef basic_ios<char> ios;

typedef basic_ios<wchar_t> wios;

typedef basic_streambuf<char> streambuf;

typedef basic_istream<char> istream;

typedef basic_ostream<char> ostream;

typedef basic_iostream<char> iostream;

typedef basic_stringbuf<char> stringbuf;

typedef basic_istringstream<char> istringstream;

typedef basic_ostringstream<char> ostringstream;

typedef basic_stringstream<char> stringstream;

typedef basic_filebuf<char> filebuf;

typedef basic_ifstream<char> ifstream;

typedef basic_ofstream<char> ofstream;

typedef basic_fstream<char> fstream;

typedef basic_streambuf<wchar_t> wstreambuf;

typedef basic_istream<wchar_t> wistream;

typedef basic_ostream<wchar_t> wostream;

typedef basic_iostream<wchar_t> wiostream;

typedef basic_stringbuf<wchar_t> wstringbuf;

typedef basic_istringstream<wchar_t> wistringstream;

typedef basic_ostringstream<wchar_t> wostringstream;

typedef basic_stringstream<wchar_t> wstringstream;

typedef basic_filebuf<wchar_t> wfilebuf;

typedef basic_ifstream<wchar_t> wifstream;

typedef basic_ofstream<wchar_t> wofstream;

typedef basic_fstream<wchar_t> wfstream;

template <class state> class fpos;

typedef fpos<char_traits<char>::state_type> streampos;

typedef fpos<char_traits<wchar_t>::state_type> wstreampos;

}

\end{codeblock}

\pnum

Default template arguments are described as appearing both in

\tcode{<iosfwd>}

and in the synopsis of other headers

but it is well-formed to include both

\tcode{<iosfwd>}

and one or more of the other headers.\footnote{It is the implementation's

responsibility to implement headers so

that including

\tcode{<iosfwd>}

and other headers does not violate the rules about

multiple \DIFdelbegin \DIFdel{occurences }\DIFdelend \DIFaddbegin \DIFadd{occurrences }\DIFaddend of default arguments.}

\pnum

\enternote

The

class template specialization

\tcode{basic_ios<charT,traits>}

serves as a virtual base class for the

class templates

\tcode{basic_istream},

\tcode{basic_ostream},

and

class templates

derived from them.

\tcode{basic_iostream}

is a class

template

derived from both

\tcode{basic_istream<charT,traits>}

and

\tcode{basic_ostream<charT,traits>}.

\pnum

The

class template specialization

\tcode{basic_streambuf<charT,traits>}

serves as a base class for class templates

\tcode{basic_stringbuf}

and

\tcode{basic_filebuf}.

\pnum

The

class template specialization

\tcode{basic_istream<charT,traits>}

serves as a base class for class templates

\tcode{basic_istringstream}

and

\tcode{basic_ifstream}.

\pnum

The

class template specialization

\tcode{basic_ostream<charT,traits>}

serves as a base class for class templates

\tcode{basic_ostringstream}

and

\tcode{basic_ofstream}.

\pnum

The

class template specialization

\tcode{basic_iostream<charT,traits>}

serves as a base class for class templates

\tcode{basic_stringstream}

and

\tcode{basic_fstream}.

\pnum

Other typedefs define instances of

class templates

specialized for

\tcode{char}

or

\tcode{wchar_t}

types.

\pnum

Specializations of the class template

\tcode{fpos}

are

used for specifying file position information.

\pnum

The types

\tcode{streampos}

and

\tcode{wstreampos}

are used for positioning streams specialized on

\tcode{char}

and

\tcode{wchar_t}

respectively.

\pnum

This synopsis suggests a circularity between

\tcode{streampos}

and

\tcode{char_traits<char>}.

An implementation can avoid this circularity by substituting equivalent

types.

One way to do this might be

\begin{codeblock}

template<class stateT> class fpos { ... }; // depends on nothing

typedef ... _STATE; // implementation private declaration of \tcode{stateT}

typedef fpos<_STATE> streampos;

template<> struct char_traits<char> {

typedef streampos

pos_type;

}

\end{codeblock}

\exitnote

\rSec1[iostream.objects]{Standard iostream objects}

\rSec2[iostream.objects.overview]{Overview}

\synopsis{Header \tcode{<iostream>} synopsis}

\indexlibrary{\idxhdr{iostream}}%

\begin{codeblock}

#include <ios>

#include <streambuf>

#include <istream>

#include <ostream>

namespace std {

extern istream cin;

extern ostream cout;

extern ostream cerr;

extern ostream clog;

extern wistream wcin;

extern wostream wcout;

extern wostream wcerr;

extern wostream wclog;

}

\end{codeblock}

\pnum

The header

\tcode{<iostream>}

declares objects that associate objects with the

standard C streams provided for by the functions declared in

\tcode{<cstdio>}~(\ref{c.files}), and includes all the headers necessary to use

these objects.

\indexlibrary{\idxhdr{cstdio}}%

\pnum

The objects are constructed and the associations are established at some

time prior to or during the first time an object of class

\tcode{ios_base::Init} is constructed, and in any case before the body

of \tcode{main} begins execution.\footnote{If it is possible for them to do so, implementations are encouraged to

initialize the objects earlier than required.}

The objects are not destroyed during program execution.\footnote{Constructors and destructors for static objects can

access these objects to read input from

\tcode{stdin}

or write output to

\tcode{stdout}

or

\tcode{stderr}.

}

The results of including \tcode{<iostream>} in a translation unit shall be as if

\tcode{<iostream>} defined an instance of \tcode{ios_base::Init} with static

storage duration. Similarly, the entire program shall behave as if there were at least

one instance of \tcode{ios_base::Init} with static storage duration.

\pnum

Mixing operations on corresponding wide- and narrow-character streams

follows the same semantics as mixing such operations on

\tcode{FILE}s,

as specified in Amendment 1 of the ISO C standard.

\pnum

Concurrent access to a synchronized~(\ref{ios.members.static}) standard iostream object's formatted and unformatted input~(\ref{istream}) and output~(\ref{ostream}) functions or a standard C stream by multiple threads shall not result in a data race~(\ref{intro.multithread}). \enternote Users must still synchronize concurrent use of these objects and streams by multiple threads if they wish to avoid interleaved characters. \exitnote

\rSec2[narrow.stream.objects]{Narrow stream objects}

\indexlibrary{\idxcode{cin}}%

\begin{itemdecl}

istream cin;

\end{itemdecl}

\begin{itemdescr}

\pnum

The object

\tcode{cin}

controls input from a stream buffer

associated with the object

\tcode{stdin},

declared in

\indexlibrary{\idxhdr{cstdio}}%

\tcode{<cstdio>}.

\pnum

After the object

\tcode{cin}

is initialized,

\tcode{cin.tie()}

returns

\tcode{\&cout}.

Its state is otherwise the same as required for

\tcode{basic_ios<char>::init}~(\ref{basic.ios.cons}).

\end{itemdescr}

\indexlibrary{\idxcode{cout}}%

\begin{itemdecl}

ostream cout;

\end{itemdecl}

\begin{itemdescr}

\pnum

The object

\tcode{cout}

controls output to a stream buffer

associated with the object

\tcode{stdout},

declared in

\indexlibrary{\idxhdr{cstdio}}%

\tcode{<cstdio>}~(\ref{c.files}).

\end{itemdescr}

\indexlibrary{\idxcode{cerr}}%

\begin{itemdecl}

ostream cerr;

\end{itemdecl}

\begin{itemdescr}

\pnum

The object

\tcode{cerr}

controls output to a stream buffer

associated with the object

\tcode{stderr},

declared in

\indexlibrary{\idxhdr{cstdio}}%

\tcode{<cstdio>}~(\ref{c.files}).

\pnum

After the object

\tcode{cerr}

is initialized,

\tcode{cerr.flags() \& unitbuf}

is nonzero and \tcode{cerr.tie()} returns \tcode{\&cout}.

Its state is otherwise the same as required for

\tcode{basic_ios<char>::init}~(\ref{basic.ios.cons}).

\end{itemdescr}

\indexlibrary{\idxcode{clog}}%

\begin{itemdecl}

ostream clog;

\end{itemdecl}

\begin{itemdescr}

\pnum

The object

\tcode{clog}

controls output to a stream buffer

associated with the object

\tcode{stderr},

declared in

\indexlibrary{\idxhdr{cstdio}}%

\tcode{<cstdio>}~(\ref{c.files}).

\end{itemdescr}

\rSec2[wide.stream.objects]{Wide stream objects}

\indexlibrary{\idxcode{wcin}}%

\begin{itemdecl}

wistream wcin;

\end{itemdecl}

\begin{itemdescr}

\pnum

The object

\tcode{wcin}

controls input from a stream buffer

associated with the object

\tcode{stdin},

declared in

\indexlibrary{\idxhdr{cstdio}}%

\tcode{<cstdio>}.

\pnum

After the object

\tcode{wcin}

is initialized,

\tcode{wcin.tie()}

returns

\tcode{\&wcout}.

Its state is otherwise the same as required for

\tcode{basic_ios<wchar_t>::init}~(\ref{basic.ios.cons}).

\end{itemdescr}

\indexlibrary{\idxcode{wcout}}%

\begin{itemdecl}

wostream wcout;

\end{itemdecl}

\begin{itemdescr}

\pnum

The object

\tcode{wcout}

controls output to a stream buffer

associated with the object

\tcode{stdout},

declared in

\indexlibrary{\idxhdr{cstdio}}%

\tcode{<cstdio>}~(\ref{c.files}).

\end{itemdescr}

\indexlibrary{\idxcode{wcerr}}%

\begin{itemdecl}

wostream wcerr;

\end{itemdecl}

\begin{itemdescr}

\pnum

The object

\tcode{wcerr}

controls output to a stream buffer

associated with the object

\tcode{stderr},

declared in

\indexlibrary{\idxhdr{cstdio}}%

\tcode{<cstdio>}~(\ref{c.files}).

\pnum

After the object

\tcode{wcerr}

is initialized,

\tcode{wcerr.flags() \& unitbuf}

is nonzero and \tcode{wcerr.tie()} returns \tcode{\&wcout}.

Its state is otherwise the same as required for

\tcode{basic_ios<wchar_t>::init}~(\ref{basic.ios.cons}).

\end{itemdescr}

\indexlibrary{\idxcode{wclog}}%

\begin{itemdecl}

wostream wclog;

\end{itemdecl}

\begin{itemdescr}

\pnum

The object

\tcode{wclog}

controls output to a stream buffer

associated with the object

\tcode{stderr},

declared in

\indexlibrary{\idxhdr{cstdio}}%

\tcode{<cstdio>}~(\ref{c.files}).

\end{itemdescr}

\rSec1[iostreams.base]{Iostreams base classes}

\rSec2[iostreams.base.overview]{Overview}

\synopsis{Header \tcode{<ios>} synopsis}

\indexlibrary{\idxhdr{ios}}%

\begin{codeblock}

#include <iosfwd>

namespace std {

typedef @\impdef@ streamoff;

typedef @\impdef@ streamsize;

template <class stateT> class fpos;

class ios_base;

template <class charT, class traits = char_traits<charT> >

class basic_ios;

// \ref{std.ios.manip}, manipulators:

ios_base& boolalpha (ios_base& str);

ios_base& noboolalpha(ios_base& str);

ios_base& showbase (ios_base& str);

ios_base& noshowbase (ios_base& str);

ios_base& showpoint (ios_base& str);

ios_base& noshowpoint(ios_base& str);

ios_base& showpos (ios_base& str);

ios_base& noshowpos (ios_base& str);

ios_base& skipws (ios_base& str);

ios_base& noskipws (ios_base& str);

ios_base& uppercase (ios_base& str);

ios_base& nouppercase(ios_base& str);

ios_base& unitbuf (ios_base& str);

ios_base& nounitbuf (ios_base& str);

// \ref{adjustfield.manip} adjustfield:

ios_base& internal (ios_base& str);

ios_base& left (ios_base& str);

ios_base& right (ios_base& str);

// \ref{basefield.manip} basefield:

ios_base& dec (ios_base& str);

ios_base& hex (ios_base& str);

ios_base& oct (ios_base& str);

// \ref{floatfield.manip} floatfield:

ios_base& fixed (ios_base& str);

ios_base& scientific (ios_base& str);

ios_base& hexfloat (ios_base& str);

ios_base& defaultfloat(ios_base& str);

// \ref{error.reporting} error reporting:

enum class io_errc {

stream = 1

};

template <> struct is_error_code_enum<io_errc> : public true_type { };

error_code make_error_code(io_errc e);

error_condition make_error_condition(io_errc e);

const error_category& iostream_category();

}

\end{codeblock}

\indexlibrary{\idxcode{ios}}%

\indexlibrary{\idxcode{basic_ios<char>}}%

\indexlibrary{\idxcode{wios}}%

\indexlibrary{\idxcode{basic_ios<wchar_t>}}%

\indexlibrary{\idxcode{fpos}}%

\rSec2[stream.types]{Types}

\indexlibrary{\idxcode{streamoff}}%

\begin{itemdecl}

typedef @\impdef@ streamoff;

\end{itemdecl}

\begin{itemdescr}

\pnum

The type \tcode{streamoff} is a synonym for one of the signed basic integral types of

sufficient size to represent the maximum possible file size for the operating system.\footnote{Typically \tcode{long long}.}

\end{itemdescr}

\indexlibrary{\idxcode{streamsize}}%

\begin{itemdecl}

typedef @\impdef@ streamsize;

\end{itemdecl}

\begin{itemdescr}

\pnum

The type

\tcode{streamsize}

is a synonym for one of the signed basic

integral types.

It is used to represent the number of characters transferred in an I/O

operation, or the size of I/O buffers.\footnote{\tcode{streamsize}

is used in most places where ISO C would use

\tcode{size_t}.

Most of the uses of

\tcode{streamsize}

could use

\tcode{size_t},

except for the

\tcode{strstreambuf}

constructors, which require negative values.

It should probably be the signed type corresponding to

\tcode{size_t}

(which is what Posix.2 calls

\tcode{ssize_t}).}

\end{itemdescr}

\rSec2[ios.base]{Class \tcode{ios_base}}

\indexlibrary{\idxcode{ios_base}}%

\begin{codeblock}

namespace std {

class ios_base {

public:

class failure;

// \ref{ios::fmtflags} \tcode{fmtflags}

typedef @\textit{T1}@ fmtflags;

static constexpr fmtflags boolalpha = @\unspec@;

static constexpr fmtflags dec = @\unspec@;

static constexpr fmtflags fixed = @\unspec@;

static constexpr fmtflags hex = @\unspec@;

static constexpr fmtflags internal = @\unspec@;

static constexpr fmtflags left = @\unspec@;

static constexpr fmtflags oct = @\unspec@;

static constexpr fmtflags right = @\unspec@;

static constexpr fmtflags scientific = @\unspec@;

static constexpr fmtflags showbase = @\unspec@;

static constexpr fmtflags showpoint = @\unspec@;

static constexpr fmtflags showpos = @\unspec@;

static constexpr fmtflags skipws = @\unspec@;

static constexpr fmtflags unitbuf = @\unspec@;

static constexpr fmtflags uppercase = @\unspec@;

static constexpr fmtflags adjustfield = @\seebelow@;

static constexpr fmtflags basefield = @\seebelow@;

static constexpr fmtflags floatfield = @\seebelow@;

// \ref{ios::iostate} \tcode{iostate}

typedef @\textit{T2}@ iostate;

static constexpr iostate badbit = @\unspec@;

static constexpr iostate eofbit = @\unspec@;

static constexpr iostate failbit = @\unspec@;

static constexpr iostate goodbit = @\seebelow@;

// \ref{ios::openmode} \tcode{openmode}

typedef @\textit{T3}@ openmode;

static constexpr openmode app = @\unspec@;

static constexpr openmode ate = @\unspec@;

static constexpr openmode binary = @\unspec@;

static constexpr openmode in = @\unspec@;

static constexpr openmode out = @\unspec@;

static constexpr openmode trunc = @\unspec@;

// \ref{ios::seekdir} \tcode{seekdir}

typedef @\textit{T4}@ seekdir;

static constexpr fmtflags beg = @\unspec@;

static constexpr fmtflags cur = @\unspec@;

static constexpr fmtflags end = @\unspec@;

class Init;

// \ref{fmtflags.state} fmtflags state:

fmtflags flags() const;

fmtflags flags(fmtflags fmtfl);

fmtflags setf(fmtflags fmtfl);

fmtflags setf(fmtflags fmtfl, fmtflags mask);

void unsetf(fmtflags mask);

streamsize precision() const;

streamsize precision(streamsize prec);

streamsize width() const;

streamsize width(streamsize wide);

// \ref{ios.base.locales} locales:

locale imbue(const locale& loc);

locale getloc() const;

// \ref{ios.base.storage} storage:

static int xalloc();

long& iword(int index);

void*& pword(int index);

// destructor

virtual ~ios_base();

// \ref{ios.base.callback} callbacks;

enum event { erase_event, imbue_event, copyfmt_event };

typedef void (*event_callback)(event, ios_base&, int index);

void register_callback(event_callback fn, int index);

ios_base(const ios_base&) = delete;

ios_base& operator=(const ios_base&) = delete;

static bool sync_with_stdio(bool sync = true);

protected:

ios_base();

private:

static int index; // \exposr

long* iarray; // \exposr

void** parray; // \exposr

};

}

\end{codeblock}

\pnum

\tcode{ios_base}

defines several member types:

\begin{itemize}

\item a class \tcode{failure} derived from \tcode{system_error};

\item a class \tcode{Init};

\item three bitmask types, \tcode{fmtflags}, \tcode{iostate}, and \tcode{openmode};

\item an enumerated type, \tcode{seekdir}.

\end{itemize}

\pnum

It maintains several kinds of data:

\begin{itemize}

\item

state information that reflects the integrity of the stream buffer;

\item

control information that influences how to interpret (format) input

sequences and how to generate (format) output sequences;

\item

additional information that is stored by the program for its private use.

\end{itemize}

\pnum

\enternote

For the sake of exposition, the maintained data is presented here as:

\begin{itemize}

\item

\tcode{static int index},

specifies the next available

unique index for the integer or pointer arrays maintained for the private use

of the program, initialized to an unspecified value;

\item

\tcode{long* iarray},

points to the first element of an

arbitrary-length

\tcode{long}

array maintained for the private use of the

program;

\item

\tcode{void** parray},

points to the first element of an

arbitrary-length pointer array maintained for the private use of the program.

\exitnote

\end{itemize}

\rSec3[ios.types]{Types}

\rSec4[ios::failure]{Class \tcode{ios_base::failure}}

\indexlibrary{\idxcode{ios_base::failure}}%

\begin{codeblock}

namespace std {

class ios_base::failure : public system_error {

public:

explicit failure(const string& msg, const error_code& ec = io_errc::stream);

explicit failure(const char* msg, const error_code& ec = io_errc::stream);

};

}

\end{codeblock}

\pnum

The class

\tcode{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.

\pnum

When throwing \tcode{ios_base::failure} exceptions, implementations should provide

values of \tcode{ec} that identify the specific reason for the failure. \enternote

Errors arising from the operating system would typically be reported as

\tcode{system_category()} errors with an error value of the error number

reported by the operating system. Errors arising from within the stream library would

typically be reported as \tcode{error_code(io_errc::stream,

iostream_category())}. \exitnote

\indexlibrary{\idxcode{failure}!\idxcode{ios_base::failure}}%

\begin{itemdecl}

explicit failure(const string& msg, , const error_code& ec = io_errc::stream);

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Constructs an object of class

\tcode{failure} by constructing the base class with \tcode{msg} and \tcode{ec}.

\end{itemdescr}

\indexlibrary{\idxcode{failure}!\idxcode{ios_base::failure}}%

\begin{itemdecl}

explicit failure(const char* msg, const error_code& ec = io_errc::stream);

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Constructs an object of class

\tcode{failure} by constructing the base class with \tcode{msg} and \tcode{ec}.

\end{itemdescr}

\rSec4[ios::fmtflags]{Type \tcode{ios_base::fmtflags}}

\indexlibrary{\idxcode{fmtflags}!\idxcode{ios_base}}%

\begin{itemdecl}

typedef @\textit{T1}@ fmtflags;

\end{itemdecl}

\begin{itemdescr}

\pnum

The type

\tcode{fmtflags}

is a bitmask type~(\ref{bitmask.types}).

Setting its elements has the effects indicated in Table~\ref{tab:iostreams.fmtflags.effects}.

\begin{libefftab}{\tcode{fmtflags} effects}{tab:iostreams.fmtflags.effects}

\tcode{boolalpha} &

insert and extract \tcode{bool} type in alphabetic format\\

\tcode{dec} &

converts integer input or generates integer output in decimal base\\

\tcode{fixed} &

generate floating-point output in fixed-point notation\\

\tcode{hex} &

converts integer input or generates integer output in hexadecimal base\\

\tcode{internal} &

adds fill characters at a designated internal point in certain generated output,

or identical to \tcode{right} if no such point is designated\\

\tcode{left} &

adds fill characters on the right (final positions) of certain generated output\\

\tcode{oct} &

converts integer input or generates integer output in octal base\\

\tcode{right} &

adds fill characters on the left (initial positions) of certain generated output\\

\tcode{scientific} &

generates floating-point output in scientific notation\\

\tcode{showbase} &

generates a prefix indicating the numeric base of generated integer output\\

\tcode{showpoint} &

generates a decimal-point character unconditionally in generated floating-point output\\

\tcode{showpos} &

generates a \tcode{+} sign in non-negative generated numeric output\\

\tcode{skipws} &

skips leading whitespace before certain input operations\\

\tcode{unitbuf} &

flushes output after each output operation\\

\tcode{uppercase} &

replaces certain lowercase letters with their uppercase equivalents in generated output\\

\end{libefftab}

\pnum

Type

\tcode{fmtflags}

also defines the constants indicated in Table~\ref{tab:iostreams.fmtflags.constants}.

\begin{floattable}{\tcode{fmtflags} constants}{tab:iostreams.fmtflags.constants}

{ll}

\topline

\lhdr{Constant} & \rhdr{Allowable values} \\ \capsep

\tcode{adjustfield} & \tcode{left | right | internal} \\

\tcode{basefield} & \tcode{dec | oct | hex} \\

\tcode{floatfield} & \tcode{scientific | fixed} \\

\end{floattable}

\end{itemdescr}

\rSec4[ios::iostate]{Type \tcode{ios_base::iostate}}

\indexlibrary{\idxcode{iostate}!\idxcode{ios_base}}%

\indexlibrary{\idxcode{ios_base}!\idxcode{iostate}}%

\begin{itemdecl}

typedef @\textit{T2}@ iostate;

\end{itemdecl}

\begin{itemdescr}

\pnum

The type

\tcode{iostate}

is a bitmask type~(\ref{bitmask.types})

that contains the elements indicated in Table~\ref{tab:iostreams.iostate.effects}.

\begin{libefftab}{\tcode{iostate} effects}{tab:iostreams.iostate.effects}

\tcode{badbit} &

indicates a loss of integrity in an input or output sequence

(such as an irrecoverable read error from a file); \\

\tcode{eofbit} &

indicates that an input operation reached the end of an input sequence; \\

\tcode{failbit} &