27 Input/output library [input.output]

27.9 File-based streams [file.streams]

27.9.1 File streams [fstreams]

The header <fstream> defines four class templates and eight types that associate stream buffers with files and assist reading and writing files.

Header <fstream> synopsis

namespace std {
  template <class charT, class traits = char_traits<charT> >
    class basic_filebuf;
  typedef basic_filebuf<char>    filebuf;
  typedef basic_filebuf<wchar_t> wfilebuf;

  template <class charT, class traits = char_traits<charT> >
    class basic_ifstream;
  typedef basic_ifstream<char>    ifstream;
  typedef basic_ifstream<wchar_t> wifstream;

  template <class charT, class traits = char_traits<charT> >
    class basic_ofstream;
  typedef basic_ofstream<char>    ofstream;
  typedef basic_ofstream<wchar_t> wofstream;

  template <class charT, class traits = char_traits<charT> >
    class basic_fstream;
  typedef basic_fstream<char>     fstream;
  typedef basic_fstream<wchar_t> wfstream;
}

In this subclause, the type name FILE refers to the type FILE declared in <cstdio> ([c.files]).

Note: The class template basic_filebuf treats a file as a source or sink of bytes. In an environment that uses a large character set, the file typically holds multibyte character sequences and the basic_filebuf object converts those multibyte sequences into wide character sequences.  — end note ]

27.9.1.1 Class template basic_filebuf [filebuf]

namespace std {
  template <class charT, class traits = char_traits<charT> >
  class basic_filebuf : public basic_streambuf<charT,traits> {
  public:
    typedef charT                     char_type;
    typedef typename traits::int_type int_type;
    typedef typename traits::pos_type pos_type;
    typedef typename traits::off_type off_type;
    typedef traits                    traits_type;

    // [filebuf.cons] Constructors/destructor:
    basic_filebuf();
    basic_filebuf(const basic_filebuf& rhs) = delete;
    basic_filebuf(basic_filebuf&& rhs);
    virtual ~basic_filebuf();

    // [filebuf.assign] Assign/swap:
    basic_filebuf& operator=(const basic_filebuf& rhs) = delete;
    basic_filebuf& operator=(basic_filebuf&& rhs);
    void swap(basic_filebuf& rhs);

     // [filebuf.members] Members:
    bool is_open() const;
    basic_filebuf<charT,traits>* open(const char* s,
        ios_base::openmode mode);
    basic_filebuf<charT,traits>* open(const string& s,
        ios_base::openmode mode);
    basic_filebuf<charT,traits>* close();

  protected:
    // [filebuf.virtuals] Overridden virtual functions:
    virtual streamsize showmanyc();
    virtual int_type underflow();
    virtual int_type uflow();
    virtual int_type pbackfail(int_type c = traits::eof());
    virtual int_type overflow (int_type c = traits::eof());

    virtual basic_streambuf<charT,traits>*
        setbuf(char_type* s, streamsize n);
    virtual pos_type seekoff(off_type off, ios_base::seekdir way,
        ios_base::openmode which = ios_base::in | ios_base::out);
    virtual pos_type seekpos(pos_type sp,
        ios_base::openmode which = ios_base::in | ios_base::out);
    virtual int      sync();
    virtual void     imbue(const locale& loc);
  };

  template <class charT, class traits>
  void swap(basic_filebuf<charT, traits>& x,
            basic_filebuf<charT, traits>& y);
}

The class basic_filebuf<charT,traits> associates both the input sequence and the output sequence with a file.

The restrictions on reading and writing a sequence controlled by an object of class basic_filebuf<charT, traits> are the same as for reading and writing with the Standard C library FILEs.

In particular:

  • If the file is not open for reading the input sequence cannot be read.

  • If the file is not open for writing the output sequence cannot be written.

  • A joint file position is maintained for both the input sequence and the output sequence.

An instance of basic_filebuf behaves as described in [filebuf] provided traits::pos_type is fpos<traits::state_type>. Otherwise the behavior is undefined.

In order to support file I/O and multibyte/wide character conversion, conversions are performed using members of a facet, referred to as a_codecvt in following sections, obtained as if by

const codecvt<charT,char,typename traits::state_type>& a_codecvt =
  use_facet<codecvt<charT,char,typename traits::state_type> >(getloc());

