Standard C++ Library
Copyright 1998, Rogue Wave Software, Inc.
NAME
basic_filebuf, filebuf, wfilebuf - Class that associates the
input or output sequence with a file.
SYNOPSIS
#include <fstream>
template<class charT, class traits = char_traits<charT> >
class basic_filebuf
: public basic_streambuf<charT, traits>
DESCRIPTION
The template class basic_filebuf is derived from
basic_streambuf. It associates the input or output sequence
with a file. Each object of type
basic_filebuf<charT,_traits> controls two character
sequences:
o A character input sequence
o A character output sequence
The restrictions on reading and writing a sequence con-
trolled by an object of class basic_filebuf<charT,traits>
are the same as for reading and writing with the Standard C
library files.
If the file is not open for reading, the input sequence can-
not be read. If the file is not open for writing, the output
sequence cannot be written. A joint file position is main-
tained for both the input and output sequences.
A file has byte sequences, so the basic_filebuf class treats
a file as the external source (or sink) byte sequence. In
order to provide the contents of a file as wide character
sequences, a wide-oriented file buffer called wfilebuf con-
verts wide character sequences to multibytes character
sequences (and vice versa) according to the current locale
being used in the stream buffer.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_filebuf
: public basic_streambuf<charT, traits> {
public:
typedef traits traits_type;
typedef charT char_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
basic_filebuf();
basic_filebuf(int fd);
virtual ~basic_filebuf();
bool is_open() const;
basic_filebuf<charT, traits>* open(const char *s,
ios_base::openmode,
long protection = 0666);
basic_filebuf<charT, traits>* open(int fd);
basic_filebuf<charT, traits>* close();
protected:
virtual int showmanyc();
virtual int_type underflow();
virtual int_type overflow(int_type c = traits::eof());
virtual int_type pbackfail(int_type c = traits::eof());
virtual basic_streambuf<charT,traits>*
setbuf(char_type *s,streamsize n);
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 sp,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual int sync();
virtual streamsize xsputn(const char_type* s,
streamsize n);
};
TYPES
char_type
The type char_type is a synonym for the template parame-
ter charT.
filebuf
The type filebuf is an instantiation of class
basic_filebuf on type char:
typedef basic_filebuf<char> filebuf;
int_type
The type int_type is a synonym of type traits::in_type.
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 param-
eter traits.
wfilebuf
The type wfilebuf is an instantiation of class
basic_filebuf on type wchar_t:
typedef basic_filebuf<wchar_t> wfilebuf;
CONSTRUCTORS
basic_filebuf();
Constructs an object of class
basic_filebuf<charT,traits>, initializing the base class
with basic_streambuf<charT,traits>().
basic_filebuf(int fd);
Constructs an object of class
basic_filebuf<charT,traits>, initializing the base class
with basic_streambuf<charT,traits>(). It then calls
open(fd) with file descriptor fd. This function is not
described in the C++ standard, and is included as an
extension to manipulate pipes, sockets, or other UNIX
devices that can be accessed through file descriptor.
DESTRUCTORS
virtual ~basic_filebuf();
Calls close() and destroys the object.
MEMBER FUNCTIONS
basic_filebuf<charT,traits>*
close();
If is_open() == false, returns a null pointer. Otherwise,
closes the file, and returns *this.
bool
is_open() const;
Returns true if the associated file is open.
basic_filebuf<charT,traits>*
open(const char* s, ios_base::openmode mode,
long protection = 0666);
If is_open() == true, returns a null pointer. Otherwise
opens the file, whose name is stored in the null-
terminated byte-string s. The file open modes are given
by their C-equivalent description (see the C function
fopen):
in "w"
in|binary "rb"
out "w"
out|app "a"
out|binary "wb"
out|binary|app "ab"
out|in "r+"
out|in|app "a+"
out|in|binary "r+b"
out|in|binary|app "a+b"
trunc|out "w"
trunc|out|binary "wb"
trunc|out|in "w+"
trunc|out|in|binary "w+b"
The third argument, protection, is used as the file per-
mission. It does not appear in the Standard C++ descrip-
tion of the function open and is included as an exten-
sion. It determines the file read/write/execute permis-
sions under UNIX. It is more limited under DOS, since
files are always readable and do not have special execute
permission. If the open function fails, it returns a null
pointer.
basic_filebuf<charT,traits>*
open(int fd);
Attaches the previously opened file, which is identified
by its file descriptor fd, to the basic_filebuf object.
This function 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.
int_type
overflow(int_type c = traits::eof() );
If the output sequence has a put position available, and
c is not traits::eof(), then writes c into it. If there
is no position available, the function outputs the con-
tents of the buffer to the associated file and then
writes c at the new current put position. If the opera-
tion fails, the function returns traits::eof(). Otherwise
it returns traits::not_eof(c). In wide characters file
buffer, overflow converts the internal wide characters to
their external multibytes representation by using the
locale::codecvt facet located in the locale object imbued
in the stream buffer.
int_type
pbackfail(int_type c = traits::eof() );
Puts back the character designated by c into the input
sequence. If traits::eq_int_type(c,traits::eof()) returns
true, moves the input sequence one position backward. If
the operation fails, the function returns traits::eof().
Otherwise it returns traits::not_eof(c).
pos_type
seekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which = ios_base::in |
ios_base::out);
If the open mode is in | out, alters the stream position
of both the input and the output sequence. If the open
mode is in, alters the stream position of only the input
sequence, and if it is out, alters the stream position of
only the output sequence. The new position is calculated
by combining the two parameters off (displacement) and
way (reference point). If the current position of the
sequence is invalid before repositioning, the operation
fails and the return value is pos_type(off_type(-1)).
Otherwise the function returns the current new position.
File buffers using locale::codecvt facet and performing
state dependent conversion support only seeking to the
beginning of the file, to the current position, or to a
position previously obtained by a call to one of the ios-
treams seeking functions.
pos_type
seekpos(pos_type sp,ios_base::openmode which =
ios_base::in | ios_base::out);
If the open mode is in | out, alters the stream position
of both the input and the output sequence. If the open
mode is in, alters the stream position of only the input
sequence, and if it is out, alters the stream position of
only the output sequence. If the current position of the
sequence is invalid before repositioning, the operation
fails and the return value is pos_type(off_type(-1)).
Otherwise the function returns the current new position.
File buffers using locale::codecvt facet performing state
dependent conversion, only support seeking to the begin-
ning of the file, to the current position, or to a posi-
tion previously obtained by a call to one of the ios-
treams seeking functions.
basic_filebuf<charT,traits>*
setbuf(char_type*s, streamsize n);
If s is not a null pointer, outputs the content of the
current buffer to the associated file, then deletes the
current buffer and replaces it by s. Otherwise resizes
the current buffer to size n after outputting its con-
tents to the associated file, if necessary.
int
sync();
Synchronizes the contents of the external file, with its
image maintained in memory by the file buffer. If the
function fails, it returns -1; otherwise it returns 0.
int_type
underflow();
If the input sequence has a read position available,
returns the contents of this position. Otherwise fills up
the buffer by reading characters from the associated
file, and if it succeeds, returns the contents of the new
current position. The function returns traits::eof() to
indicate failure. In wide characters file buffer, under-
flow converts the external multibytes characters to their
wide character representation by using the
locale::codecvt facet located in the locale object imbued
in the stream buffer.
streamsize
xsputn(const char_type* s, streamsize n);
Writes up to n characters to the output sequence. The
characters written are obtained from successive elements
of the array whose first element is designated by s. The
function returns the number of characters written.
EXAMPLE
//
// stdlib/examples/manual/filebuf.cpp
//
#include<iostream>
#include<fstream>
void main ( )
{
using namespace std;
// create a read/write file-stream object on tiny char
// and attach it to the file "filebuf.out"
ofstream out("filebuf.out",ios_base::in |
ios_base::out);
// tie the istream object to the ofstream object
istream in(out.rdbuf());
// output to out
out << "Il errait comme un ame en peine";
// seek to the beginning of the file
in.seekg(0);
// output in to the standard output
cout << in.rdbuf() << endl;
// close the file "filebuf.out"
out.close();
// open the existing file "filebuf.out"
// and truncate it
out.open("filebuf.out",ios_base::in | ios_base::out |
ios_base::trunc);
// set the buffer size
out.rdbuf()->pubsetbuf(0,4096);
// open the source code file
ifstream ins("filebuf.cpp");
//output it to filebuf.out
out << ins.rdbuf();
// seek to the beginning of the file
out.seekp(0);
// output the all file to the standard output
cout << out.rdbuf();
}
SEE ALSO
char_traits(3C++), ios_base(3C++), basic_ios(3C++),
basic_streambuf(3C++), basic_ifstream(3C++),
basic_ofstream(3C++), basic_fstream(3C++)
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section
27.8.1.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee