13.24 <fstream>

The <fstream> header declares classes and other types for performing I/O with external files. A file in C++ is a sequence of bytes. A narrow (byte) stream or buffer simply reads or writes those bytes. A wide stream or buffer reads multibyte characters and converts them to wide characters (according to the stream's locale) or converts wide characters to their multibyte equivalents for writing.

See Chapter 9 for a general discussion of I/O and related topics (stream buffers, locales, and facets), Chapter 1 for more information about character sets, and the <iostream> section in this chapter for information about the base-class templates required by the fstream class templates. Refer to Chapter 8 for information about traits in general and to the <string> section in this chapter for detailed information about the char_traits class template. Refer to the <streambuf> section in this chapter for information about the basic_streambuf class template.

To open a file for reading, use ifstream; for writing, use ofstream; for reading and writing, use fstream; for wide character I/O, use wifstream, wofstream, or wfstream.

basic_filebuf class template

Class template for file buffers

template <class charT, class traits = char_traits<charT> >
class basic_filebuf : public basic_streambuf<charT,traits>
{
public:
  typedef charT char_type;
  typedef typename traits::int_type int_type;
  typedef typename traits::pos_type pos_type;
  typedef typename traits::off_type off_type;
  typedef traits traits_type;
   
  basic_filebuf(  );
  virtual ~basic_filebuf(  );
   
  bool is_open(  ) const;
  basic_filebuf<charT,traits>* 
    open(const char* filename, ios_base::openmode mode);
  basic_filebuf<charT,traits>* 
    open(const char* filename, ios_base::open_mode mode);
  basic_filebuf<charT,traits>* close(  );
protected:
  virtual streamsize showmanyc(  );
  virtual int_type underflow(  );
  virtual int_type uflow(  );
  virtual int_type pbackfail(int_type c = traits::eof(  ));
  virtual int_type overflow(int_type c = traits::eof(  ));
  virtual basic_streambuf<charT,traits>*
    setbuf(char_type* s, streamsize n);
  virtual pos_type seekoff(off_type off, ios_base::seekdir way,
    ios_base::openmode = ios_base::in | ios_base::out);
  virtual pos_type seekpos(pos_type newpos, 
    ios_base::openmode which = ios_base::in | ios_base::out);
  virtual int sync(  );
  virtual void imbue(const locale& loc);
};

The basic_filebuf class template implements a stream buffer that is associated with an external file. The connection to the external file is equivalent to calling C I/O functions (declared in <cstdio>) but may or may not actually call the C functions. For example, the open function is equivalent to calling fopen and having the filebuf object store the returned FILE pointer.

The external file is treated as a series of bytes, which might form multibyte characters. When converting the multibyte character sequences to characters in the file buffer, which are of type charT, the file buffer uses a code conversion facet from the buffer's locale. This codecvt facet is equivalent to a_codecvt, which is declared and initialized as follows:

std::codecvt<charT, char, typename traits::state_type>
  a_codecvt = use_facet<codecvt<charT, char,
              typename traits::state_type> >(getloc(  ));

Some of the function descriptions in this section refer to a_codecvt and describe functionality, assuming that an actual codecvt facet object exists. An implementation does not have to create a codecvt facet object as long as the file stream acts as though it did create and use an explicit codecvt facet. (See <locale> for more information about codecvt.)

Remember that codecvt<char, char, mbstate_t> is essentially a no-op, mapping a character to itself, so the codecvt facet is most important when charT is wchar_t.

See <streambuf> for a description of the required behavior of a stream buffer, especially for the virtual functions that basic_filebuf overrides.

The following are the member functions of basic_filebuf:

basic_filebuf( )

Initializes the file buffer in a closed state.

virtual ~basic_filebuf( )

Calls close( ) and finalizes the file buffer.

basic_filebuf<charT, traits>* close( )

Closes the file, severing the connection between the external file and the file buffer. If the file is already closed, it returns a null pointer. Otherwise, it calls overflow(EOF) to flush the output buffer. If the buffer recently called overflow, the external character stream might have an incomplete shift sequence of a multibyte character. The close function therefore calls a_codecvt.unshift( ) as often as needed to complete the shift sequence, and then calls overflow(EOF) again to flush the buffer. Finally, the external file is closed by calling fclose or its equivalent.

The return value is this for success or a null pointer for failure.

virtual void imbue(const locale& loc)

Changes the file buffer's locale, in particular the codecvt facet. It is safe to change the locale when the file is positioned at its beginning, when the character encoding (a_codecvt.encoding( )) is not state-dependent, or the old and new locales have the same codecvt facet.

bool is_open( ) const

Returns true if the file is open or false if the file is closed.

basic_filebuf<charT, traits>*

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

basic_filebuf<charT, traits>*

open(const char* filename, ios_base::open_mode mode)

Opens the file filename. If the file is already open (is_open( ) returns true), a null pointer is returned immediately; otherwise, the file buffer is initialized and the named file is opened by calling the equivalent of fopen(filename, modestr). The modestr is determined from the mode (without the ios_base::ate bit), as shown in Table 13-9. No other mode combinations are allowed. If the mode includes ios_base::ate, the opened file is positioned at its end by calling the equivalent of fseek(file, 0, SEEK_END).

The second form is deprecated. It has the same functionality as the first form. See ios_base::openmode in <ios> for details.

If the file is opened successfully, this is returned; otherwise, the return value is a null pointer.

virtual int_type overflow(int_type c = traits::eof( ))

Converts its output using a_codecvt.out and writes the converted characters to the external file. The return value is traits::eof( ) for failure, which also occurs if the file is not open. For success, the return value is traits::not_eof(c).

virtual int_type pbackfail(int_type c = traits::eof( ))

Tries to push back the character c so it will be the next character read from the input buffer. If a push-back position is not available (see <streambuf> for a definition of "push-back position"), the file buffer attempts to make one available (e.g., by moving the file position).

If c is traits::eof( ) or the same character as gptr( )[-1], the file buffer decrements the gptr( ) pointer; otherwise, if the input array is assignable, c is assigned to gptr( )[-1] and gptr( ) is decremented.

The return value is traits::eof( ) for failure or traits::not_eof(c) for success.

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

Tries to seek to a new position in the file as an offset from a defined position. If the file is not open, the attempt to seek fails. If the character set encoding uses shift states or otherwise does not have a fixed size per character, off must be 0. Otherwise, if the destination is not the current position (off != 0 or way != basic_ios::cur), the output buffer is flushed and unshift sequences are written as needed (a_codecvt.unshift). The new file position is set by calling the equivalent of fseek(file, width * off, origin), in which width is a_codecvt.encoding( ) and origin is determined as shown in Table 13-10. If width < 0, off must be 0, so the call is fseek(file, 0, origin). The return value is the new file position or -1 for an error or if the new position is unknown. Note that seekoff does not use its final parameter.

Table 13-10. Seek origins

ios_base::seekdir options

fseek equivalents

basic_ios::beg

SEEK_SET

basic_ios::cur

SEEK_CUR

basic_ios::end

SEEK_END

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

Attempts to set the file position to newpos, which must be the result of calling seekoff or seekpos on the same file. If which includes the ios_base::in bit, the input sequence is updated; if which includes the ios_base::out bit, the output sequence is updated, and any necessary unshift characters are written prior to setting the file position. If neither bit is set in which, an error results. The return value is -1 for an error or newpos for success.

virtual basic_streambuf<charT, traits>* setbuf(char_type* s, streamsize n)

Sets the buffer. If you call setbuf(0, 0) before any I/O operations are performed on a file, the file is set to unbuffered. The behavior is implementation-defined for any other argument values. The return value is this.

virtual streamsize showmanyc( )

Returns an estimate of the number of characters immediately available for input.In other words, it does the same thing as the base class showmanyc function.

virtual int sync( )

Flushes output to the external file. The behavior for input is implementation-defined.

virtual int_type uflow( )

Fills the input buffer in the same manner as underflow.

virtual int_type underflow( )

Fills the input buffer. Multibyte characters are read from the external file and converted to charT characters by calling the equivalent of a_codecvt.in.

Example

Example 13-9. Copying a file using ifstream and ofstream

#include <cstdlib>
#include <fstream>
#include <cstdio>    // For perror(  )
#include <iostream>  // For cerr
   
int main(int argc, char** argv)
{
  if (argc != 3) {
    std::cerr << "usage: copy FROM TO\n";
    return EXIT_FAILURE;
  }
   
  // Open the input file.
  std::ifstream in(argv[1]);
  if (! in) {
    std::perror(argv[1]);
    return EXIT_FAILURE;
  }
   
  // Open the output file.
  std::ofstream out(argv[2]);
  if (! out) {
    std::perror(argv[2]);
    return EXIT_FAILURE;
  }
   
  // Copy the input to the output, one character at a time.
  char c;
  while (in.get(c))
    out.put(c);
  out.close(  );
  // Make sure the output was written.
  if (! out) {
    std::perror(argv[2]);
    return EXIT_FAILURE;
  }
}

13.24 <fstream>

Table 13-9. File open modes

Table 13-10. Seek origins

See Also

See Also

See Also

See Also

See Also

See Also

Example

Example 13-9. Copying a file using ifstream and ofstream

See Also

See Also

See Also

See Also

See Also

See Also