27.9.1.2 basic_filebuf constructors [filebuf.cons]

basic_filebuf();

Effects: Constructs an object of class basic_filebuf<charT,traits>, initializing the base class with basic_streambuf<charT,traits>() ([streambuf.cons]).

Postcondition: is_open() == false.

basic_filebuf(basic_filebuf&& rhs);

Effects: Move constructs from the rvalue rhs. It is implementation-defined whether the sequence pointers in *this (eback(), gptr(), egptr(), pbase(), pptr(), epptr()) obtain the values which rhs had. Whether they do or not, *this and rhs reference separate buffers (if any at all) after the construction. Additionally *this references the file which rhs did before the construction, and rhs references no file after the construction. The openmode, locale and any other state of rhs is also copied.

Postconditions: Let rhs_p refer to the state of rhs just prior to this construction and let rhs_a refer to the state of rhs just after this construction.

  • is_open() == rhs_p.is_open()

  • rhs_a.is_open() == false

  • gptr() - eback() == rhs_p.gptr() - rhs_p.eback()

  • egptr() - eback() == rhs_p.egptr() - rhs_p.eback()

  • pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()

  • epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase()

  • if (eback()) eback() != rhs_a.eback()

  • if (gptr()) gptr() != rhs_a.gptr()

  • if (egptr()) egptr() != rhs_a.egptr()

  • if (pbase()) pbase() != rhs_a.pbase()

  • if (pptr()) pptr() != rhs_a.pptr()

  • if (epptr()) epptr() != rhs_a.epptr()

virtual ~basic_filebuf();

Effects: Destroys an object of class basic_filebuf<charT,traits>. Calls close(). If an exception occurs during the destruction of the object, including the call to close(), the exception is caught but not rethrown (see [res.on.exception.handling]).

27.9.1.3 Assign and swap [filebuf.assign]

basic_filebuf& operator=(basic_filebuf&& rhs);

Effects: Calls this->close() then move assigns from rhs. After the move assignment *this has the observable state it would have had if it had been move constructed from rhs (see [filebuf.cons]).

Returns: *this.

void swap(basic_filebuf& rhs);

Effects: Exchanges the state of *this and rhs.

template <class charT, class traits> void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);

Effects: x.swap(y).

27.9.1.4 Member functions [filebuf.members]

bool is_open() const;

Returns: true if a previous call to open succeeded (returned a non-null value) and there has been no intervening call to close.

basic_filebuf<charT,traits>* open(const char* s, ios_base::openmode mode);

Effects: If is_open() != false, returns a null pointer. Otherwise, initializes the filebuf as required. It then opens a file, if possible, whose name is the ntbs s (as if by calling std::fopen(s,modstr)). The ntbs modstr is determined from mode & ~ios_base::ate as indicated in Table [tab:iostreams.file.open.modes]. If mode is not some combination of flags shown in the table then the open fails.

Table 132 — File open modes
ios_base flag combination stdio equivalent
binary in out trunc app
+ "w"
+ + "a"
+ "a"
+ + "w"
+ "r"
+ + "r+"
+ + + "w+"
+ + + "a+"
+ + "a+"
+ + "wb"
+ + + "ab"
+ + "ab"
+ + + "wb"
+ + "rb"
+ + + "r+b"
+ + + + "w+b"
+ + + + "a+b"
+ + + "a+b"

If the open operation succeeds and (mode & ios_base::ate) != 0, positions the file to the end (as if by calling std::fseek(file,0,SEEK_END)).334

If the repositioning operation fails, calls close() and returns a null pointer to indicate failure.

Returns: this if successful, a null pointer otherwise.

basic_filebuf<charT,traits>* open(const string& s, ios_base::openmode mode);

Returns: open(s.c_str(), mode);

basic_filebuf<charT,traits>* close();

Effects: If is_open() == false, returns a null pointer. If a put area exists, calls overflow(traits::eof()) to flush characters. If the last virtual member function called on *this (between underflow, overflow, seekoff, and seekpos) was overflow then calls a_codecvt.unshift (possibly several times) to determine a termination sequence, inserts those characters and calls overflow(traits::eof()) again. Finally, regardless of whether any of the preceding calls fails or throws an exception, the function closes the file (as if by calling std::fclose(file)).335 If any of the calls made by the function, including std::fclose, fails, close fails by returning a null pointer. If one of these calls throws an exception, the exception is caught and rethrown after closing the file.

