FSTREAM(3CC4)FSTREAM(3CC4)NAMEfstream - 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 out‐
put for an ofstream. The default protection is filebuf::open‐
prot, 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 con‐
nected 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 col‐
lection 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. Construc‐
tion 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 trun‐
cated 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.
SEE ALSOios.intro(3CC4), filebuf(3CC4), ios(3CC4), istream(3CC4),
ostream(3CC4), sbufpub(3CC4),
C++ Library Reference
Chapter 3, "The Classic iostream Library",
Chapter 4, "Using Classic iostream in a Multithreaded Environ‐
ment."
18 June 1998 FSTREAM(3CC4)
