fstream(3C++std)

basic_filebuf , basic_fstream , basic_ifstream , basic_ofstream , filebuf , fstream , ifstream , ofstream , wfilebuf , wfstream , wifstream , wofstream - defines several iostreams template classes that manipulate exteral 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;
       };

Description

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

basic_filebuf

basic_filebuf , close , is_open , open , overflow , pbackfail , seekoff , seekpos , setbuf , sync , underflow

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

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.

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 E char_type;

The type is a synonym for the template parameter E.

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::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 *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):

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 | 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<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::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 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 c, by using the file conversion facet fac to call fac.out 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 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(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 a putback position is available, and the element stored there compares equal to x, 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 x 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(c).

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

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::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 T traits_type;

The type is a synonym for the template parameter T.

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 a read position is available, it takes c 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 c of type E 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 c, converted as described above.

basic_fstream

basic_fstream , basic_fstream , close , is_open , open , rdbuf

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

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

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

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

basic_ifstream , basic_ifstream , close , is_open , open , rdbuf

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

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

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

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

basic_ofstream , basic_ofstream , close , is_open , open , rdbuf

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

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

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

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.

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.

References

ios(3C++std) , istream(3C++std) , locale(3C++std) , ostream(3C++std) , stdio(5) , streambuf(3C++std) , string(3C++std)