Returns: this on success, a null pointer otherwise.

Postcondition: is_open() == false.

The macro SEEK_END is defined, and the function signatures fopen(const char*, const char*) and fseek(FILE*, long, int) are declared, in <cstdio> ([c.files]).

The function signature fclose(FILE*) is declared in <cstdio> ([c.files]).

27.9.1.5 Overridden virtual functions [filebuf.virtuals]

streamsize showmanyc();

Effects: Behaves the same as basic_streambuf::showmanyc() ([streambuf.virtuals]).

Remarks: An implementation might well provide an overriding definition for this function signature if it can determine that more characters can be read from the input sequence.

int_type underflow();

Effects: Behaves according to the description of basic_streambuf<charT,traits>::underflow(), with the specialization that a sequence of characters is read from the input sequence as if by reading from the associated file into an internal buffer ( extern_buf) and then as if by doing

char   extern_buf[XSIZE];
char*  extern_end;
charT  intern_buf[ISIZE];
charT* intern_end;
codecvt_base::result r =
  a_codecvt.in(state, extern_buf, extern_buf+XSIZE, extern_end,
               intern_buf, intern_buf+ISIZE, intern_end);

This shall be done in such a way that the class can recover the position (fpos_t) corresponding to each character between intern_buf and intern_end. If the value of r indicates that a_codecvt.in() ran out of space in intern_buf, retry with a larger intern_buf.

int_type uflow();

Effects: Behaves according to the description of basic_streambuf<charT,traits>::uflow(), with the specialization that a sequence of characters is read from the input with the same method as used by underflow.

int_type pbackfail(int_type c = traits::eof());

Effects: Puts back the character designated by c to the input sequence, if possible, in one of three ways:

  • If traits::eq_int_type(c,traits::eof()) returns false and if the function makes a putback position available and if traits::eq(to_char_type(c),gptr()[-1]) returns true, decrements the next pointer for the input sequence, gptr().

    Returns: c.

  • If traits::eq_int_type(c,traits::eof()) returns false and if the function makes a putback position available and if the function is permitted to assign to the putback position, decrements the next pointer for the input sequence, and stores c there.

    Returns: c.

  • If traits::eq_int_type(c,traits::eof()) returns true, and if either the input sequence has a putback position available or the function makes a putback position available, decrements the next pointer for the input sequence, gptr().

    Returns: traits::not_eof(c).

Returns: traits::eof() to indicate failure.

Remarks: If is_open() == false, the function always fails.

The function does not put back a character directly to the input sequence.

If the function can succeed in more than one of these ways, it is unspecified which way is chosen. The function can alter the number of putback positions available as a result of any call.

int_type overflow(int_type c = traits::eof());

Effects: Behaves according to the description of basic_streambuf<charT,traits>::overflow(c), except that the behavior of “consuming characters” is performed by first converting as if by:

charT* b = pbase();
charT* p = pptr();
charT* end;
char   xbuf[XSIZE];
char*  xbuf_end;
codecvt_base::result r =
  a_codecvt.out(state, b, p, end, xbuf, xbuf+XSIZE, xbuf_end);

and then

  • If r == codecvt_base::error then fail.

  • If r == codecvt_base::noconv then output characters from b up to (and not including) p.

  • If r == codecvt_base::partial then output to the file characters from xbuf up to xbuf_end, and repeat using characters from end to p. If output fails, fail (without repeating).

  • Otherwise output from xbuf to xbuf_end, and fail if output fails. At this point if b != p and b == end (xbuf isn't large enough) then increase XSIZE and repeat from the beginning.

Returns: traits::not_eof(c) to indicate success, and traits::eof() to indicate failure. If is_open() == false, the function always fails.

basic_streambuf* setbuf(char_type* s, streamsize n);

Effects: If setbuf(0,0) is called on a stream before any I/O has occurred on that stream, the stream becomes unbuffered. Otherwise the results are implementation-defined. “Unbuffered” means that pbase() and pptr() always return null and output to the file should appear as soon as possible.

pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out);

