This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

<fstream>

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

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

basic_filebuf

template <class Elem, class Tr = char_traits<Elem> >
    class basic_filebuf : public basic_streambuf<Elem, Tr> {
public:
    typedef typename basic_streambuf<Elem, Tr>::char_type
        char_type;
    typedef typename basic_streambuf<Elem, Tr>::traits_type
        traits_type;
    typedef typename basic_streambuf<Elem, Tr>::int_type
        int_type;
    typedef typename basic_streambuf<Elem, Tr>::pos_type
        pos_type;
    typedef typename basic_streambuf<Elem, Tr>::off_type
        off_type;
    basic_filebuf();
    bool is_open() const;
    basic_filebuf *open(const char *filename,
        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 meta =
        traits_type::eof());
    virtual int_type overflow(int_type meta =
        traits_type::eof());
    virtual int sync();
    virtual basic_streambuf<Elem, Tr>
        *setbuf(Elem *buffer, streamsize count);
    };

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

An object of class basic_filebuf<Elem, Tr> 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.

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.

basic_filebuf::char_type

typedef Elem char_type;

The type is a synonym for the template parameter Elem.

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 byte 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(byte, fp). If the call to fac.unshift or any write fails, the function does not succeed.

basic_filebuf::int_type

typedef typename traits_type::int_type int_type;

The type is a synonym for traits_type::int_type.

basic_filebuf::is_open

bool is_open();

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

basic_filebuf::off_type

typedef typename traits_type::off_type off_type;

The type is a synonym for traits_type::off_type.

basic_filebuf::open

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

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

• ios_base::in becomes "r" (open existing file for reading).
• ios_base::out or ios_base::out | ios_base::trunc becomes "w" (truncate existing file or create for writing).
• ios_base::out | ios_base::app becomes "a" (open existing file for appending all writes).
• ios_base::in | ios_base::out becomes "r+" (open existing file for reading and writing).
• ios_base::in | ios_base::out | ios_base::trunc becomes "w+" (truncate existing file or create for reading and writing).
• ios_base::in | ios_base::out | ios_base::app becomes "a+" (open existing file for reading and for appending all writes).

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<Elem, 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::overflow

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

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

• If a write position is available, it can store the element into the write position and increment the next pointer for the output buffer.
• It can make a write position available by allocating new or additional storage for the output buffer.
• It can convert any pending output in the output buffer, followed by ch, by using the file conversion facet fac to call fac.out as needed. Each element ch 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(ch, fp). If any conversion or write fails, the function does not succeed.

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

basic_filebuf::pbackfail

virtual int_type pbackfail(int_type meta =
    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 meta == 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 ch = traits_type::to_char_type(meta). The function can put back an element in various ways:

• If a putback position is available, and the element stored there compares equal to ch, it can simply decrement the next pointer for the input buffer.
• If the function can make a putback position available, it can do so, set the next pointer to point at that position, and store ch in that position.
• If the function can push back an element onto the input stream, it can do so, such as by calling ungetc for an element of type char.

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

basic_filebuf::pos_type

typedef typename traits_type::pos_type pos_type;

The type is a synonym for traits_type::pos_type.

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<Elem, Tr>, 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<Elem, Tr>, 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 byte 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(byte, 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<Elem, Tr>
    *setbuf(Elem *buffer, streamsize count);

The protected member function returns zero if the file pointer fp is a null pointer. Otherwise, it calls setvbuf(fp, (char *)buffer, _IOFBF, count * sizeof (Elem)) to offer the array of count elements beginning at buffer 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::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.

basic_filebuf::traits_type

typedef Tr traits_type;

The type is a synonym for the template parameter Tr.

basic_filebuf::underflow

virtual int_type underflow();

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

• If a read position is available, it takes ch as the element stored in the read position and advances the next pointer for the input buffer.
• It can read one or more elements of type char, as if by successive calls of the form fgetc(fp), and convert them to an element ch of type Elem by using the file conversion facet fac to call fac.in as needed. If any read or conversion fails, the function does not succeed.

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

basic_fstream

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

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

basic_fstream::basic_fstream

basic_fstream();
explicit basic_fstream(const char *filename,
    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<Elem, Tr>. It also initializes sb by calling basic_filebuf<Elem, Tr>().

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

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 *filename,
    ios_base::openmode mode =
        ios_base::in | ios_base::out);

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

basic_fstream::rdbuf

basic_filebuf<Elem, Tr> *rdbuf() const

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

basic_ifstream

template <class Elem, class Tr = char_traits<Elem> >
    class basic_ifstream : public basic_istream<Elem, Tr> {
public:
    basic_filebuf<Elem, Tr> *rdbuf() const;
    basic_ifstream();
    explicit basic_ifstream(const char *filename,
        ios_base::openmode mode = ios_base::in);
    bool is_open() const;
    void open(const char *filename,
        ios_base::openmode mode = ios_base::in);
    void close();
    };

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

basic_ifstream::basic_ifstream

basic_ifstream();
explicit basic_ifstream(const char *filename,
    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<Elem, Tr>. It also initializes sb by calling basic_filebuf<Elem, Tr>().

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

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 *filename,
    ios_base::openmode mode = ios_base::in);

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

basic_ifstream::rdbuf

basic_filebuf<Elem, Tr> *rdbuf() const

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

basic_ofstream

template <class Elem, class Tr = char_traits<Elem> >
    class basic_ofstream : public basic_ostream<Elem, Tr> {
public:
    basic_filebuf<Elem, Tr> *rdbuf() const;
    basic_ofstream();
    explicit basic_ofstream(const char *filename,
        ios_base::openmode mode = ios_base::out);
    bool is_open() const;
    void open(const char *filename,
        ios_base::openmode mode = ios_base::out);
    void close();
    };

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

basic_ofstream::basic_ofstream

basic_ofstream();
explicit basic_ofstream(const char *filename,
    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<Elem, Tr>. It also initializes sb by calling basic_filebuf<Elem, Tr>().

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

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 *filename,
    ios_base::openmode mode = ios_base::out);

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

basic_ofstream::rdbuf

basic_filebuf<Elem, Tr> *rdbuf() const

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

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.

See also the Table of Contents and the Index.

Copyright © 1992-2002 by P.J. Plauger. All rights reserved.