.\" ident @(#)basic_filebuf.3 .\" Standard Template Library .\" $$RW_INSERT_HEADER "slyrs.man" .TH basic_filebuf 3C++ "02 Apr 1998" "Rogue Wave Software" "-" .ce2 Standard C++ Library Copyright 1998, Rogue Wave Software, Inc. .SH NAME \f2basic_filebuf\fP, \f2filebuf\fP, \f2wfilebuf\fP \- Class that associates the input or output sequence with a file. .SH SYNOPSIS .RE .RS 0 #include .br template > .br class basic_filebuf .br : public basic_streambuf .SH 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 controls two character sequences: .HP .5i \(bu A character input sequence .HP .5i \(bu A character output sequence .HP 0 The restrictions on reading and writing a sequence controlled by an object of class basic_filebuf 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 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 converts wide character sequences to multibytes character sequences (and vice versa) according to the current locale being used in the stream buffer. .SH INTERFACE .br template > .br class basic_filebuf .br : public basic_streambuf { .br .br public: .br .RE .RS 1 typedef traits traits_type; .br typedef charT char_type; .br typedef typename traits::int_type int_type; .br typedef typename traits::pos_type pos_type; .br typedef typename traits::off_type off_type; .RE .RS 0 .RE .RS 1 basic_filebuf(); .br basic_filebuf(int fd); .RE .RS 0 .RE .RS 1 virtual ~basic_filebuf(); .RE .RS 0 .RE .RS 1 bool is_open() const; .br basic_filebuf* open(const char *s, .RE .RS 35 ios_base::openmode, .br long protection = 0666); .RE .RS 0 .RE .RS 1 basic_filebuf* open(int fd); .br basic_filebuf* close(); .RE .RS 0 .br protected: .br .RE .RS 1 virtual int showmanyc(); .br virtual int_type underflow(); .br virtual int_type overflow(int_type c = traits::eof()); .br virtual int_type pbackfail(int_type c = traits::eof()); .RE .RS 0 .RE .RS 1 virtual basic_streambuf* .RE .RS 3 setbuf(char_type *s,streamsize n); .RE .RS 0 .RE .RS 1 virtual pos_type seekoff(off_type off, .RE .RS 26 ios_base::seekdir way, .br ios_base::openmode which = .br ios_base::in | ios_base::out); .RE .RS 0 .RE .RS 1 virtual pos_type seekpos(pos_type sp, .RE .RS 26 ios_base::openmode which = .br ios_base::in | ios_base::out); .RE .RS 1 virtual int sync(); .br virtual streamsize xsputn(const char_type* s, .RE .RS 27 streamsize n); .RE .RS 0 .br }; .SH TYPES .br char_type .RE .RS 3 The type \f2char_type\fP is a synonym for the template parameter \f2charT\fP. .RE .br filebuf .RE .RS 3 The type \f2filebuf\fP is an instantiation of class \f2basic_filebuf\fP on type \f2char\fP: \f2typedef basic_filebuf filebuf;\fP .RE .br int_type .RE .RS 3 The type \f2int_type\fP is a synonym of type \f2traits::in_type\fP. .RE .br off_type .RE .RS 3 The type \f2off_type\fP is a synonym of type \f2traits::off_type\fP. .RE .br pos_type .RE .RS 3 The type \f2pos_type\fP is a synonym of type \f2traits::pos_type\fP. .RE .br traits_type .RE .RS 3 The type \f2traits_type\fP is a synonym for the template parameter \f2traits\fP. .RE .br wfilebuf .RE .RS 3 The type \f2wfilebuf\fP is an instantiation of class \f2basic_filebuf\fP on type \f2wchar_t\fP: \f2typedef basic_filebuf wfilebuf;\fP .RE .SH CONSTRUCTORS .br basic_filebuf(); .RE .RS 3 Constructs an object of class \f2basic_filebuf\fP, initializing the base class with \f2basic_streambuf()\fP. .RE .br basic_filebuf(int fd); .RE .RS 3 Constructs an object of class \f2basic_filebuf\fP, initializing the base class with \f2basic_streambuf()\fP. It then calls \f2open(fd)\fP with file descriptor \f2fd\fP. 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. .RE .SH DESTRUCTORS .br virtual ~basic_filebuf(); .RE .RS 3 Calls \f2close()\fP and destroys the object. .RE .SH MEMBER FUNCTIONS .br basic_filebuf* .br close(); .RE .RS 3 If \f2is_open() == false\fP, returns a null pointer. Otherwise, closes the file, and returns \f2*this\fP. .RE .br bool .br is_open() const; .RE .RS 3 Returns \f2true\fP if the associated file is open. .RE .br basic_filebuf* .br open(const char* s, ios_base::openmode mode, .RE .RS 2 long protection = 0666); .RE .RS 3 If \f2is_open() == true\fP, returns a null pointer. Otherwise opens the file, whose name is stored in the null-terminated byte-string \f2s\fP. The file open modes are given by their C-equivalent description (see the C function \f2fopen\fP): in "w" .br in|binary "rb" .br out "w" .br out|app "a" .br out|binary "wb" .br out|binary|app "ab" .br out|in "r+" .br out|in|app "a+" .br out|in|binary "r+b" .br out|in|binary|app "a+b" .br trunc|out "w" .br trunc|out|binary "wb" .br trunc|out|in "w+" .br trunc|out|in|binary "w+b" The third argument, \f2protection\fP, is used as the file permission. It does not appear in the Standard C++ description of the function \f2open\fP and is included 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 \f2open\fP function fails, it returns a null pointer. .RE .br basic_filebuf* .br open(int fd); .RE .RS 3 Attaches the previously opened file, which is identified by its file descriptor \f2fd\fP, to the \f2basic_filebuf\fP 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. .RE .br int_type .br overflow(int_type c = traits::eof() ); .RE .RS 3 If the output sequence has a put position available, and \f2c\fP is not\f2 traits::eof()\fP, then writes \f2c\fP into it. If there is no position available, the function outputs the contents of the buffer to the associated file and then writes \f2c\fP at the new current put position. If the operation fails, the function returns \f2traits::eof()\fP. Otherwise it returns \f2traits::not_eof(c)\fP. In wide characters file buffer, \f2overflow\fP converts the internal wide characters to their external multibytes representation by using the \f2locale::codecvt\fP facet located in the locale object imbued in the stream buffer. .RE .br int_type .br pbackfail(int_type c = traits::eof() ); .RE .RS 3 Puts back the character designated by \f2c\fP into the input sequence. If \f2traits::eq_int_type(c,traits::eof())\fP returns \f2true\fP, moves the input sequence one position backward. If the operation fails, the function returns \f2traits::eof()\fP. Otherwise it returns\f2 traits::not_eof(c)\fP. .RE .br pos_type .br seekoff(off_type off, ios_base::seekdir way, .RE .RS 7 ios_base::openmode which = ios_base::in | .br ios_base::out); .RE .RS 3 If the open mode is \f2in | out\fP, alters the stream position of both the input and the output sequence. If the open mode is \f2in\fP, alters the stream position of only the input sequence, and if it is \f2out\fP, alters the stream position of only the output sequence. The new position is calculated by combining the two parameters \f2off\fP (displacement) and \f2way\fP (reference point). If the current position of the sequence is invalid before repositioning, the operation fails and the return value is \f2pos_type(off_type(-1))\fP. Otherwise the function returns the current new position. File buffers using \f2locale::codecvt\fP 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 iostreams seeking functions. .RE .RE .RS 0 pos_type .br seekpos(pos_type sp,ios_base::openmode which = ios_base::in | ios_base::out); .RE .RS 3 If the open mode is \f2in | out\fP, alters the stream position of both the input and the output sequence. If the open mode is \f2in\fP, alters the stream position of only the input sequence, and if it is \f2out\fP, 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 \f2pos_type(off_type(-1))\fP. Otherwise the function returns the current new position. File buffers using \f2locale::codecvt\fP 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. .RE .br basic_filebuf* .br setbuf(char_type*s, streamsize n); .RE .RS 3 If \f2s\fP 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 \f2s\fP. Otherwise resizes the current buffer to size \f2n\fP after outputting its contents to the associated file, if necessary. .RE .br int .br sync(); .RE .RS 3 Synchronizes the contents of the external file, with its image maintained in memory by the file buffer. If the function fails, it returns \f2-1\fP; otherwise it returns \f20\fP. .RE .br int_type .br underflow(); .RE .RS 3 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 \f2traits::eof()\fP to indicate failure. In wide characters file buffer, \f2underflow\fP converts the external multibytes characters to their wide character representation by using the \f2locale::codecvt\fP facet located in the locale object imbued in the stream buffer. .RE .br streamsize .br xsputn(const char_type* s, streamsize n); .RE .RS 3 Writes up to \f2n\fP characters to the output sequence. The characters written are obtained from successive elements of the array whose first element is designated by \f2s\fP. The function returns the number of characters written. .RE .SH EXAMPLE .br // .br // stdlib/examples/manual/filebuf.cpp .br // .br #include .br #include .br .br void main ( ) .br { .RE .RS 1 using namespace std; .RE .RS 0 .RE .RS 2 // create a read/write file-stream object on tiny char .br // and attach it to the file "filebuf.out" .RE .RS 1 ofstream out("filebuf.out",ios_base::in | .RE .RS 15 ios_base::out); .RE .RS 0 .RE .RS 2 // tie the istream object to the ofstream object .RE .RS 1 istream in(out.rdbuf()); .RE .RS 0 .RE .RS 2 // output to out .RE .RS 1 out << "Il errait comme un ame en peine"; .br .RE .RS 2 // seek to the beginning of the file .RE .RS 1 in.seekg(0); .RE .RS 0 .RE .RS 2 // output in to the standard output .RE .RS 1 cout << in.rdbuf() << endl; .RE .RS 0 .RE .RS 2 // close the file "filebuf.out" .RE .RS 1 out.close(); .RE .RS 0 .RE .RS 2 // open the existing file "filebuf.out" .br // and truncate it .RE .RS 1 out.open("filebuf.out",ios_base::in | ios_base::out | .RE .RS 10 ios_base::trunc); .RE .RS 0 .RE .RS 2 // set the buffer size .RE .RS 1 out.rdbuf()->pubsetbuf(0,4096); .br .RE .RS 2 // open the source code file .RE .RS 1 ifstream ins("filebuf.cpp"); .RE .RS 0 .RE .RS 2 //output it to filebuf.out .RE .RS 1 out << ins.rdbuf(); .RE .RS 0 .RE .RS 2 // seek to the beginning of the file .RE .RS 1 out.seekp(0); .RE .RS 0 .RE .RS 2 // output the all file to the standard output .RE .RS 1 cout << out.rdbuf(); .RE .RS 0 } .SH 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 .SH STANDARDS CONFORMANCE ANSI X3J16/ISO WG21 Joint C++ Committee