Effects: Let width denote a_codecvt.encoding(). If is_open() == false, or off != 0 && width <= 0, then the positioning operation fails. Otherwise, if way != basic_ios::cur or off != 0, and if the last operation was output, then update the output sequence and write any unshift sequence. Next, seek to the new position: if width > 0, call std::fseek(file, width * off, whence), otherwise call std::fseek(file, 0, whence).

Remarks: “The last operation was output” means either the last virtual operation was overflow or the put buffer is non-empty. “Write any unshift sequence” means, if width if less than zero then call a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end) and output the resulting unshift sequence. The function determines one of three values for the argument whence, of type int, as indicated in Table [tab:iostreams.seekoff.effects].

Table 133seekoff effects
way Valuestdio Equivalent
basic_ios::beg SEEK_SET
basic_ios::cur SEEK_CUR
basic_ios::end SEEK_END

Returns: A newly constructed pos_type object that stores the resultant stream position, if possible. If the positioning operation fails, or if the object cannot represent the resultant stream position, returns pos_type(off_type(-1)).

pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out);

Alters the file position, if possible, to correspond to the position stored in sp (as described below). Altering the file position performs as follows:

  1. if (om & ios_base::out) != 0, then update the output sequence and write any unshift sequence;

  2. set the file position to sp;

  3. if (om & ios_base::in) != 0, then update the input sequence;

where om is the open mode passed to the last call to open(). The operation fails if is_open() returns false.

If sp is an invalid stream position, or if the function positions neither sequence, the positioning operation fails. If sp has not been obtained by a previous successful call to one of the positioning functions (seekoff or seekpos) on the same file the effects are undefined.

Returns: sp on success. Otherwise returns pos_type(off_type(-1)).

int sync();

Effects: If a put area exists, calls filebuf::overflow to write the characters to the file. If a get area exists, the effect is implementation-defined.

void imbue(const locale& loc);

Requires: If the file is not positioned at its beginning and the encoding of the current locale as determined by a_codecvt.encoding() is state-dependent ([locale.codecvt.virtuals]) then that facet is the same as the corresponding facet of loc.

Effects: Causes characters inserted or extracted after this call to be converted according to loc until another call of imbue.

Remark: This may require reconversion of previously converted characters. This in turn may require the implementation to be able to reconstruct the original contents of the file.

27.9.1.6 Class template basic_ifstream [ifstream]

namespace std {
  template <class charT, class traits = char_traits<charT> >
  class basic_ifstream : public basic_istream<charT,traits> {
  public:
    typedef charT                     char_type;
    typedef typename traits::int_type int_type;
    typedef typename traits::pos_type pos_type;
    typedef typename traits::off_type off_type;
    typedef traits                    traits_type;

    // [ifstream.cons] Constructors:
    basic_ifstream();
    explicit basic_ifstream(const char* s,
        ios_base::openmode mode = ios_base::in);
    explicit basic_ifstream(const string& s,
        ios_base::openmode mode = ios_base::in);
    basic_ifstream(const basic_ifstream& rhs) = delete;
    basic_ifstream(basic_ifstream&& rhs);

    // [ifstream.assign] Assign/swap:
    basic_ifstream& operator=(const basic_ifstream& rhs) = delete;
    basic_ifstream& operator=(basic_ifstream&& rhs);
    void swap(basic_ifstream& rhs);

    // [ifstream.members] Members:
    basic_filebuf<charT,traits>* rdbuf() const;

    bool is_open() const;
    void open(const char* s, ios_base::openmode mode = ios_base::in);
    void open(const string& s, ios_base::openmode mode = ios_base::in);
    void close();
  private:
    basic_filebuf<charT,traits> sb; // exposition only
  };

  template <class charT, class traits>
  void swap(basic_ifstream<charT, traits>& x,
            basic_ifstream<charT, traits>& y);
}

The class basic_ifstream<charT, traits> supports reading from named files. It uses a basic_filebuf<charT, traits> object to control the associated sequence. For the sake of exposition, the maintained data is presented here as:

  • sb, the filebuf object.

27.9.1.7 basic_ifstream constructors [ifstream.cons]

basic_ifstream();

Effects: Constructs an object of class basic_ifstream<charT,traits>, initializing the base class with basic_istream(&sb) and initializing sb with basic_filebuf<charT,traits>()) ([istream.cons], [filebuf.cons]).

explicit basic_ifstream(const char* s, ios_base::openmode mode = ios_base::in);

