Apache C++ Standard Library Reference Guide

## basic_fstream

Library: Input/output

                             basic_ostream
    basic_fstreambasic_iostream                      basic_iosios_base
                             basic_istream

- Local Index
- Summary
- Synopsis
- Description
- Interface
- Member Types
- Nonmember Types
- Constructors
- Destructors
- Member Functions
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

basic_fstream() char_type close() | fd() int_type is_open() | off_type open() pos_type | rdbuf() traits_type ~basic_fstream()

#### Non-Members

fstream | wfstream |

### Summary

Class that supports reading and writing of named files or devices associated with a file descriptor

### Synopsis

    #include <fstream>

    namespace std {
      template<class charT, class traits = char_traits<charT> >
      class basic_fstream;
    }

### Description

The class template basic_fstream supports reading and writing to named files or other devices associated with a file descriptor. It uses a basic_filebuf object to control the associated sequences. It inherits from basic_iostream and can therefore use all the formatted and unformatted input and output functions.

### Interface

    namespace std {

      template<class charT, class traits = char_traits<charT> >
      class basic_fstream
      : public basic_iostream<charT, traits> {

       public:

        typedef charT  char_type;
        typedef traits traits_type;
        typedef typename traits_type::int_type  int_type;
        typedef typename traits_type::pos_type  pos_type;
        typedef typename traits_type::off_type  off_type;

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

        // extensions:
        explicit basic_fstream(const char*,
                               ios_base::openmode,
                               long);
        explicit basic_fstream(int, char_type* = 0,
                               streamsize = /* default size */);
        explicit basic_fstream(FILE*, char_type* = 0,
                               streamsize = /* default size */);

        virtual ~basic_fstream();

        basic_filebuf<char_type, traits_type> *rdbuf() const;
        bool is_open() const;

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

        // extensions:
        int fd() const;
        void open(const char*, ios_base::openmode, long);
        void open(int, char_type* = 0,
                  streamsize = /* default size */);
        void open(FILE*, char_type* = 0,
                  streamsize = /* default size */);
        void close();

      };
    }

### Member Types

    char_type

The type `char_type` is a synonym for the template parameter `charT`.

    int_type

The type `int_type` is a synonym of type `traits_type::in_type`.

    off_type

The type `off_type` is a synonym of type `traits_type::off_type`.

    pos_type

The type `pos_type` is a synonym of type `traits_type::pos_type`.

    traits_type

The type `traits_type` is a synonym for the template parameter `traits`.

### Nonmember Types

    fstream

The type `fstream` is an instantiation of class basic_fstream on type `char`:

`typedef basic_fstream<char> fstream;`

    wfstream

The type `wfstream` is an instantiation of class basic_fstream on type `wchar_t:`

`typedef basic_fstream<wchar_t> wfstream;`

### Constructors

    basic_fstream();

Constructs an object of class basic_fstream, initializing the base class basic_iostream with the associated file buffer. This buffer is initialized by calling the basic_filebuf constructor:

`basic_filebuf<char_type, traits_type>(rdbuf())`

After construction, a file can be attached to the basic_fstream object by using the `open()` member function.

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

Constructs an object of class basic_fstream, initializing the base class basic_iostream with the associated file buffer. This buffer is initialized by calling the constructor:

`basic_filebuf<char_type, traits_type>(rdbuf())`

The constructor then calls `open(s, mode)` in order to attach the file, whose name is pointed to by `s`, to the basic_fstream object.

    basic_fstream(const char* s, ios_base::openmode mode,
                  long protection);

Constructs an object of class basic_fstream, initializing the base class basic_iostream with the associated file buffer. This buffer is initialized by calling the basic_filebuf constructor:

`basic_filebuf<char_type, traits_type>(rdbuf())`

The constructor then calls:

`rdbuf()->open(s, mode, protection)`

in order to attach the file, whose name is pointed to by `s`, to the basic_fstream object.

The third argument, `protection`, holds file permissions. It determines the file read/write/execute permissions under UNIX, but is more limited elsewhere.

> NOTE -- The protection argument is not part of the C++ Standard, but is included here as a convenience extension. See Appendix B for a complete list of extensions of this implementation.

    basic_fstream(int fd, char_type *buf, streamsize n);

Constructs an object of class basic_fstream, initializing the base class basic_iostream with the associated file buffer. This buffer is initialized by calling the basic_filebuf constructor:

`basic_filebuf<char_type, traits_type>(rdbuf ())`

The constructor then calls:

`rdbuf()->open (fd, buf, n)`

in order to attach the file descriptor `fd` to the basic_fstream object. If the function fails, it sets `ios_base::failbit`.

