## basic_fstream

                                       basic_ostream
    basic_fstreambasic_iostream                    basic_iosios_base
                                       basic_istream

- Summary
- Data Type and Member Function Indexes
- Synopsis
- Description
- Interface
- Types
- Constructors
- Destructors
- Member Functions
- Example
- See Also
- Standards Conformance

### Summary

Supports reading and writing of named files or devices associated with a file descriptor.

### Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Data Types
char_type fstream int_type ios_type | off_type pos_type traits_type wfstream |

Member Functions
close() is_open() open() rdbuf()

### Synopsis

    #include <fstream>
    template<class charT, class traits = char_traits<charT> >
    class basic_fstream
    : public basic_iostream<charT, traits>

### Description

The template class basic_fstream<charT,traits> 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

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

     public:

      typedef basic_ios<charT, traits>   ios_type;

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

      basic_fstream();
      explicit basic_fstream(const char *s, ios_base::openmode
                             mode = ios_base::in |
                             ios_base::out,
                             long protection = 0666);

      explicit basic_fstream(int fd);
      basic_fstream(int fd, char_type *buf, int len);

      virtual ~basic_fstream();

      basic_filebuf<charT, traits> *rdbuf() const;
      bool is_open();
      void open(const char *s, ios_base::openmode mode =
                ios_base::in | ios_base::out,
                long protection = 0666);

      void close();

    };

### Types

    char_type

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

    fstream

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

`typedef basic_fstream<char> fstream;`

    int_type

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

    ios_type

The type `ios_type` is an instantiation of class `basic_ios` on type `charT`.

    off_type

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

    pos_type

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

    traits_type

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

    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<charT,traits>, initializing the base class basic_iostream with the associated file buffer, which is initialized by calling the `basic_filebuf` constructor `basic_filebuf<charT,traits>()`. 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,
                  long protection= 0666);

Constructs an object of class basic_fstream<charT,traits>, initializing the base class basic_iostream with the associated file buffer, which is initialized by calling the `basic_filebuf` constructor `basic_filebuf<charT,traits>()`. The constructor then calls the open function `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`, is used as the file permission. It does not appear in the Standard C++ description and is included as an extension. 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.

    explicit basic_fstream(int fd);

Constructs an object of class basic_fstream<charT,traits>, initializing the base class basic_iostream with the associated file buffer, which is initialized by calling the `basic_filebuf` constructor `basic_filebuf<charT,traits>()`. The constructor then calls the `basic_filebuf` open function `open(fd)` in order to attach the file descriptor `fd` to the basic_fstream object. This constructor is not described in the C++ standard, and is included as an extension in order to manipulate pipes, sockets, or other UNIX devices that can be accessed through file descriptors. If the function fails, it sets `ios_base::failbit.`

    basic_fstream(int fd, char_type* buf,int len);

Constructs an object of class basic_fstream<charT,traits>, initializing the base class basic_iostream with the associated file buffer, which is initialized by calling the `basic_filebuf` constructor `basic_filebuf<charT,traits>()`. The constructor then calls the `basic_filebuf` open function `open(fd)` in order to attach the file descriptor `fd` to the basic_fstream object. The underlying buffer is then replaced by calling the `basic_filebuf` member function, `setbuf()`, with parameters `buf` and `len`. This constructor is not described in the C++ standard, and is included as an extension in order to manipulate pipes, sockets, or other UNIX devices that can be accessed through file descriptors. It also maintains compatibility with the old iostreams library. If the function fails, it sets `ios_base::failbit.`

### Destructors

    virtual ~basic_fstream();

Destroys an object of class `basic_fstream`.

### Member Functions

    void
    close();

Calls the associated `basic_filebuf` function `close()` and if this function fails, it calls the `basic_ios` member function `setstate(failbit)`.

    bool
    is_open();

Calls the associated `basic_filebuf` function `is_open()` and return its result.

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

Calls the associated `basic_filebuf` function `open(s,mode,protection)` and, if this function fails at opening the file, calls the `basic_ios` member function `setstate(failbit)`. The third argument `protection` is used as the file permissions. It does not appear in the Standard C++ description and is included as an extension. 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.

    basic_filebuf<charT,traits>*
    rdbuf() const;

Returns a pointer to the `basic_filebuf` associated with the stream.

### Example

    //
    // stdlib/examples/manual/fstream.cpp
    //
    #include<iostream>
    #include<fstream>
    void main ( )
    {
        using namespace std;

        // create a bi-directional fstream object
        fstream inout("fstream.out");

        // output characters
        inout << "Das ist die rede von einem man" << endl;
        inout << "C'est l'histoire d'un home" << endl;
        inout << "This is the story of a man" << endl;

        char p[100];

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

        // extract the first line
        inout.getline(p,100);

        // output the first line to stdout
        cout << endl << "Deutch :" << endl;
        cout << p;

        fstream::pos_type pos = inout.tellg();

        // extract the second line
        inout.getline(p,100);

        // output the second line to stdout
        cout << endl << "Francais :" << endl;
        cout << p;

        // extract the third line
        inout.getline(p,100);

        // output the third line to stdout
        cout << endl << "English :" << endl;
        cout << p;

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

        // replace the second line
        inout << "This is the story of a man" << endl;

        // replace the third line
        inout << "C'est l'histoire d'un home";

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

        // output the all content of the fstream
        // object to stdout
        cout << endl << endl << inout.rdbuf();
    }

### See Also

char_traits(3C++),ios_base(3C++), basic_ios(3C++), basic_filebuf(3C++), basic_ifstream(3C++), basic_ofstream(3C++)

Working Paper for Draft Proposed International Standard for Information Systems--Programming Language C++, Section 27.8.1.11

### Standards Conformance

ANSI X3J16/ISO WG21 Joint C++ Committee

Copyright (c) 1998, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.
OEM Release, June 1998