Effects: Constructs an object of class basic_ifstream, initializing the base class with basic_istream(&sb) and initializing sb with basic_filebuf<charT, traits>()) ([istream.cons], [filebuf.cons]), then calls rdbuf()->open(s, mode | ios_base::in). If that function returns a null pointer, calls setstate(failbit).

explicit basic_ifstream(const string& s, ios_base::openmode mode = ios_base::in);

Effects: the same as basic_ifstream(s.c_str(), mode).

basic_ifstream(basic_ifstream&& rhs);

Effects: Move constructs from the rvalue rhs. This is accomplished by move constructing the base class, and the contained basic_filebuf. Next basic_istream<charT,traits>::set_rdbuf(&sb) is called to install the contained basic_filebuf.

27.9.1.8 Assign and swap [ifstream.assign]

basic_ifstream& operator=(basic_ifstream&& rhs);

Effects: Move assigns the base and members of *this from the base and corresponding members of rhs.

Returns: *this.

void swap(basic_ifstream& rhs);

Effects: Exchanges the state of *this and rhs by calling basic_istream<charT,traits>::swap(rhs) and sb.swap(rhs.sb).

template <class charT, class traits> void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);

Effects: x.swap(y).

27.9.1.9 Member functions [ifstream.members]

basic_filebuf<charT,traits>* rdbuf() const;

Returns: const_cast<basic_filebuf<charT,traits>*>(&sb).

bool is_open() const;

Returns: rdbuf()->is_open().

void open(const char* s, ios_base::openmode mode = ios_base::in);

Effects: Calls rdbuf()->open(s, mode | ios_base::in). If that function does not return a null pointer calls clear(), otherwise calls setstate(failbit) (which may throw ios_base::failure ([iostate.flags])).

void open(const string& s, ios_base::openmode mode = ios_base::in);

Effects: calls open(s.c_str(), mode).

void close();

Effects: Calls rdbuf()->close() and, if that function returns a null pointer, calls setstate(failbit) (which may throw ios_base::failure ([iostate.flags])).

27.9.1.10 Class template basic_ofstream [ofstream]

namespace std {
  template <class charT, class traits = char_traits<charT> >
  class basic_ofstream : public basic_ostream<charT,traits> {
  public:
    typedef charT                     char_type;
    typedef typename traits::int_type int_type;
    typedef typename traits::pos_type pos_type;
    typedef typename traits::off_type off_type;
    typedef traits                    traits_type;

    // [ofstream.cons] Constructors:
    basic_ofstream();
    explicit basic_ofstream(const char* s,
        ios_base::openmode mode = ios_base::out);
    explicit basic_ofstream(const string& s,
        ios_base::openmode mode = ios_base::out);
    basic_ofstream(const basic_ofstream& rhs) = delete;
    basic_ofstream(basic_ofstream&& rhs);

    // [ofstream.assign] Assign/swap:
    basic_ofstream& operator=(const basic_ofstream& rhs) = delete;
    basic_ofstream& operator=(basic_ofstream&& rhs);
    void swap(basic_ofstream& rhs);

    // [ofstream.members] Members:
    basic_filebuf<charT,traits>* rdbuf() const;

    bool is_open() const;
    void open(const char* s, ios_base::openmode mode = ios_base::out);
    void open(const string& s, ios_base::openmode mode = ios_base::out);
    void close();
  private:
    basic_filebuf<charT,traits> sb; // exposition only
  };

  template <class charT, class traits>
  void swap(basic_ofstream<charT, traits>& x,
            basic_ofstream<charT, traits>& y);
}

The class basic_ofstream<charT, traits> supports writing to named files. It uses a basic_filebuf<charT, traits> object to control the associated sequence. For the sake of exposition, the maintained data is presented here as:

  • sb, the filebuf object.

27.9.1.11 basic_ofstream constructors [ofstream.cons]

basic_ofstream();

Effects: Constructs an object of class basic_ofstream<charT,traits>, initializing the base class with basic_ostream(&sb) and initializing sb with basic_filebuf<charT,traits>()) ([ostream.cons], [filebuf.cons]).

explicit basic_ofstream(const char* s, ios_base::openmode mode = ios_base::out);

