fstream - Oracle Developer Studio 12.6 Man Pages

Language:

fstream(3CC4)

Name

fstream - stream class for file I/O

Synopsis

 
#include <fstream.h>
typedef long streampos;
typedef long streamoff;
class unsafe_ios {
public:
     // exported types
        // stream status bits
        enum io_state   {
            goodbit  = 0x00,        // no bit set: all is ok
            eofbit   = 0x01,        // at end of file
            failbit  = 0x02,        // last I/O operation failed
            badbit   = 0x04,        // invalid operation attempted
            hardfail = 0x80         // unrecoverable error
            };

        // stream operation mode
        enum open_mode  {
            in       = 0x01,        // open for reading
            out      = 0x02,        // open for writing
            ate      = 0x04,        // seek to eof upon original open
            app      = 0x08,        // append mode: all additions at eof
            trunc    = 0x10,        // truncate file if already exists
            nocreate = 0x20,        // open fails if file doesn't exist
            noreplace= 0x40         // open fails if file already exists
        };

        // stream seek direction
        enum seek_dir { beg=0, cur=1, end=2 };

     // see ios(3CC4) for remainder ...
};
class  filebuf : public streambuf {
     // see filebuf(3CC4) ...
};
class unsafe_fstreambase : virtual public unsafe_ios {
        unsafe_fstreambase();
        unsafe_fstreambase(const char*, int, int = filebuf::openprot);
        unsafe_fstreambase(int);
        unsafe_fstreambase(int _f, char*, int);
        ~unsafe_fstreambase();

        void open(const char*, int, int = filebuf::openprot);
        void attach(int);
        void close();
        void setbuf(char*, int);
        filebuf* rdbuf();
};
class fstreambase : virtual public ios, public unsafe_fstreambase {
public:
        fstreambase() ;

        fstreambase(const char*, int, int=filebuf::openprot) ;
        fstreambase(int) ;
        fstreambase(int, char*, int) ;

        void    open(const char*, int, int=filebuf::openprot) ;
        void     attach(int);
        void     close() ;
        void     setbuf(char*, int) ;
        filebuf* rdbuf();
};
class ifstream : public fstreambase, public istream {
public:
     // exported functions
     void open(const char* fname, int omode=ios::in,
        int prot=filebuf::openprot);
     filebuf* rdbuf();
public:
     // exported constructors
     ifstream();
     ifstream(const char* fname, int omode=ios::in,
        int prot=filebuf::openprot);
     ifstream(int fileno);
     ifstream(int fileno, char* buf, int size);
};
class ofstream : public fstreambase, public ostream {
public:
     // exported functions
     void open(const char* fname, int omode=ios::out,
        int prot=filebuf::openprot);
     filebuf* rdbuf();
public:
     // exported constructors
     ofstream();
     ofstream(const char* fname, int omode=ios::out,
        int prot=filebuf::openprot);
     ofstream(int fileno);
     ofstream(int fileno, char* buf, int size);
};
class fstream : public fstreambase, public iostream {
public:
     // exported functions
     void open(const char * fname, int omode,
        int prot=filebuf::openprot);
     filebuf* rdbuf();
public:
     // exported constructors
     fstream();
     fstream(const char* fname, int omode,
        int prot=filebuf::openprot);
     fstream(int fileno);
     fstream(int fileno, char* buf, int size);
};

Description

Classes ifstream, ofstream, and fstream are specialization of classes istream, ostream, and iostream, respectively, for I/O using files. That is, the associated streambuf is a filebuf.

An auxiliary class fstreambase is an implementation detail, primarily to provide a set of common functions. It is not further discussed.

We will discuss these classes together, using the notation Xstream to refer equally to any of ifstream, ofstream, or fstream.

Objects of type fstream, ifstream, ofstream are protected against simultaneous access by multiple threads by the useof mutex locks. Class unsafe_fstreambase is available to derive new file classes that do not require mt-safety. Class fstreambase, which is a base class for the three provided file classes, does use mutex locks to provide mt-safety.

As for other iostream classes, the mutex locking may be disabled by calling the member function set_safe_flag defined by class stream_MT.

Constructors

Xstream(): Constructs a closed Xstream not connected to any file.
Xstream(name, mode, prot): Constructs an Xstream and opens file name using mode for the open mode bits and prot for the file protection bits. (See open below.) The default open mode is input for an ifstream and output for an ofstream. The default protection is filebuf::openprot, which is 0666. Any errors will be stored in the Xstream error state; see ios(3CC4).
Xstream(f): Constructs an Xstream attached to file descriptor f, which must already be open. (It does not test for this condition.)
Xstream(f, ptr, len): Constructs an Xstream attached to file descriptor f, which must already be open. (It does not test for this condition.) The filebuf will use the len chars beginning at the location pointed to by ptr as the buffer (reserve area). If ptr is zero or len is not greater than zero, there will be no reserve area and fbuf will be unbuffered.

Member functions

fs.attach(f)

Connects fs to an open file descriptor f. If fs is already connected to a file, ignores the request, and sets ios::failbit in the fs error state.

fs.close()

Closes the associated filebuf and disconnects the file from fs. If the filebuf's close call succeeds, clears the error state; otherwise sets ios::failbit in the fs error state.

fs.open(name, mode, prot)

Opens file name and connects its file descriptor to fs; If the file does not exist, and ios::nocreate is not set in mode, open attempts to create the file with the protection bits specified in prot (with default value 0666). The mode parameter is a collection of bits from ios::open_mode which may be or'd together:

ios::app: Initially seeks to the end of the file. Any subsequent write always appends to the end of the file. This flag implies ios::out.
ios::ate: Initially seeks to the end of the file. This flag does not imply ios::out, but only begins operations at end of file.
ios::in: Open the file for input. If a file is opened for input and the file does not exist, it will not be created. Construction or opening of an ifstream always implies this bit, meaning the bit need not be set. When set for an fstream, means that input should be allowed if possible. When set for an ofstream, means that the file should not be truncated when it is opened.
ios::out: Open the file for output. Construction or opening of an ofstream always implies this bit, meaning the bit need not be set. When set for an fstream, means that output should be allowed if possible. May be set for an ifstream, but output to the file is not permitted.
ios::trunc: If the file exists, truncate to zero length upon opening it. When ios::out is specified or implied and neither ios::ate nor ios::app is specified, this bit is implied.
ios::nocreate: If the file does not already exist, do not create it; open will fail in this case.
ios::noreplace: The file should not already exist; open will fail if it does. This bit makes sense only when opening for output.

filebuf* fb = fs.rdbuf()

Returns a pointer to the filebuf associated with fs. This is the same as base class versions of this function, except that the return type is specifically a filebuf.

fs.setbuf(ptr, len)

This offers the buffer of len chars at ptr as the reserve area. It calls the filebuf version of setbuf, and uses its return value to adjust the error state of fs. That is, it clears the error state on success, and sets ios::failbit on error.