<fstream>
namespace std { class filebuf; class ifstream; class ofstream; };
Include the iostreams
standard header <fstream>
to define several classes that support
iostreams operations on
sequences stored in external
files.
filebuf
class filebuf : public streambuf { public: filebuf(); bool is_open() const; filebuf *open(const char *s, ios_base::openmode mode); filebuf *close(); protected: virtual pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out); virtual pos_type seekpos(pos_type pos, ios_base::openmode which = ios_base::in | ios_base::out); virtual int_type underflow(); virtual int_type pbackfail(int_type c = traits_type::eof()); virtual int_type overflow(int_type c = traits_type::eof()); virtual int sync(); virtual streambuf *setbuf(E *s, streamsize n); };
The class describes a stream buffer that controls the transmission of elements to and from a sequence of elements stored in an external file.
An object of class
filebuf
stores a
file pointer, which designates the
FILE
object
that controls the stream
associated with an
open file.
filebuf::filebuf
filebuf();
The constructor stores a null pointer in all the pointers controlling the input buffer and the output buffer. It also stores a null pointer in the file pointer.
filebuf::close
filebuf *close();
The member function returns a null pointer if the
file pointer fp
is a null pointer. Otherwise, it calls
fclose(fp)
.
If that function returns a nonzero value, the function
returns a null pointer. Otherwise, it returns this
to indicate that the file was successfully
closed.
filebuf::is_open
bool is_open();
The member function returns true if the file pointer is not a null pointer.
filebuf::open
filebuf *open(const char *s, ios_base::openmode mode);
The member function endeavors to open the file with
filename s
, by calling
fopen(s, strmode)
. Here
strmode
is determined from mode &
~(ate & |
binary)
:
ios_base::in
becomes "r"
(open existing file for reading).ios_base::out
or
ios_base::out |
ios_base::trunc
becomes "w"
(truncate existing file or create for writing).ios_base::out |
app
becomes "a"
(open existing file for appending all writes).ios_base::in | ios_base::out
becomes "r+"
(open existing file for reading and writing).ios_base::in | ios_base::out |
ios_base::trunc
becomes "w+"
(truncate existing file or create for reading and writing).ios_base::in | ios_base::out |
ios_base::app
becomes "a+"
(open existing file for reading and for appending all writes).If mode & ios_base::binary
is nonzero,
the function appends b
to strmode
to open a binary stream
instead of a text stream.
It then stores the value returned by fopen
in the
file pointer fp
. If
mode & ios_base::ate
is nonzero and the
file pointer is not a null pointer, the function calls
fseek(fp, 0,
SEEK_END)
to
position the stream at end-of-file. If that positioning operation
fails, the function calls
close(fp)
and
stores a null pointer in the file pointer.
If the file pointer is a null pointer, the function returns
a null pointer. Otherwise, it returns this
.
filebuf::overflow
virtual int_type overflow(int_type c = traits_type::eof());
If c !=
traits_type::eof()
,
the protected virtual member function endeavors to insert the element
traits_type::to_char_type(c)
into the
output buffer.
It can do so in various ways:
c
, to the associated stream designated by the
file pointer fp
as if by successive calls of the form
fputc(x, fp)
.
If any conversion or write fails, the function does not succeed.If the function cannot succeed, it returns traits_type::eof()
.
Otherwise, it returns
traits_type::not_eof(c)
.
filebuf::pbackfail
virtual int_type pbackfail(int_type c = traits_type::eof());
The protected virtual member function endeavors to put back an element
into the
input buffer,
then make it the current element (pointed to
by the next pointer). If c ==
traits_type::eof()
,
the element to push back is effectively the one already in the stream
before the current element. Otherwise, that element is replaced by
x =
traits_type::to_char_type(c)
.
The function can put back an element in various ways:
x
,
it can simply decrement the next pointer for the input buffer.x
in that position.ungetc
for an element
of type char.If the function cannot succeed, it returns
traits_type::eof()
. Otherwise, it returns
traits_type::not_eof(c)
.
filebuf::seekoff
virtual pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out);
The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
filebuf
, a stream position can be represented
by an object of type
fpos_t
.
Offset zero designates the first element of the stream.
(An object of type
pos_type
stores at least an fpos_t
object.)
For a file opened for both reading and writing,
both the input and output streams are positioned in tandem. To
switch
between inserting and extracting, you must call either
pubseekoff
or
pubseekpos
.
Calls to pubseekoff
(and hence to seekoff
)
have various limitations for
text streams
and binary streams.
If the
file pointer fp
is a null pointer, the function fails. Otherwise, it endeavors
to alter the stream position by calling
fseek(fp, off, way)
.
If that function succeeds and the resultant position
fposn
can be determined by calling
fgetpos(fp, &fposn)
,
the function succeeds. If the function succeeds, it returns
a value of type pos_type
containing fposn
.
Otherwise, it returns an invalid stream position.
filebuf::seekpos
virtual pos_type seekpos(pos_type pos, ios_base::openmode which = ios_base::in | ios_base::out);
The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
filebuf
, a stream position can be represented
by an object of type
fpos_t
.
Offset zero designates the first element of the stream.
(An object of type
pos_type
stores at least an fpos_t
object.)
For a file opened for both reading and writing,
both the input and output streams are positioned in tandem. To
switch
between inserting and extracting, you must call either
pubseekoff
or
pubseekpos
.
Calls to pubseekoff
(and hence to seekoff
)
have various limitations for
both text streams
and binary streams.
If the
file pointer fp
is a null pointer, the function fails. Otherwise, it endeavors
to alter the stream position by calling
fsetpos(fp, &fposn)
,
where fposn
is the fpos_t
object stored
in pos
. If that function succeeds, the function returns
pos
. Otherwise, it returns an invalid stream position.
filebuf::setbuf
virtual streambuf *setbuf(E *s, streamsize n);
The protected member function returns zero if the
file pointer fp
is a null pointer. Otherwise, it calls
setvbuf(fp, (char *)s,
_IOFBF, n * sizeof (E))
to offer the array of n
elements beginning at s
as a buffer for the stream. If that function returns a nonzero value,
the function returns a null pointer. Otherwise, it returns this
to signal success.
filebuf::sync
int sync();
The protected member function returns zero if the
file pointer fp
is a null pointer. Otherwise, it returns zero only if calls to both
overflow()
and
fflush(fp)
succeed in flushing any pending output to the stream.
filebuf::underflow
virtual int_type underflow();
The protected virtual member function endeavors to extract the current
element c
from the input stream, and return the element as
traits_type::to_int_type(c)
.
It can do so in various ways:
c
as the element stored in the read position
and advances the next pointer for the
input buffer.
fgetc(fp)
.
If any read or conversion fails,
the function does not succeed.If the function cannot succeed, it returns
traits_type::eof()
. Otherwise,
it returns c
, converted as described above.
ifstream
class ifstream : public istream { public: filebuf *rdbuf() const; ifstream(); explicit ifstream(const char *s, ios_base::openmode mode = ios_base::in); bool is_open() const; void open(const char *s, ios_base::openmode mode = ios_base::in); void close(); };
The class describes an object that controls
extraction of elements and encoded objects from a
stream buffer of class
filebuf
.
The object stores an object of class
filebuf
.
ifstream::ifstream
ifstream(); explicit ifstream(const char *s, ios_base::openmode mode = ios_base::in);
The first constructor initializes the base class by calling
istream(sb)
,
where sb
is the stored object of class
filebuf
.
It also initializes sb
by calling
filebuf()
.
The second constructor initializes the base class by calling
istream(sb)
.
It also initializes sb
by calling
filebuf()
,
then sb.open(s, mode
| ios_base::in)
. If the latter function returns a null
pointer, the constructor calls
setstate(failbit)
.
ifstream::close
void close();
The member function calls
rdbuf()->
close()
.
ifstream::is_open
bool is_open();
The member function returns
rdbuf()->
is_open()
.
ifstream::open
void open(const char *s, ios_base::openmode mode = ios_base::in);
The member function calls
rdbuf()->
open(s, mode | ios_base::in)
.
If that function returns a null pointer, the function calls
setstate(failbit)
.
ifstream::rdbuf
filebuf *rdbuf() const
The member function returns the address of the stored stream buffer.
ofstream
class ofstream : public ostream { public: filebuf *rdbuf() const; ofstream(); explicit ofstream(const char *s, ios_base::openmode mode = ios_base::out | ios_base::trunc); bool is_open() const; void open(const char *s, ios_base::openmode mode = ios_base::out | ios_base::trunc); void close(); };
The class describes an object that controls
insertion of elements and encoded objects into a
stream buffer of class
filebuf
.
The object stores an object of class
filebuf
.
ofstream::ofstream
ofstream(); explicit ofstream(const char *s, ios_base::openmode which = ios_base::out | ios_base::trunc);
The first constructor initializes the base class by calling
ostream(sb)
,
where sb
is the stored object of class
filebuf<E, T>
.
It also initializes sb
by calling
filebuf()
.
The second constructor initializes the base class by calling
ostream(sb)
.
It also initializes sb
by calling
filebuf()
,
then sb.open(s, mode
| ios_base::out)
. If the latter function returns a null
pointer, the constructor calls
setstate(failbit)
.
ofstream::close
void close();
The member function calls
rdbuf()->
close()
.
ofstream::is_open
bool is_open();
The member function returns
rdbuf()->
is_open()
.
ofstream::open
void open(const char *s, ios_base::openmode mode = ios_base::out | ios_base::trunc);
The member function calls
rdbuf()->
open(s, mode | ios_base::out)
.
If that function returns a null pointer, the function calls
setstate(failbit)
.
ofstream::rdbuf
filebuf *rdbuf() const
The member function returns the address of the stored stream buffer.
See also the Table of Contents and the Index.
Copyright © 1992-1996 by P.J. Plauger. All rights reserved.