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

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

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

input/output operations.

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>} \\ \rowsep

\ref{filesystems} & File systems & \tcode{<filesystem>} \\ \rowsep

\ref{c.files} & C library files & \tcode{<cstdio>} \\

& & \tcode{<cinttypes>} \\

\end{libsumtab}

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

described in this 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}

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}

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

\impldef{behavior of iostream classes when \tcode{traits::pos_type} is not

\tcode{streampos} or when \tcode{traits::\brk{}off_type} is not \tcode{streamoff}}.

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

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

and any other \impldef{set of character types that iostreams templates can be instantiated for}

character types that satisfy the requirements for a character on which any of

the iostream components can be instantiated.

\rSec2[iostreams.threadsafety]{Thread safety}

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}).

\begin{note} Data races result in undefined behavior~(\ref{intro.multithread}). \end{note}

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}

\rSec2[iosfwd.syn]{Header \tcode{<iosfwd>} synopsis}

\indextext{\idxhdr{iosfwd}}%

\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;

using ios = basic_ios<char>;

using wios = basic_ios<wchar_t>;

using streambuf = basic_streambuf<char>;

using istream = basic_istream<char>;

using ostream = basic_ostream<char>;

using iostream = basic_iostream<char>;

using stringbuf = basic_stringbuf<char>;

using istringstream = basic_istringstream<char>;

using ostringstream = basic_ostringstream<char>;

using stringstream = basic_stringstream<char>;

using filebuf = basic_filebuf<char>;

using ifstream = basic_ifstream<char>;

using ofstream = basic_ofstream<char>;

using fstream = basic_fstream<char>;

using wstreambuf = basic_streambuf<wchar_t>;

using wistream = basic_istream<wchar_t>;

using wostream = basic_ostream<wchar_t>;

using wiostream = basic_iostream<wchar_t>;

using wstringbuf = basic_stringbuf<wchar_t>;

using wistringstream = basic_istringstream<wchar_t>;

using wostringstream = basic_ostringstream<wchar_t>;

using wstringstream = basic_stringstream<wchar_t>;

using wfilebuf = basic_filebuf<wchar_t>;

using wifstream = basic_ifstream<wchar_t>;

using wofstream = basic_ofstream<wchar_t>;

using wfstream = basic_fstream<wchar_t>;

template <class state> class fpos;

using streampos = fpos<char_traits<char>::state_type>;

using wstreampos = fpos<char_traits<wchar_t>::state_type>;

}

\end{codeblock}

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 occurrences of default arguments.}

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

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

The

class template specialization

\tcode{basic_streambuf<charT, traits>}

serves as a base class for class templates

\tcode{basic_stringbuf}

and

\tcode{basic_filebuf}.

The

class template specialization

\tcode{basic_istream<charT, traits>}

serves as a base class for class templates

\tcode{basic_istringstream}

and

\tcode{basic_ifstream}.

The

class template specialization

\tcode{basic_ostream<charT, traits>}

serves as a base class for class templates

\tcode{basic_ostringstream}

and

\tcode{basic_ofstream}.

The

class template specialization

\tcode{basic_iostream<charT, traits>}

serves as a base class for class templates

\tcode{basic_stringstream}

and

\tcode{basic_fstream}.

Other \grammarterm{typedef-name}{s} define instances of

class templates

specialized for

\tcode{char}

or

\tcode{wchar_t}

types.

Specializations of the class template

\tcode{fpos}

are

used for specifying file position information.

The types

\tcode{streampos}

and

\tcode{wstreampos}

are used for positioning streams specialized on

\tcode{char}

and

\tcode{wchar_t}

respectively.

\begin{note}

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

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

using streampos = fpos<_STATE>;

template<> struct char_traits<char> {

using pos_type = streampos;

}

\end{codeblock}

\end{note}

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

\rSec2[iostream.syn]{Header \tcode{<iostream>} synopsis}

\indextext{\idxhdr{iostream}}%

\indexlibrary{\idxhdr{iostream}}%

\begin{codeblock}

#include <ios> // see \ref{ios.syn}

#include <streambuf> // see \ref{streambuf.syn}

#include <istream> // see \ref{istream.syn}

#include <ostream> // see \ref{ostream.syn}

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}

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

In this Clause, the type name \tcode{FILE} refers to

the type

\tcode{FILE}

declared in

\tcode{<cstdio>}

\indextext{\idxhdr{cstdio}}%

\indexlibrary{\idxhdr{cstdio}}%

(\ref{cstdio.syn}).

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}}%

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}~(\ref{basic.start.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.

Mixing operations on corresponding wide- and narrow-character streams

follows the same semantics as mixing such operations on

\tcode{FILE}s,

as specified in the C standard library.

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}). \begin{note} Users must still synchronize concurrent use of these objects and streams by multiple threads if they wish to avoid interleaved characters. \end{note}

\xref~ISO C 7.21.2.

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

\indexlibrary{\idxcode{cin}}%

\begin{itemdecl}

istream cin;

\end{itemdecl}

\begin{itemdescr}

The object

\tcode{cin}

