fstream

<fstream>

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

        // DECLARATIONS
class filebuf;
class ifstream;
class ofstream;
        // END OF DECLARATIONS

filebuf

class filebuf : public streambuf {
public:
    typedef typename streambuf<Elem, Tr>::char_type
        char_type;
    typedef typename streambuf<Elem, Tr>::traits_type
        traits_type;
    typedef typename streambuf<Elem, Tr>::int_type
        int_type;
    typedef typename streambuf<Elem, Tr>::pos_type
        pos_type;
    typedef typename streambuf<Elem, Tr>::off_type
        off_type;
    filebuf();
    bool is_open() const;
    filebuf *open(const char *filename,
        ios_base::openmode mode);
    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 streambuf
        *setbuf(Elem *buffer, streamsize count);
    };

The class describes a stream buffer that controls the transmission of elements to and from a sequence of elements stored in an external file.

An object of class filebuf stores a file pointer, which designates the FILE object that controls the stream associated with an open file.

filebuf::filebuf

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.

filebuf::char_type

typedef char char_type;

The type is a synonym for char.

filebuf::close

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.

filebuf::int_type

typedef traits_type::int_type int_type;

The type is a synonym for traits_type::int_type.

filebuf::is_open

bool is_open();

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

filebuf::off_type

typedef traits_type::off_type off_type;

The type is a synonym for traits_type::off_type.

filebuf::open

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 a null pointer, the function returns a null pointer. Otherwise, it returns this.

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 write any pending output in the output buffer, followed by ch, 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).

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).

filebuf::pos_type

typedef traits_type::pos_type pos_type;

The type is a synonym for traits_type::pos_type.

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 filebuf, a stream position can be represented by an object of type fpos_t. 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 and binary 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.

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 filebuf, a stream position can be represented by an object of type fpos_t. 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 both text streams and binary streams.

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.

filebuf::setbuf

virtual streambuf
    *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.

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.

filebuf::traits_type

typedef char_traits traits_type;

The type is a synonym for char_traits.

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). 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.

ifstream

class ifstream : public istream {
public:
    filebuf *rdbuf() const;
    ifstream();
    explicit 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 class describes an object that controls extraction of elements and encoded objects from a stream buffer of class filebuf. The object stores an object of class filebuf.

ifstream::ifstream

ifstream();
explicit ifstream(const char *filename,
    ios_base::openmode mode = ios_base::in);

The first constructor initializes the base class by calling istream(sb), where sb is the stored object of class filebuf. It also initializes sb by calling filebuf().

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

ifstream::close

void close();

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

ifstream::is_open

bool is_open();

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

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).

ifstream::rdbuf

filebuf *rdbuf() const

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

ofstream

class ofstream : public ostream {
public:
    filebuf *rdbuf() const;
    ofstream();
    explicit 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 class describes an object that controls insertion of elements and encoded objects into a stream buffer of class filebuf. The object stores an object of class filebuf.

ofstream::ofstream

ofstream();
explicit ofstream(const char *filename,
    ios_base::openmode which = ios_base::out);

The first constructor initializes the base class by calling ostream(sb), where sb is the stored object of class filebuf<Elem, Tr>. It also initializes sb by calling filebuf().

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

ofstream::close

void close();

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

ofstream::is_open

bool is_open();

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

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).

ofstream::rdbuf

filebuf *rdbuf() const

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

See also the Table of Contents and the Index.

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