fstream(3C++)
fstream --
iostream and streambuf specialized to files
Synopsis
#include <fstream.h>
typedef long streamoff, streampos;
class ios {
public:
enum seek_dir { beg, cur, end } ;
enum open_mode { in, out, ate, app, trunc, nocreate, noreplace } ;
enum io_state { goodbit=0, eofbit, failbit, badbit } ;
// and lots of other stuff, see ios(3C++) ...
} ;
class ifstream : istream {
ifstream() ;
~ifstream() ;
ifstream(const char* name, int =ios::in,
int prot =filebuf::openprot) ;
ifstream(int fd) ;
ifstream(int fd, char* p, int l) ;
void attach(int fd) ;
int detach() ;
void close() ;
void open(char* name, int =ios::in,
int prot=filebuf::openprot) ;
filebuf* rdbuf() ;
void setbuf(char* p, int l) ;
};
class ofstream : ostream {
ofstream() ;
~ofstream() ;
ofstream(const char* name, int =ios::out,
int prot =filebuf::openprot) ;
ofstream(int fd) ;
ofstream(int fd, char* p, int l) ;
void attach(int fd) ;
int detach() ;
void close() ;
void open(char* name, int =ios::out, int prot=filebuf::openprot) ;
filebuf* rdbuf() ;
void setbuf(char* p, int l) ;
};
class fstream : iostream {
fstream() ;
~fstream() ;
fstream(const char* name, int mode,
int prot =filebuf::openprot) ;
fstream(int fd) ;
fstream(int fd, char* p, int l) ;
void attach(int fd) ;
int detach();
void close() ;
void open(char* name, int mode, int prot=filebuf::openprot) ;
filebuf* rdbuf() ;
void setbuf(char* p, int l) ;
};
Description
ifstream, ofstream, and fstream
specialize istream, ostream, and iostream,
respectively, to files.
That is, the associated streambuf will be a filebuf.
In the following descriptions, assume
-- f is any of ifstream, ofstream, or fstream.
-- pfb is a filebuf*.
-- psb is a streambuf*.
-- name and ptr are char*s.
-- i, fd, len, and prot are ints.
-- mode is an int representing an open_mode.
Constructors
The constructors for xstream, where x is either
if, of, or f, are:
xstream()-
Constructs an unopened xstream.
xstream(name, mode, prot)-
Constructs an xstream and opens file name
using mode as the open mode and prot as the protection mode.
By default, prot is filebuf::openprot, which is 0644.
The error state (io_state) of the constructed xstream
will indicate failure in case the open fails.
xstream(d)-
Constructs an xstream connected to file descriptor d,
which must be already open.
xstream(d,ptr,len)-
Constructs an xstream connected to file descriptor d,
and, in addition, initializes
the associated filebuf to use the len bytes
at ptr as the reserve area.
If ptr is null or len is 0, the filebuf
will be unbuffered.
Member functions
f.attach(d)-
Connects f to the file descriptor d.
A failure occurs when f is already connected to a file.
A failure sets ios::failbit in f's error state.
d=f.detach()-
Disconnects the attached file descriptor from f and returns the file
descriptor. Before disconnection, flushes any waiting output to the file
associated with the file descriptor.
f.close()-
Closes any associated filebuf and thereby breaks the connection
of the f to a file.
f's error state is cleared except on failure.
A failure occurs when the call to f.rdbuf()->close() fails.
f.open(name,mode,prot)-
Opens file name and connects f to it.
If the file does not already exist,
an attempt is made to create it with protection mode prot
unless ios::nocreate is set.
By default, prot is filebuf::openprot, which is 0644.
Failure occurs if f is already open,
or the call to f.rdbuf()->open() fails.
ios::failbit is set in f's error status on failure.
The members of open_mode are bits that may be or'ed together.
(Because the or'ing returns an int, open() takes an
int rather than an open_mode argument.)
The meanings of these bits in mode are:
ios::app-
A seek to the end of file is performed.
Subsequent data written to the file is always added (appended)
at the end of file.
On some systems this is implemented in the operating system.
In
others it is implemented by seeking to the end of the file
before each write. ios::app implies ios::out.
ios::ate-
A seek to the end of the file is performed during the open().
ios::ate does not imply ios::out.
ios::in-
The file is opened for input.
ios::in is implied by construction and opens of ifstreams.
For fstreams it indicates that input operations should be
allowed if possible.
It is legal to include ios::in in the modes
of an ostream in which case it implies that the original
file (if it exists) should not be truncated.
If the file being opened for input does not exist, the open will
fail.
ios::out-
The file is opened for output.
ios::out is implied by construction and opens of ofstreams.
For fstream it says that output operations are to
be allowed.
ios::out may be specified even if prot
does not permit output.
ios::trunc-
If the file already exists, its contents will be truncated (discarded).
This mode is implied when ios::out is specified
(including implicit specification for ofstream)
and neither ios::ate nor ios::app is specified.
ios::nocreate-
If the file does not already exist, the open() will fail.
ios::noreplace-
If the file already exists, the open() will fail.
Only valid with ios::out.
pfb=f.rdbuf()-
Returns a pointer to the filebuf associated with f.
fstream::rdbuf() has the same meaning as
iostream::rdbuf() but is typed differently.
f.setbuf(p,len)-
Has the usual effect of a setbuf() (see
filebuf(3C++)),
offering space for a reserve area or requesting unbuffered I/O.
Normally the returned psb is f.rdbuf(), but it is 0
on failure.
A failure occurs if f is open or the call to f.rdbuf()->setbuf
fails.
References
filebuf(3C++),
istream(3C++),
ios(3C++),
ostream(3C++),
streambuf_pub(3C++)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004