controls input from a stream buffer

associated with the object

\tcode{stdin},

declared in

\indextext{\idxhdr{cstdio}}%

\indexlibrary{\idxhdr{cstdio}}%

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

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}

The object

\tcode{cout}

controls output to a stream buffer

associated with the object

\tcode{stdout},

declared in

\indextext{\idxhdr{cstdio}}%

\indexlibrary{\idxhdr{cstdio}}%

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

\end{itemdescr}

\indexlibrary{\idxcode{cerr}}%

\begin{itemdecl}

ostream cerr;

\end{itemdecl}

\begin{itemdescr}

The object

\tcode{cerr}

controls output to a stream buffer

associated with the object

\tcode{stderr},

declared in

\indextext{\idxhdr{cstdio}}%

\indexlibrary{\idxhdr{cstdio}}%

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

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}

The object

\tcode{clog}

controls output to a stream buffer

associated with the object

\tcode{stderr},

declared in

\indextext{\idxhdr{cstdio}}%

\indexlibrary{\idxhdr{cstdio}}%

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

\end{itemdescr}

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

\indexlibrary{\idxcode{wcin}}%

\begin{itemdecl}

wistream wcin;

\end{itemdecl}

\begin{itemdescr}

The object

\tcode{wcin}

controls input from a stream buffer

associated with the object

\tcode{stdin},

declared in

\indextext{\idxhdr{cstdio}}%

\indexlibrary{\idxhdr{cstdio}}%

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

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}

The object

\tcode{wcout}

controls output to a stream buffer

associated with the object

\tcode{stdout},

declared in

\indextext{\idxhdr{cstdio}}%

\indexlibrary{\idxhdr{cstdio}}%

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

\end{itemdescr}

\indexlibrary{\idxcode{wcerr}}%

\begin{itemdecl}

wostream wcerr;

\end{itemdecl}

\begin{itemdescr}

The object

\tcode{wcerr}

controls output to a stream buffer

associated with the object

\tcode{stderr},

declared in

\indextext{\idxhdr{cstdio}}%

\indexlibrary{\idxhdr{cstdio}}%

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

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}

The object

\tcode{wclog}

controls output to a stream buffer

associated with the object

\tcode{stderr},

declared in

\indextext{\idxhdr{cstdio}}%

\indexlibrary{\idxhdr{cstdio}}%

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

\end{itemdescr}

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

\rSec2[ios.syn]{Header \tcode{<ios>} synopsis}

\indextext{\idxhdr{ios}}%

\indexlibrary{\idxhdr{ios}}%

\indexlibrary{\idxcode{io_errc}}%

\begin{codeblock}

#include <iosfwd> // see \ref{iosfwd.syn}

namespace std {

using streamoff = @\impdef@;

using streamsize = @\impdef@;

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) noexcept;

error_condition make_error_condition(io_errc e) noexcept;

const error_category& iostream_category() noexcept;

}

\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}

using streamoff = @\impdef@;

\end{itemdecl}

\begin{itemdescr}

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}

using streamsize = @\impdef@;

\end{itemdecl}

\begin{itemdescr}

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; // see below

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

using fmtflags = @\textit{T1}@;

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}

using iostate = @\textit{T2}@;

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}

using openmode = @\textit{T3}@;

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}

using seekdir = @\textit{T4}@;

static constexpr seekdir beg = @\unspec@;

static constexpr seekdir cur = @\unspec@;

static constexpr seekdir end = @\unspec@;

class Init;

// \ref{fmtflags.state}, \tcode{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 };

using event_callback = void (*)(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; // \expos

long* iarray; // \expos

void** parray; // \expos

};

}

\end{codeblock}

\tcode{ios_base}

defines several member types:

\begin{itemize}

\item a type \tcode{failure}, defined as either a class derived from

\tcode{system_error} or a synonym for a class 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}

It maintains several kinds of data:

\begin{itemize}

state information that reflects the integrity of the stream buffer;

control information that influences how to interpret (format) input

sequences and how to generate (format) output sequences;

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

\end{itemize}

\begin{note}

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

\begin{itemize}

\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;

\tcode{long* iarray},

points to the first element of an

arbitrary-length

\tcode{long}

array maintained for the private use of the

program;

\tcode{void** parray},

points to the first element of an

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

\end{itemize}

\end{note}

\rSec3[ios.types]{Types}

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

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

\indexlibrary{\idxcode{ios_base}!\idxcode{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}

An implementation is permitted to define \tcode{ios_base::failure}

as a synonym for a class with equivalent functionality

to class \tcode{ios_base::failure} shown in this subclause.

\begin{note}

When \tcode{ios_base::failure} is a synonym for another type

it shall provide a nested type \tcode{failure},

to emulate the injected class name.

\end{note}

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.

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

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

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())}. \end{note}

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

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

Constructs an object of class

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

\end{itemdescr}

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

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

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}}

\indexlibrarymember{fmtflags}{ios_base}%

\begin{itemdecl}

using fmtflags = @\textit{T1}@;

\end{itemdecl}

\begin{itemdescr}

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}

Type