> NOTE -- This function is not part of the C++ Standard, but is included here as an extension in order to manipulate pipes, sockets, or other UNIX devices that can be accessed through file descriptors. See Appendix B for a complete list of extensions of this implementation.

    basic_fstream(FILE *fp, char_type* buf, streamsize n);

Constructs an object of class basic_fstream, initializing the base class basic_iostream with the associated file buffer. This buffer is initialized by calling the basic_filebuf constructor:

`basic_filebuf<char_type, traits_type>(rdbuf ())`

The constructor then calls:

`rdbuf()->open (fp, buf, n)`

in order to attach the file pointer `fp` to the basic_fstream object. If the function fails, it sets `ios_base::failbit`.

> NOTE -- This function is not part of the C++ Standard, but is provided here as a convenience extension. See Appendix B for a complete list of extensions of this implementation.

### Destructors

    virtual ~basic_fstream();

Destroys an object of class basic_fstream.

### Member Functions

    void
    close();

Calls `rdbuf()->close()`. If this function fails, it calls `setstate(failbit)`.

    int
    fd() const;

Returns the file descriptor associated with the stream.

> NOTE -- This function is not part of the C++ Standard, but is provided here as a convenience extension. See Appendix B for a complete list of extensions of this implementation.

    bool
    is_open() const;

Returns `rdbuf()->is_open()`.

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

Calls `rdbuf()->open(s, mode)`. If this function fails to open the file, it calls the basic_ios member function `setstate(failbit)`.

    void
    open(const char* s,
         ios_base::openmode, long protection);

Calls `rdbuf()->open (s, mode, protection)`. If this function fails to open the file, it calls `setstate(failbit)`.

The third argument, `protection`, holds file permissions. It determines the file read/write/execute permissions under UNIX. It is more limited under DOS, since files are always readable and do not have special execute permission.

> NOTE -- The protection argument does not appear in the C++ Standard C++, but is included here as a convenience extension. See Appendix B for a complete list of extensions of this implementation.

    void
    open(int fd, char_type *buf = 0,
          streamsize n = /* default size */);

Calls `rdbuf()->open (fd, buf, n)`. If this function fails to open the file, it calls `setstate(failbit)`.

> NOTE -- This function is not part of the C++ Standard, but is provided here as a convenience extension. See Appendix B for a complete list of extensions of this implementation.

    void
    open(FILE *fp, char_type *buf = 0,
         streamsize n = /* default size */);

Returns `open(fileno (fp), buf, n)`. If this function fails to open the file, it calls `setstate(failbit)`.

`fileno` is a UNIX98 function declared in `<cstdio>`.

> NOTE -- This function is not part of the C++ Standard, but is provided here as a convenience extension. See Appendix B for a complete list of extensions of this implementation.

    basic_filebuf<charT_type,traits_type>*
    rdbuf() const;

Returns a pointer to the basic_filebuf associated with the stream.

### Example

    //
    //  fstream.cpp
    //

    #include <fstream>    // for fstream
    #include <iostream>   // for cout, endl
    #include <string>     // for string

    int main ( )
    {
        // create a bi-directional fstream object
        std::fstream inout ("test_fstream.out",
                            std::ios::in | std::ios::out |
                            std::ios::trunc);

        // write out three lines to the file
        inout << "Dieses ist die Geschichte eines Mannes.\n"
              << "C'est l'histoire d'un homme.\n"
              << "This is the story of a man." << std::endl;

        std::string line;

        // seek back to the beginning of the file
        inout.seekg (0);

        // extract the first line
        std::getline (inout, line);

        // output the first line to standard output
        std::cout << "\nDeutsch:\n" << line << std::endl;

        // obtain current position in file
        std::fstream::pos_type pos = inout.tellg ();

        // extract the second line
        std::getline (inout, line);

        // output the second line to standard output
        std::cout << "Français:\n" << line << std::endl;

        // extract the third line
        std::getline (inout, line);

        // output the third line to standard output
        std::cout << "English:\n" << line << std::endl;

        // move the put sequence before the second line
        inout.seekp (pos);

        // replace the second and third lines
        inout << "This is the story of a man.\n"
              << "C'est l'histoire d'un homme.";

        // seek to the beginning of the file
        inout.seekg (0);

        // output the all content of the fstream object to stdout
        std::cout << "\n" << inout.rdbuf () << std::endl;

        return 0;
    }

    Program Output:

    Deutsch:
    Dieses ist die Geschichte eines Mannes.
    Francais:
    C'est l'histoire d'un homme.
    English:
    This is the story of a man.

    Dieses ist die Geschichte eines Mannes.
    This is the story of a man.
    C'est l'histoire d'un homme.

### See Also

char_traits, ios_base, basic_ios, basic_filebuf, basic_ifstream, basic_ofstream

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems --Programming Language C++, Section 27.8.1.11