29 Input/output library [input.output]

29.9 File-based streams [file.streams]

29.9.2 Class template basic_­filebuf [filebuf]

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;

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

    // [filebuf.assign], assign 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();

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

  template<class charT, class traits>
    void swap(basic_filebuf<charT, traits>& x,
              basic_filebuf<charT, traits>& y);
}
1
#
The class basic_­filebuf<charT, traits> associates both the input sequence and the output sequence with a file.
2
#
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.
3
#
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.
4
#
An instance of basic_­filebuf behaves as described in [filebuf] provided traits​::​pos_­type is fpos<traits​::​​state_­type>.
Otherwise the behavior is undefined.
5
#
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());

29.9.2.1 Constructors [filebuf.cons]

🔗
basic_filebuf();
1
#
Effects: Initializes the base class with basic_­streambuf<charT, traits>() ([streambuf.cons]).
2
#
Postconditions: is_­open() == false.
🔗
basic_filebuf(basic_filebuf&& rhs);
3
#
Effects: 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.
4
#
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.
  • (4.1)
    is_­open() == rhs_­p.is_­open()
  • (4.2)
    rhs_­a.is_­open() == false
  • (4.3)
    gptr() - eback() == rhs_­p.gptr() - rhs_­p.eback()
  • (4.4)
    egptr() - eback() == rhs_­p.egptr() - rhs_­p.eback()
  • (4.5)
    pptr() - pbase() == rhs_­p.pptr() - rhs_­p.pbase()
  • (4.6)
    epptr() - pbase() == rhs_­p.epptr() - rhs_­p.pbase()
  • (4.7)
    if (eback()) eback() != rhs_­a.eback()
  • (4.8)
    if (gptr()) gptr() != rhs_­a.gptr()
  • (4.9)
    if (egptr()) egptr() != rhs_­a.egptr()
  • (4.10)
    if (pbase()) pbase() != rhs_­a.pbase()
  • (4.11)
    if (pptr()) pptr() != rhs_­a.pptr()
  • (4.12)
    if (epptr()) epptr() != rhs_­a.epptr()
🔗
virtual ~basic_filebuf();
5
#
Effects: 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]).

29.9.2.2 Assignment and swap [filebuf.assign]

🔗
basic_filebuf& operator=(basic_filebuf&& rhs);
1
#
Effects: Calls 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]).
2
#
Returns: *this.
🔗
void swap(basic_filebuf& rhs);
3
#
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);
4
#
Effects: Equivalent to: x.swap(y).

29.9.2.3 Member functions [filebuf.members]

🔗
bool is_open() const;
1
#
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* 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]
2
#
Preconditions: s points to a NTCTS ([defns.ntcts]).
3
#
Effects: If is_­open() != false, returns a null pointer.
Otherwise, initializes the filebuf as required.
It then opens the file to which s resolves, if possible, as if by a call to fopen with the second argument determined from mode & ~ios_­base​::​ate as indicated in Table 126.
If mode is not some combination of flags shown in the table then the open fails.
Table 126: File open modes   [tab:filebuf.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"
4
#
If the open operation succeeds and ios_­base​::​ate is set in mode, positions the file to the end (as if by calling fseek(file, 0, SEEK_­END), where file is the pointer returned by calling fopen).323
5
#
If the repositioning operation fails, calls close() and returns a null pointer to indicate failure.
6
#
Returns: this if successful, a null pointer otherwise.
🔗
basic_filebuf* open(const string& s, ios_base::openmode mode); basic_filebuf* open(const filesystem::path& s, ios_base::openmode mode);
7
#
Returns: open(s.c_­str(), mode);
🔗
basic_filebuf* close();
8
#
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 fclose(file)).
If any of the calls made by the function, including 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.
9
#
Returns: this on success, a null pointer otherwise.
10
#
Postconditions: is_­open() == false.
323)
The macro SEEK_­END is defined, and the function signatures fopen(const char*, const char*) and fseek(FILE*, long, int) are declared, in <cstdio> ([cstdio.syn]).
⮥

29.9.2.4 Overridden virtual functions [filebuf.virtuals]

🔗
streamsize showmanyc() override;
1
#
Effects: Behaves the same as basic_­streambuf​::​showmanyc() ([streambuf.virtuals]).
2
#
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() override;
3
#
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() override;
4
#
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()) override;
5
#
Effects: Puts back the character designated by c to the input sequence, if possible, in one of three ways:
  • (5.1)
    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.
  • (5.2)
    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.
  • (5.3)
    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).
6
#
Returns: As specified above, or traits​::​eof() to indicate failure.
7
#
Remarks: If is_­open() == false, the function always fails.
8
#
The function does not put back a character directly to the input sequence.
9
#
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()) override;
10
#
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
  • (10.1)
    If r == codecvt_­base​::​error then fail.
  • (10.2)
    If r == codecvt_­base​::​noconv then output characters from b up to (and not including) p.
  • (10.3)
    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).
  • (10.4)
    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.
11
#
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) override;
12
#
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) override;
13
#
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 fseek(file, width * off, whence), otherwise call fseek(file, 0, whence).
14
#
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 127.
Table 127: seekoff effects   [tab:filebuf.seekoff]
way Value
stdio Equivalent
basic_­ios​::​beg
SEEK_­SET
basic_­ios​::​cur
SEEK_­CUR
basic_­ios​::​end
SEEK_­END
15
#
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) override;
16
#
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. 1.if (om & ios_­base​::​out) != 0, then update the output sequence and write any unshift sequence;
  2. 2.set the file position to sp as if by a call to fsetpos;
  3. 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.
17
#
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.
18
#
Returns: sp on success.
Otherwise returns pos_­type(off_­type(-1)).
🔗
int sync() override;
19
#
Effects: If a put area exists, calls filebuf​::​overflow to write the characters to the file, then flushes the file as if by calling fflush(file).
If a get area exists, the effect is implementation-defined.
🔗
void imbue(const locale& loc) override;
20
#
Preconditions: 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.
21
#
Effects: Causes characters inserted or extracted after this call to be converted according to loc until another call of imbue.
22
#
Remarks: 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.