Effects: Constructs an object of class basic_ofstream<charT,traits>, initializing the base class with basic_ostream(&sb) and initializing sb with basic_filebuf<charT,traits>()) ([ostream.cons], [filebuf.cons]), then calls rdbuf()->open(s, mode|ios_base::out). If that function returns a null pointer, calls setstate(failbit).

explicit basic_ofstream(const string& s, ios_base::openmode mode = ios_base::out);

Effects: the same as basic_ofstream(s.c_str(), mode);

basic_ofstream(basic_ofstream&& rhs);

Effects: Move constructs from the rvalue rhs. This is accomplished by move constructing the base class, and the contained basic_filebuf. Next basic_ostream<charT,traits>::set_rdbuf(&sb) is called to install the contained basic_filebuf.

27.9.1.12 Assign and swap [ofstream.assign]

basic_ofstream& operator=(basic_ofstream&& rhs);

Effects: Move assigns the base and members of *this from the base and corresponding members of rhs.

Returns: *this.

void swap(basic_ofstream& rhs);

Effects: Exchanges the state of *this and rhs by calling basic_ostream<charT,traits>::swap(rhs) and sb.swap(rhs.sb).

template <class charT, class traits> void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);

Effects: x.swap(y).

27.9.1.13 Member functions [ofstream.members]

basic_filebuf<charT,traits>* rdbuf() const;

Returns: const_cast<basic_filebuf<charT,traits>*>(&sb).

bool is_open() const;

Returns: rdbuf()->is_open().

void open(const char* s, ios_base::openmode mode = ios_base::out);

Effects: Calls rdbuf()->open(s, mode | ios_base::out). If that function does not return a null pointer calls clear(), otherwise calls setstate(failbit) (which may throw ios_base::failure ([iostate.flags])).

void close();

Effects: Calls rdbuf()->close() and, if that function fails (returns a null pointer), calls setstate(failbit) (which may throw ios_base::failure ([iostate.flags])).

void open(const string& s, ios_base::openmode mode = ios_base::out);

Effects: calls open(s.c_str(), mode);

27.9.1.14 Class template basic_fstream [fstream]

namespace std {
  template <class charT, class traits=char_traits<charT> >
  class basic_fstream
    : public basic_iostream<charT,traits> {

  public:
    typedef charT                     char_type;
    typedef typename traits::int_type int_type;
    typedef typename traits::pos_type pos_type;
    typedef typename traits::off_type off_type;
    typedef traits                    traits_type;

    // constructors/destructor
    basic_fstream();
    explicit basic_fstream(const char* s,
        ios_base::openmode mode = ios_base::in|ios_base::out);
    explicit basic_fstream(const string& s,
        ios_base::openmode mode = ios_base::in|ios_base::out);
    basic_fstream(const basic_fstream& rhs) = delete;
    basic_fstream(basic_fstream&& rhs);

    // [fstream.assign] Assign/swap:
    basic_fstream& operator=(const basic_fstream& rhs) = delete;
    basic_fstream& operator=(basic_fstream&& rhs);
    void swap(basic_fstream& rhs);

    // Members:
    basic_filebuf<charT,traits>* rdbuf() const;
    bool is_open() const;
    void open(const char* s,
        ios_base::openmode mode = ios_base::in|ios_base::out);
    void open(const string& s,
        ios_base::openmode mode = ios_base::in|ios_base::out);
    void close();

  private:
    basic_filebuf<charT,traits> sb; // exposition only
  };

  template <class charT, class traits>
  void swap(basic_fstream<charT, traits>& x,
            basic_fstream<charT, traits>& y);
}

The class template basic_fstream<charT,traits> supports reading and writing from named files. It uses a basic_filebuf<charT,traits> object to control the associated sequences. For the sake of exposition, the maintained data is presented here as:

  • sb, the basic_filebuf object.

27.9.1.15 basic_fstream constructors [fstream.cons]

basic_fstream();

Effects: Constructs an object of class basic_fstream<charT,traits>, initializing the base class with basic_iostream(&sb) and initializing sb with basic_filebuf<charT,traits>().

explicit basic_fstream(const char* s, ios_base::openmode mode = ios_base::in|ios_base::out);

Effects: Constructs an object of class basic_fstream<charT, traits>, initializing the base class with basic_iostream(&sb) and initializing sb with basic_filebuf<charT, traits>(). Then calls rdbuf()->open(s, mode). If that function returns a null pointer, calls setstate(failbit).

