<fstream>

Description
Synopsis
Classes
Types

Description

Include the iostreams standard header <fstream> to define several classes that support iostreams operations on sequences stored in external files.

Synopsis

namespace std {
template<class E, class T = char_traits<E> >
    class basic_filebuf;
typedef basic_filebuf<char> filebuf;
typedef basic_filebuf<wchar_t> wfilebuf;
template<class E, class T = char_traits<E> >
    class basic_ifstream;
typedef basic_ifstream<char> ifstream;
typedef basic_ifstream<wchar_t> wifstream;
template<class E, class T = char_traits<E> >
    class basic_ofstream;
typedef basic_ofstream<char> ofstream;
typedef basic_ofstream<wchar_t> wofstream;
template<class E, class T = char_traits<E> >
    class basic_fstream;
typedef basic_fstream<char> fstream;
typedef basic_fstream<wchar_t> wfstream;
    }

Classes

basic_filebuf
basic_fstream
basic_ifstream
basic_ofstream

basic_filebuf

Description
Synopsis
Constructor
basic_filebuf::basic_filebuf
Types
basic_filebuf::char_type
basic_filebuf::int_type
basic_filebuf::off_type
basic_filebuf::pos_type
basic_filebuf::traits_type
Member functions
basic_filebuf::close
basic_filebuf::is_open
basic_filebuf::open
basic_filebuf::sync
Protected virtual member functions
basic_filebuf::overflow
basic_filebuf::pbackfail
basic_filebuf::seekoff
basic_filebuf::seekpos
basic_filebuf::setbuf
basic_filebuf::underflow
Description

The template class describes a stream buffer that controls the transmission of elements of type E, whose character traits are determined by the class T, to and from a sequence of elements stored in an external file.

An object of class basic_filebuf<E, T> stores a file pointer, which designates the FILE object that controls the stream associated with an open file. It also stores pointers to two file conversion facets for use by the protected member functions overflow and underflow.

Synopsis
template <class E, class T = char_traits<E> >
    class basic_filebuf : public basic_streambuf<E, T> {
public:
    typedef typename basic_streambuf<E, T>::char_type
        char_type;
    typedef typename basic_streambuf<E, T>::traits_type
        traits_type;
    typedef typename basic_streambuf<E, T>::int_type
        int_type;
    typedef typename basic_streambuf<E, T>::pos_type
        pos_type;
    typedef typename basic_streambuf<E, T>::off_type
        off_type;
    basic_filebuf();
    bool is_open() const;
    basic_filebuf *open(const char *s,
        ios_base::openmode mode);
    basic_filebuf *close();
protected:
    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 pos,
        ios_base::openmode which =
            ios_base::in | ios_base::out);
    virtual int_type underflow();
    virtual int_type pbackfail(int_type c =
        traits_type::eof());
    virtual int_type overflow(int_type c =
        traits_type::eof());
    virtual int sync();
    virtual basic_streambuf<E, T>
        *setbuf(E *s, streamsize n);
    };
Constructor
basic_filebuf::basic_filebuf

basic_filebuf();

The constructor stores a null pointer in all the pointers controlling the input buffer and the output buffer. It also stores a null pointer in the file pointer.

Types
basic_filebuf::char_type

typedef E char_type;

The type is a synonym for the template parameter E.

basic_filebuf::int_type

typedef typename traits_type::int_type int_type;

The type is a synonym for traits_type::int_type.

basic_filebuf::off_type

typedef typename traits_type::off_type off_type;

The type is a synonym for traits_type::off_type.

basic_filebuf::pos_type

typedef typename traits_type::pos_type pos_type;

The type is a synonym for traits_type::pos_type.

basic_filebuf::traits_type

typedef T traits_type;

The type is a synonym for the template parameter T.

Member functions
basic_filebuf::close

basic_filebuf *close();

The member function returns a null pointer if the file pointer fp is a null pointer. Otherwise, it calls fclose(fp). If that function returns a nonzero value, the function returns a null pointer. Otherwise, it returns this to indicate that the file was successfully closed.

For a wide stream, if any insertions have occured since the stream was opened, or since the last call to streampos, the function calls overflow(). It also inserts any sequence needed to restore the initial conversion state, by using the file conversion facet fac to call fac.unshift as needed. Each element x of type char thus produced is written to the associated stream designated by the file pointer fp as if by successive calls of the form fputc(x, fp). If the call to fac.unshift or any write fails, the function does not succeed.

