basic_filebuf (3C++std) - Tru64 UNIX
Standard C++ LibraryCopyright 1996, Rogue Wave Software, Inc.
NAME
basic_filebuf,filebuf
This page describes the ANSI basic_filebuf class. If you would like
information on the pre-ANSI filebuf class, use the command:
man 3C++ filebuf or man filebuf.3C++
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:
• a character input sequence
• a character output sequence
The restrictions on reading and writing a sequence controlled 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 cannot be read. If
the file is not open for writing the output sequence cannot be written. A
joint file position is maintained for both the input and output sequences.
A file provides 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 converts 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 overflow(int_type c = traits::eof());
virtual int_type pbackfail(int_type c = traits::eof());
virtual int_type underflow();
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 parameter 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 parameter 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>(), then calls
open(fd). This function is not described in the C++ standard, and is
provided as an extension in order to manipulate pipes, sockets or other
UNIX devices, that can be accessed through file descriptors.
DESTRUCTOR
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 permission. It does
not appear in the Standard C++ description of the function open and is
provided as an extension. It determines the file read/write/execute
permissions 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 file previously opened and identified by its file
descriptor fd, to the basic_filebuf object. This function is not
described in the C++ standard, and is provided 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 write c into it. If there is no position available,
the function output the content of the buffer to the associated file and
then write c at the new current put position. If the operation 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, move 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 performing state
dependent conversion, only support seeking to the beginning of the file,
to the current position, or to a position previously obtained by a call
to one of the iostreams 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
beginning of the file, to the current position, or to a position
previously obtained by a call to one of the iostreams seeking functions.
basic_filebuf<charT,traits>*
setbuf(char_type*s, streamsize n);
If s is not a null pointer, output the content of the current buffer to
the associated file, then delete the current buffer and replace it by s.
Otherwise resize the current buffer to size n after outputting its
content to the associated file if necessary.
int
sync();
Synchronizes the content 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 content
of this position. Otherwise fills up the buffer by reading characters
from the associated file and if it succeeds, returns the content of the
new current position. The function returns traits::eof() to indicate
failure. In wide characters file buffer, underflow converts the external
mutltibytes 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.
EXAMPLES
//
// 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++std), ios_base(3C++std), basic_ios(3C++std),
basic_streambuf(3C++std), basic_ifstream(3C++std), basic_ofstream(3C++std),
basic_fstream(3C++std)
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
privacy and legal statement
