31 Input/output library [input.output]

31.10 File-based streams [file.streams]

31.10.3 Class template basic_filebuf [filebuf]

31.10.3.1 General [filebuf.general]

namespace std { template<class charT, class traits = char_traits<charT>> class basic_filebuf : public basic_streambuf<charT, traits> { public: using char_type = charT; using int_type = typename traits::int_type; using pos_type = typename traits::pos_type; using off_type = typename traits::off_type; using traits_type = traits; using native_handle_type = implementation-defined; // see [file.native] // [filebuf.cons], constructors/destructor basic_filebuf(); basic_filebuf(const basic_filebuf&) = delete; basic_filebuf(basic_filebuf&& rhs); virtual ~basic_filebuf(); // [filebuf.assign], assignment and swap basic_filebuf& operator=(const basic_filebuf&) = delete; basic_filebuf& operator=(basic_filebuf&& rhs); void swap(basic_filebuf& rhs); // [filebuf.members], members bool is_open() const; basic_filebuf* open(const char* s, ios_base::openmode mode); basic_filebuf* open(const filesystem::path::value_type* s, ios_base::openmode mode); // wide systems only; see [fstream.syn] basic_filebuf* open(const string& s, ios_base::openmode mode); basic_filebuf* open(const filesystem::path& s, ios_base::openmode mode); basic_filebuf* close(); native_handle_type native_handle() const noexcept; protected: // [filebuf.virtuals], overridden virtual functions streamsize showmanyc() override; int_type underflow() override; int_type uflow() override; int_type pbackfail(int_type c = traits::eof()) override; int_type overflow (int_type c = traits::eof()) override; basic_streambuf<charT, traits>* setbuf(char_type* s, streamsize n) override; pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out) override; pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out) override; int sync() override; void imbue(const locale& loc) override; }; }

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 C standard library FILEs.

In particular:

(3.1)
If the file is not open for reading the input sequence cannot be read.
(3.2)
If the file is not open for writing the output sequence cannot be written.
(3.3)
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.

The file associated with a basic_filebuf has an associated value of type native_handle_type, called the native handle ([file.native]) of that file.

This native handle can be obtained by calling the member function native_handle.

For any opened basic_filebuf f, the native handle returned by f.native_handle() is invalidated when f.close() is called, or f is destroyed.

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 subclauses, obtained as if by const codecvt<charT, char, typename traits::state_type>& a_codecvt = use_facet<codecvt<charT, char, typename traits::state_type>>(getloc());