basic_filebuf::is_open

bool is_open();

The member function returns true if the file pointer is not a null pointer.

basic_filebuf::open

basic_filebuf *open(const char *s,
    ios_base::openmode mode);

The member function endeavors to open the file with filename s, by calling fopen(s, strmode). Here strmode is determined from mode & ~(ate & | binary):

If mode & ios_base::binary is nonzero, the function appends b to strmode to open a binary stream instead of a text stream. It then stores the value returned by fopen in the file pointer fp. If mode & ios_base::ate is nonzero and the file pointer is not a null pointer, the function calls fseek(fp, 0, SEEK_END to position the stream at end-of-file. If that positioning operation fails, the function calls close(fp) and stores a null pointer in the file pointer.

If the file pointer is not a null pointer, the function determines the file conversion facet: use_facet< codecvt<E, char, traits_type:: state_type> >(getloc()), for use by underflow and overflow.

If the file pointer is a null pointer, the function returns a null pointer. Otherwise, it returns this.

basic_filebuf::sync

int sync();

The protected member function returns zero if the file pointer fp is a null pointer. Otherwise, it returns zero only if calls to both overflow() and fflush(fp) succeed in flushing any pending output to the stream.

Protected virtual member functions
basic_filebuf::overflow

virtual int_type overflow(int_type c =
    traits_type::eof());

If c != traits_type::eof(), the protected virtual member function endeavors to insert the element traits_type::to_char_type(c) into the output buffer. It can do so in various ways:

If the function cannot succeed, it returns traits_type::eof(). Otherwise, it returns traits_type::not_eof(c).

basic_filebuf::pbackfail

virtual int_type pbackfail(int_type c =
    traits_type::eof());

The protected virtual member function endeavors to put back an element into the input buffer, then make it the current element (pointed to by the next pointer). If c == traits_type::eof(), the element to push back is effectively the one already in the stream before the current element. Otherwise, that element is replaced by x = traits_type::to_char_type(c). The function can put back an element in various ways:

If the function cannot succeed, it returns traits_type::eof(). Otherwise, it returns traits_type::not_eof(c).

basic_filebuf::seekoff

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

The protected virtual member function endeavors to alter the current positions for the controlled streams. For an object of class basic_filebuf<E, T>, a stream position can be represented by an object of type fpos_t, which stores an offset and any state information needed to parse a wide stream. Offset zero designates the first element of the stream. (An object of type pos_type stores at least an fpos_t object.)

For a file opened for both reading and writing, both the input and output streams are positioned in tandem. To switch between inserting and extracting, you must call either pubseekoff or pubseekpos. Calls to pubseekoff (and hence to seekoff) have various limitations for text streams, binary streams, and wide streams.

If the file pointer fp is a null pointer, the function fails. Otherwise, it endeavors to alter the stream position by calling fseek(fp, off, way). If that function succeeds and the resultant position fposn can be determined by calling fgetpos(fp, &fposn), the function succeeds. If the function succeeds, it returns a value of type pos_type containing fposn. Otherwise, it returns an invalid stream position.

basic_filebuf::seekpos

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

The protected virtual member function endeavors to alter the current positions for the controlled streams. For an object of class basic_filebuf<E, T>, a stream position can be represented by an object of type fpos_t, which stores an offset and any state information needed to parse a wide stream. Offset zero designates the first element of the stream. (An object of type pos_type stores at least an fpos_t object.)

For a file opened for both reading and writing, both the input and output streams are positioned in tandem. To switch between inserting and extracting, you must call either pubseekoff or pubseekpos. Calls to pubseekoff (and hence to seekoff) have various limitations for text streams, binary streams, and wide streams.

For a wide stream, if any insertions have occured since the stream was opened, or since the last call to streampos, the function calls overflow(). It also inserts any sequence needed to restore the initial conversion state, by using the file conversion facet fac to call fac.unshift as needed. Each element x of type char thus produced is written to the associated stream designated by the file pointer fp as if by successive calls of the form fputc(x, fp). If the call to fac.unshift or any write fails, the function does not succeed.

If the file pointer fp is a null pointer, the function fails. Otherwise, it endeavors to alter the stream position by calling fsetpos(fp, &fposn), where fposn is the fpos_t object stored in pos. If that function succeeds, the function returns pos. Otherwise, it returns an invalid stream position.

basic_filebuf::setbuf

virtual basic_streambuf<E, T>
    *setbuf(E *s, streamsize n);

The protected member function returns zero if the file pointer fp is a null pointer. Otherwise, it calls setvbuf(fp, (char *)s, _IOFBF, n * sizeof (E)) to offer the array of n elements beginning at s as a buffer for the stream. If that function returns a nonzero value, the function returns a null pointer. Otherwise, it returns this to signal success.

basic_filebuf::underflow

virtual int_type underflow();

The protected virtual member function endeavors to extract the current element c from the input stream, and return the element as traits_type::to_int_type(c). It can do so in various ways:

If the function cannot succeed, it returns traits_type::eof(). Otherwise, it returns c, converted as described above.

basic_fstream

Description
Synopsis
Constructor
basic_fstream::basic_fstream
Member functions
basic_fstream::close
basic_fstream::is_open
basic_fstream::open
basic_fstream::rdbuf
Description

The template class describes an object that controls insertion and extraction of elements and encoded objects using a stream buffer of class basic_filebuf<E, T>, with elements of type E, whose character traits are determined by the class T. The object stores an object of class basic_filebuf<E, T>.

Synopsis
template <class E, class T = char_traits<E> >
    class basic_fstream : public basic_iostream<E, T> {
public:
    basic_fstream();
    explicit basic_fstream(const char *s,
        ios_base::openmode mode =
            ios_base::in | ios_base::out);
    basic_filebuf<E, T> *rdbuf() const;
    bool is_open() const;
    void open(const char *s,
        ios_base::openmode mode =
            ios_base::in | ios_base::out);
    void close();
    };
Constructor
basic_fstream::basic_fstream

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

The first constructor initializes the base class by calling basic_iostream(sb), where sb is the stored object of class basic_filebuf<E, T>. It also initializes sb by calling basic_filebuf<E, T>().

The second constructor initializes the base class by calling basic_iostream(sb). It also initializes sb by calling basic_filebuf<E, T>(), then sb.open(s, mode). If the latter function returns a null pointer, the constructor calls setstate(failbit).

Member functions
basic_fstream::close

 voidclose();

The member function calls rdbuf()-> close().

basic_fstream::is_open

bool is_open();

The member function returns rdbuf()-> is_open().

basic_fstream::open

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

The member function calls rdbuf()-> open(s, mode). If that function returns a null pointer, the function calls setstate(failbit).

basic_fstream::rdbuf

basic_filebuf<E, T> *rdbuf() const

The member function returns the address of the stored stream buffer, of type pointer to basic_filebuf<E, T>.

basic_ifstream

Description
Synopsis
Constructor
basic_ifstream::basic_ifstream
Member functions
basic_ifstream::close
basic_ifstream::is_open
basic_ifstream::open
basic_ifstream::rdbuf
Description

The template class describes an object that controls extraction of elements and encoded objects from a stream buffer of class basic_filebuf<E, T>, with elements of type E, whose character traits are determined by the class T. The object stores an object of class basic_filebuf<E, T>.

Synopsis
template <class E, class T = char_traits<E> >
    class basic_ifstream : public basic_istream<E, T> {
public:
    basic_filebuf<E, T> *rdbuf() const;
    basic_ifstream();
    explicit basic_ifstream(const char *s,
        ios_base::openmode mode = ios_base::in);
    bool is_open() const;
    void open(const char *s,
        ios_base::openmode mode = ios_base::in);
    void close();
    };
Constructor
basic_ifstream::basic_ifstream

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

The first constructor initializes the base class by calling basic_istream(sb), where sb is the stored object of class basic_filebuf<E, T>. It also initializes sb by calling basic_filebuf<E, T>().

The second constructor initializes the base class by calling basic_istream(sb). It also initializes sb by calling basic_filebuf<E, T>(), then sb.open(s, mode | ios_base::in). If the latter function returns a null pointer, the constructor calls setstate(failbit).

Member functions
basic_ifstream::close

void close();

The member function calls rdbuf()-> close().

basic_ifstream::is_open

bool is_open();

The member function returns rdbuf()-> is_open().

basic_ifstream::open

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

The member function calls rdbuf()-> open(s, mode | ios_base::in). If that function returns a null pointer, the function calls setstate(failbit).

basic_ifstream::rdbuf

basic_filebuf<E, T> *rdbuf() const

The member function returns the address of the stored stream buffer.

basic_ofstream

Description
Synopsis
Constructor
basic_ofstream::basic_ofstream
Member functions
basic_ofstream::close
basic_ofstream::is_open
basic_ofstream::open
basic_ofstream::rdbuf
Description

The template class describes an object that controls insertion of elements and encoded objects into a stream buffer of class basic_filebuf<E, T>, with elements of type E, whose character traits are determined by the class T. The object stores an object of class basic_filebuf<E, T>.

Synopsis
template <class E, class T = char_traits<E> >
    class basic_ofstream : public basic_ostream<E, T> {
public:
    basic_filebuf<E, T> *rdbuf() const;
    basic_ofstream();
    explicit basic_ofstream(const char *s,
        ios_base::openmode mode = ios_base::out);
    bool is_open() const;
    void open(const char *s,
        ios_base::openmode mode = ios_base::out);
    void close();
    };
Constructor
basic_ofstream::basic_ofstream

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

The first constructor initializes the base class by calling basic_ostream(sb), where sb is the stored object of class basic_filebuf<E, T>. It also initializes sb by calling basic_filebuf<E, T>().

The second constructor initializes the base class by calling basic_ostream(sb). It also initializes sb by calling basic_filebuf<E, T>(), then sb.open(s, mode | ios_base::out). If the latter function returns a null pointer, the constructor calls setstate(failbit).

Member functions
basic_ofstream::close

void close();

The member function calls rdbuf()-> close().

basic_ofstream::is_open

bool is_open();

The member function returns rdbuf()-> is_open().

basic_ofstream::open

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

The member function calls rdbuf()-> open(s, mode | ios_base::out). If that function returns a null pointer, the function calls setstate(failbit).

basic_ofstream::rdbuf

basic_filebuf<E, T> *rdbuf() const

The member function returns the address of the stored stream buffer.

Types

filebuf
fstream
ifstream
ofstream
wfstream
wifstream
wofstream
wfilebuf

filebuf

typedef basic_filebuf<char, char_traits<char> > filebuf;

The type is a synonym for template class basic_filebuf, specialized for elements of type char with default character traits.

fstream

typedef basic_fstream<char, char_traits<char> > fstream;

The type is a synonym for template class basic_fstream, specialized for elements of type char with default character traits.

ifstream

typedef basic_ifstream<char, char_traits<char> > ifstream;

The type is a synonym for template class basic_ifstream, specialized for elements of type char with default character traits.

ofstream

typedef basic_ofstream<char, char_traits<char> >
    ofstream;

The type is a synonym for template class basic_ofstream, specialized for elements of type char with default character traits.

wfstream

typedef basic_fstream<wchar_t, char_traits<wchar_t> >
    wfstream;

The type is a synonym for template class basic_fstream, specialized for elements of type wchar_t with default character traits.

wifstream

typedef basic_ifstream<wchar_t, char_traits<wchar_t> >
    wifstream;

The type is a synonym for template class basic_ifstream, specialized for elements of type wchar_t with default character traits.

wofstream

typedef basic_ofstream<wchar_t, char_traits<wchar_t> >
    wofstream;

The type is a synonym for template class basic_ofstream, specialized for elements of type wchar_t with default character traits.

wfilebuf

typedef basic_filebuf<wchar_t, char_traits<wchar_t> >
    wfilebuf;

The type is a synonym for template class basic_filebuf, specialized for elements of type wchar_t with default character traits.

Copyright note

Certain materials included or referred to in this document are copyright P.J. Plauger and/or Dinkumware, Ltd. or are based on materials that are copyright P.J. Plauger and/or Dinkumware, Ltd.

Notwithstanding the meta-data for this document, copyright information for this document is as follows:

Copyright © IBM Corp. 1999, 2010. & Copyright © P.J. Plauger and/or Dinkumware, Ltd. 1992-2006.