explicit basic_fstream(const string& s, ios_base::openmode mode = ios_base::in|ios_base::out);

Effects: the same as basic_fstream(s.c_str(), mode);

basic_fstream(basic_fstream&& rhs);

Effects: Move constructs from the rvalue rhs. This is accomplished by move constructing the base class, and the contained basic_filebuf. Next basic_istream<charT,traits>::set_rdbuf(&sb) is called to install the contained basic_filebuf.

27.9.1.16 Assign and swap [fstream.assign]

basic_fstream& operator=(basic_fstream&& rhs);

Effects: Move assigns the base and members of *this from the base and corresponding members of rhs.

Returns: *this.

void swap(basic_fstream& rhs);

Effects: Exchanges the state of *this and rhs by calling basic_iostream<charT,traits>::swap(rhs) and sb.swap(rhs.sb).

template <class charT, class traits> void swap(basic_fstream<charT, traits>& x, basic_fstream<charT, traits>& y);

Effects: x.swap(y).

27.9.1.17 Member functions [fstream.members]

basic_filebuf<charT,traits>* rdbuf() const;

Returns: const_cast<basic_filebuf<charT,traits>*>(&sb).

bool is_open() const;

Returns: rdbuf()->is_open().

void open(const char* s, ios_base::openmode mode = ios_base::in|ios_base::out);

Effects: Calls rdbuf()->open(s,mode). If that function does not return a null pointer calls clear(), otherwise calls setstate(failbit), (which may throw ios_base::failure) ([iostate.flags]).

void open(const string& s, ios_base::openmode mode = ios_base::in|ios_base::out);

Effects: calls open(s.c_str(), mode);

void close();

Effects: Calls rdbuf()->close() and, if that function returns returns a null pointer, calls setstate(failbit) ([iostate.flags]) (which may throw ios_base::failure).

27.9.2 C library files [c.files]

Table [tab:iostreams.hdr.cstdio] describes header <cstdio>.

Table 134 — Header <cstdio> synopsis
TypeName(s)
Macros:
BUFSIZ FOPEN_MAX SEEK_CUR TMP_MAX _IONBF stdout
EOF L_tmpnam SEEK_END _IOFBF stderr
FILENAME_MAX NULL <cstdio> SEEK_SET _IOLBF stdin
Types: FILE fpos_t size_t <cstdio>
Functions:
clearerr fopen fsetpos putc setbuf vprintf
fclose fprintf ftell putchar setvbuf vscanf
feof fputc fwrite puts snprintf vsnprintf
ferror fputs getc rename sprintf vsprintf
fflush fread getchar remove tmpfile vsscanf
fgetc freopen gets rewind tmpnam
fgetpos fscanf perror scanf ungetc
fgets fseek printf sscanf vfprintf

Calls to the function tmpnam with an argument of NULL may introduce a data race ([res.on.data.races]) with other calls to tmpnam with an argument of NULL.

See also: ISO C 7.9, Amendment 1 4.6.2.

Table [tab:iostreams.hdr.cinttypes] describes header <cinttypes>. [ Note: The macros defined by <cinttypes> are provided unconditionally. In particular, the symbol __STDC_FORMAT_MACROS, mentioned in footnote 182 of the C standard, plays no role in C++.  — end note ]

Table 135 — Header <cinttypes> synopsis
TypeName(s)
Macros:
PRI{d i o u x X}[FAST LEAST]{8 16 32 64}
PRI{d i o u x X}{MAX PTR}
SCN{d i o u x X}[FAST LEAST]{8 16 32 64}
SCN{d i o u x X}{MAX PTR}
Types: imaxdiv_t
Functions:
abs imaxabs strtoimax wcstoimax
div imaxdiv strtoumax wcstoumax

The contents of header <cinttypes> are the same as the Standard C Library header <inttypes.h>, with the following changes:

  • the header <cinttypes> includes the header <cstdint> instead of <stdint.h>, and

  • if and only if the type intmax_t designates an extended integer type ([basic.fundamental]), the following function signatures are added:

    intmax_t abs(intmax_t);
    imaxdiv_t div(intmax_t, intmax_t);
    

    which shall have the same semantics as the function signatures intmax_t imaxabs(intmax_t) and imaxdiv_t imaxdiv(intmax_t, intmax_t), respectively.