SYNOPSIS

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.

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:
typedefbasic_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:
typedefbasic_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.