Google Git
Sign in
apache / stdcxx / e897e9fca7fb803e4b0aa51523ca6a8397f8cd45 / . / doc / stdlibref / basic-filebuf.html
blob: be0d5e7e4e27d19493fefc4c4b2157bbcd64a139 [file] [log] [blame]
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed
with this work for additional information regarding copyright
ownership. The ASF licenses this file to you under the Apache
License, Version 2.0 (the License); you may not use this file
except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied. See the License for the specific language governing
permissions and limitations under the License.
Copyright 1999-2007 Rogue Wave Software, Inc.
-->
<HTML>
<HEAD>
<TITLE>basic_filebuf</TITLE>
<LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
<BODY BGCOLOR=#FFFFFF>
<A HREF="bad-typeid.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="basic-fstream.html"><IMG SRC="images/bnext.gif" WIDTH=25 HEIGHT=21 ALT="Next file" BORDER=O></A><DIV CLASS="DOCUMENTNAME"><B>Apache C++ Standard Library Reference Guide</B></DIV>
<H2>basic_filebuf</H2>
<P><B>Library:</B>&nbsp;&nbsp;<A HREF="2-11.html">Input/output</A></P>
<PRE><HR><B><I>basic_filebuf</I></B> <IMG SRC="images/inherits.gif"> <B><I><A HREF="basic-streambuf.html">basic_streambuf</A></I></B><HR></PRE>
<UL>
<LI><A HREF="#sec1">Local Index</A></LI>
<LI><A HREF="#sec2">Summary</A></LI>
<LI><A HREF="#sec3">Synopsis</A></LI>
<LI><A HREF="#sec4">Description</A></LI>
<LI><A HREF="#sec5">Interface</A></LI>
<LI><A HREF="#sec6">Member Types</A></LI>
<LI><A HREF="#sec7">Nonmember Types</A></LI>
<LI><A HREF="#sec8">Constructors</A></LI>
<LI><A HREF="#sec9">Destructors</A></LI>
<LI><A HREF="#sec10">Member Functions</A></LI>
<LI><A HREF="#sec11">Example</A></LI>
<LI><A HREF="#sec12">See Also</A></LI>
<LI><A HREF="#sec13">Standards Conformance</A></LI>
</UL>
<A NAME="sec1"><H3>Local Index</H3></A>
<H4>Members</H4>
<UL><TABLE CELLPADDING=3>
<TR><TD VALIGN=top>
<A HREF="#idx51">attach()</A><BR>
<A HREF="#idx47">basic_filebuf()</A><BR>
<A HREF="#idx40">char_type</A><BR>
<A HREF="#idx52">close()</A><BR>
<A HREF="#idx53">detach()</A><BR>
<A HREF="#idx66">fd()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx41">int_type</A><BR>
<A HREF="#idx54">is_open()</A><BR>
<A HREF="#idx42">off_type</A><BR>
<A HREF="#idx55">open()</A><BR>
<A HREF="#idx58">overflow()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx59">pbackfail()</A><BR>
<A HREF="#idx43">pos_type</A><BR>
<A HREF="#idx60">seekoff()</A><BR>
<A HREF="#idx61">seekpos()</A><BR>
<A HREF="#idx62">setbuf()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx63">sync()</A><BR>
<A HREF="#idx44">traits_type</A><BR>
<A HREF="#idx64">underflow()</A><BR>
<A HREF="#idx65">xsputn()</A><BR>
<A HREF="#idx50">~basic_filebuf()</A><BR>
</TD></TR>
</TABLE></UL>
<H4>Non-Members</H4>
<UL><TABLE CELLPADDING=3>
<TR><TD VALIGN=top>
<A HREF="#idx45">filebuf</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx46">wfilebuf</A><BR>
</TD>
<TD VALIGN=top></TD></TR>
</TABLE></UL>
<A NAME="sec2"><H3>Summary</H3></A>
<P>Class that associates the input or output sequence with a file</P>
<A NAME="sec3"><H3>Synopsis</H3></A>
<PRE>#include &lt;fstream&gt;
namespace std {
template&lt;class charT, class traits = char_traits&lt;charT&gt; &gt;
class basic_filebuf;
}
</PRE>
<A NAME="sec4"><H3>Description</H3></A>
<P>The class template <B><I>basic_filebuf</I></B> is derived from <B><I><A HREF="basic-streambuf.html">basic_streambuf</A></I></B>. It associates the input or output sequence with a file. Each object of type <B><I>basic_filebuf</I></B> controls two character sequences:</P>
<UL>
<LI><P CLASS="LIST">A character input sequence</P></LI>
<LI><P CLASS="LIST">A character output sequence</P></LI>
</UL>
<P>The restrictions on reading and writing a sequence controlled by an object of class <B><I>basic_filebuf</I></B> are the same as for reading and writing with the Standard C library files.</P>
<P>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.</P>
<P>A file has byte sequences, so the <B><I>basic_filebuf</I></B> 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 <B><I>wfilebuf</I></B> converts wide character sequences to multibyte character sequences (and vice versa) according to the current locale being used in the stream buffer. </P>
<A NAME="sec5"><H3>Interface</H3></A>
<UL><PRE>namespace std {
template&lt;class charT, class traits = char_traits&lt;charT&gt; &gt;
class basic_filebuf : public basic_streambuf&lt;charT, traits&gt;
{
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();
// extensions:
basic_filebuf(int, char_type*, streamsize);
basic_filebuf(FILE*, char_type*, streamsize);
virtual ~basic_filebuf();
bool is_open() const;
// extensions:
basic_filebuf&lt;charT, traits&gt;* open(const char*,
ios_base::openmode,
long = 0666);
basic_filebuf&lt;charT, traits&gt;* open(int, char_type* = 0,
streamsize = /* default size */);
basic_filebuf&lt;charT, traits&gt;* open(FILE *, char_type*,
streamsize);
basic_filebuf&lt;charT, traits&gt;* attach(int);
int detach();
int fd() const;
basic_filebuf&lt;charT, traits&gt;* close();
protected:
virtual int showmanyc();
virtual int_type underflow();
virtual int_type overflow(int_type = traits::eof());
virtual int_type pbackfail(int_type = traits::eof());
virtual basic_streambuf&lt;charT,traits&gt;*
setbuf(char_type*,streamsize);
virtual pos_type seekoff(off_type,
ios_base::seekdir,
ios_base::openmode =
ios_base::in | ios_base::out);
virtual pos_type seekpos(pos_type,
ios_base::openmode =
ios_base::in | ios_base::out);
virtual int sync();
virtual streamsize xsputn(const char_type*,
streamsize);
};
</PRE></UL>
<A NAME="sec6"><H3>Member Types</H3></A>
<A NAME="idx40"></A><PRE><B>char_type</B></PRE>
<UL>
<P>The type <SAMP>char_type</SAMP> is a synonym for the template parameter <SAMP>charT</SAMP>.</P>
</UL>
<A NAME="idx41"></A><PRE><B>int_type</B></PRE>
<UL>
<P>The type <SAMP>int_type</SAMP> is a synonym of type <SAMP>traits::int_type</SAMP>.</P>
</UL>
<A NAME="idx42"></A><PRE><B>off_type</B></PRE>
<UL>
<P>The type <SAMP>off_type</SAMP> is a synonym of type <SAMP>traits::off_type</SAMP>.</P>
</UL>
<A NAME="idx43"></A><PRE><B>pos_type</B></PRE>
<UL>
<P>The type <SAMP>pos_type</SAMP> is a synonym of type <SAMP>traits::pos_type</SAMP>.</P>
</UL>
<A NAME="idx44"></A><PRE><B>traits_type</B></PRE>
<UL>
<P>The type <SAMP>traits_type</SAMP> is a synonym for the template parameter <SAMP>traits</SAMP>.</P>
</UL>
<A NAME="sec7"><H3>Nonmember Types</H3></A>
<A NAME="idx45"></A><PRE><B>filebuf</B></PRE>
<UL>
<P>The type <SAMP>filebuf</SAMP> is a specialization of class template <B><I>basic_filebuf</I></B> on type <SAMP>char</SAMP>:</P>
<P><SAMP>typedef basic_filebuf&lt;char&gt; filebuf;</SAMP></P>
</UL>
<A NAME="idx46"></A><PRE><B>wfilebuf</B> </PRE>
<UL>
<P>The type <SAMP>wfilebuf</SAMP> is a specialization of class template <B><I>basic_filebuf</I></B> on type <SAMP>wchar_t</SAMP>:</P>
<P><SAMP>typedef basic_filebuf&lt;wchar_t&gt; wfilebuf;</SAMP></P>
</UL>
<A NAME="sec8"><H3>Constructors</H3></A>
<A NAME="idx47"></A><PRE><B>basic_filebuf</B>();</PRE>
<UL>
<P>Constructs an object of class <B><I>basic_filebuf</I></B>, initializing the base class with <SAMP>basic_streambuf&lt;charT,traits&gt;()</SAMP>.</P>
</UL>
<A NAME="idx48"></A><PRE><B>basic_filebuf</B>(int fd, char_type *buf = 0,
streamsize n = /* default size */);</PRE>
<UL>
<P>Constructs an object of class <B><I>basic_filebuf</I></B>, initializing the base class with <SAMP>basic_streambuf&lt;charT,traits&gt;()</SAMP>. It then calls <SAMP>open(fd, buf, n)</SAMP>. </P>
</UL>
<BLOCKQUOTE><HR><B>
NOTE -- This function is not part of the C++ Standard, but is included here as an extension to manipulate pipes, sockets, or other UNIX devices that can be accessed through file descriptors. See <A HREF="B.html">Appendix&nbsp;B</A> for a complete list of extensions of this implementation.
</B><HR></BLOCKQUOTE>
<A NAME="idx49"></A><PRE><B>basic_filebuf</B>(FILE *fp, char_type *buf = 0,
streamsize n = /* default size */);</PRE>
<UL>
<P>Constructs an object of class <B><I>basic_filebuf</I></B>, initializing the base class with <SAMP>basic_streambuf&lt;charT,traits&gt;()</SAMP>. It then calls <SAMP>open(fp, buf, n)</SAMP>. </P>
</UL>
<BLOCKQUOTE><HR><B>
NOTE -- This function is not part of the C++ Standard, but is included here as an extension. See <A HREF="B.html">Appendix&nbsp;B</A> for a complete list of extensions of this implementation.
</B><HR></BLOCKQUOTE>
<A NAME="sec9"><H3>Destructors</H3></A>
<A NAME="idx50"></A><PRE>virtual <B>~basic_filebuf</B>();</PRE>
<UL>
<P>Calls <SAMP>close()</SAMP> and destroys the object. </P>
</UL>
<A NAME="sec10"><H3>Member Functions</H3></A>
<A NAME="idx51"></A><PRE>basic_filebuf&lt;charT, traits&gt;*
<B>attach</B>(int fd);</PRE>
<UL>
<P>Attaches the object to the open file descriptor <SAMP>fd</SAMP>. Unless <SAMP>detach()</SAMP> is called, the file descriptor will be closed during the next call to <SAMP>close()</SAMP> or at the time the object is destroyed. Returns <SAMP>this</SAMP> on success; otherwise returns <SAMP>0</SAMP> (for example, when <SAMP>is_open()</SAMP> returns <SAMP>true</SAMP> prior to the call).</P>
</UL>
<BLOCKQUOTE><HR><B>
NOTE -- This function is not part of the C++ Standard, but is provided as an extension of this implementation for compatibility with Classic Iostreams. See </B><A HREF="B.html">Appendix&nbsp;B</A><B> for a complete list of extensions of this implementation.
</B><HR></BLOCKQUOTE>
<A NAME="idx66"></A><PRE>int
<B>fd</B>() const;</PRE>
<UL>
<P>If <SAMP>is_open()</SAMP> returns <SAMP>true</SAMP>, returns the associated file descriptor, otherwise -1.</P>
</UL>
<BLOCKQUOTE><HR><B>
NOTE -- This function is not part of the C++ Standard, but is provided as an extension of this implementation for compatibility with Classic Iostreams. See </B><A HREF="B.html">Appendix&nbsp;B</A><B> for a complete list of extensions of this implementation.
</B><HR></BLOCKQUOTE>
<A NAME="idx52"></A><PRE>
basic_filebuf&lt;charT,traits&gt;*
<B>close</B>();</PRE>
<UL>
<P>If <SAMP>is_open() == false</SAMP>, returns a null pointer. Otherwise, if a <SAMP>put</SAMP> area exists, calls <SAMP>overflow(traits_type::eof())</SAMP> to flush the contents of the buffer. If <SAMP>overflow()</SAMP> is the last virtual member function called on an object, among the functions <SAMP>underflow()</SAMP>, <SAMP>overflow()</SAMP>, <SAMP>seekoff()</SAMP>, and <SAMP>seekpos()</SAMP>, the <SAMP>close()</SAMP> function calls:</P>
<UL><PRE> use_facet&lt;codecvt &lt;char_type, char,
typename traits_type::state_type&gt;
&gt;(getloc()).unshift
</PRE></UL>
<P>The call is made one or more times to determine a termination sequence. The <SAMP>close()</SAMP> function then inserts the characters of the termination sequence, calls <SAMP>overflow(traits_type::eof())</SAMP> again, and closes the file, just like a call to <SAMP>std::fclose</SAMP>.</P>
</UL>
<A NAME="idx53"></A><PRE>int
<B>detach</B>(); </PRE>
<UL>
<P>Flushes any pending output to the file associated with the object and, if the operation succeeds, disassociates the object from the underlying file descriptor or <SAMP>FILE*</SAMP> without closing the latter. Returns <SAMP>fd()</SAMP> on success. Returns <SAMP>-1</SAMP> on failure (for example, when the object was unable to flush the pending output).</P>
</UL>
<BLOCKQUOTE><HR><B>
NOTE -- <B>This function is not part of the C++ Standard, but is provided as an extension of this implementation for compatibility with Classic </B><B><I>Iostreams</I></B><B>. See </B><A HREF="B.html">Appendix&nbsp;B</A><B> for a complete list of extensions of this implementation.
</B><HR></BLOCKQUOTE>
<A NAME="idx54"></A><PRE>bool
<B>is_open</B>() const; </PRE>
<UL>
<P>Returns <SAMP>true</SAMP> if the associated file is open.</P>
</UL>
<A NAME="idx55"></A><PRE>basic_filebuf&lt;charT,traits&gt;*
<B>open</B>(const char* fname, ios_base::openmode mode,
long protection = 0666); </PRE>
<UL>
<P>If <SAMP>is_open() == true</SAMP>, returns a null pointer. Otherwise, if <SAMP>(fname != 0)</SAMP> evaluates to <SAMP>true</SAMP>, opens the file whose name is stored in the NUL-terminated byte string <SAMP>fname</SAMP>. </P>
<P>Otherwise, if <SAMP>(fname == 0)</SAMP> evaluates to <SAMP>true</SAMP>, attempts to create a temporary file with a unique name (obtained, for example, by a call to <SAMP>std::tmpnam()</SAMP> or a similar function. ) The temporary file will be deleted on the first call to <SAMP>close()</SAMP> on the object or when the last file descriptor referring to the file is closed, whichever occurs last. Note that the file will be deleted by the operating system even if the program exits abnormally.</P>
</UL>
<BLOCKQUOTE><HR><B>
NOTE -- The behavior of the function when <SAMP>(fname == 0)</SAMP> evaluates to true is not required by the C++ Standard, but is provided as an extension of this implementation. See <A HREF="B.html">Appendix&nbsp;B</A> for a complete list of extensions of this implementation.
</B><HR></BLOCKQUOTE>
<UL>
<P>The file open modes are given by their C-equivalent descriptions (see the C function <SAMP>fopen()</SAMP>). They are:</P>
<UL><PRE>in "r"
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"
</PRE></UL>
<P>If <SAMP>open()</SAMP> succeeds and <SAMP>(mode &amp; ios_base::ate) != 0</SAMP>, it positions the file to the end, like a call to <SAMP>std::fseek(file, 0, SEEK_END))</SAMP>. If the <SAMP>open()</SAMP> function fails, it returns a null pointer.</P>
<P>The third argument, <SAMP>protection</SAMP>, is used as the file permission. The <SAMP>protection</SAMP> argument determines the read/write/execute file permissions under UNIX. It is more limited under DOS, since files are always readable and do not have special execute permission. </P>
</UL>
<BLOCKQUOTE><HR><B>
NOTE -- The protection argument does not appear in the C++ Standard, but is included here as an extension. See <A HREF="B.html">Appendix&nbsp;B</A> for a complete list of extensions of this implementation.
</B><HR></BLOCKQUOTE>
<A NAME="idx56"></A><PRE>basic_filebuf&lt;charT,traits&gt;*
<B>open</B>(int fd, char_type *buf = 0,
streamsize n = /* default size */);</PRE>
<UL>
<P>Attaches the previously opened file, which is identified by its file descriptor, <SAMP>fd</SAMP>, to the <B><I>basic_filebuf</I></B> object. </P>
</UL>
<BLOCKQUOTE><HR><B>
NOTE -- This function is not part of the C++ Standard, but is included here as an extension in order to manipulate pipes, sockets, or other UNIX devices that can be accessed through file descriptors. See <A HREF="B.html">Appendix&nbsp;B</A> for a complete list of extensions of this implementation.
</B><HR></BLOCKQUOTE>
<A NAME="idx57"></A><PRE>basic_filebuf&lt;charT,traits&gt;*
<B>open</B>(FILE *fp, char_type *buf = 0,
streamsize n = /* default size */);</PRE>
<UL>
<P>Returns <SAMP>open(fileno (fp), buf, n)</SAMP>, where <SAMP>fileno</SAMP> is a UNIX98 function declared in <SAMP>&lt;cstdio&gt;</SAMP>. </P>
</UL>
<BLOCKQUOTE><HR><B>
NOTE -- This function is not part of the C++ Standard, but is provided as a convenience extension. See <A HREF="B.html">Appendix&nbsp;B</A> for a complete list of extensions of this implementation.
</B><HR></BLOCKQUOTE>
<A NAME="idx58"></A><PRE>int_type
<B>overflow</B>(int_type c = traits_type::eof()); </PRE>
<UL>
<P>If the output sequence has a <SAMP>put</SAMP> position available, and <SAMP>c</SAMP> is not<SAMP> traits_type::eof()</SAMP>, then writes <SAMP>c</SAMP> into it. If there is no position available, the function outputs the contents of the buffer to the associated file and writes <SAMP>c</SAMP> at the new current <SAMP>put</SAMP> position. If the operation fails, the function returns <SAMP>traits_type</SAMP><SAMP>::eof()</SAMP>; otherwise, it returns <SAMP>traits_type</SAMP><SAMP>::not_eof(c)</SAMP>. In a wide character file buffer, <SAMP>overflow()</SAMP> may convert the internal wide characters to their external multibyte representation by using the <SAMP>locale::codecvt</SAMP> facet located in the <B><I><A HREF="locale.html">locale</A></I></B> object imbued in the stream buffer. </P>
</UL>
<A NAME="idx59"></A><PRE>int_type
<B>pbackfail</B>(int_type c = traits_type::eof()); </PRE>
<UL>
<P>Puts back the character designated by <SAMP>c</SAMP> into the input sequence. If <SAMP>traits_type::eq_int_type(c,traits_type::eof())</SAMP> returns <SAMP>true</SAMP>, moves the input sequence one position backward. If the operation fails, the function returns <SAMP>traits_type::eof()</SAMP>. Otherwise, it returns <SAMP>traits::not_eof(c)</SAMP>.</P>
</UL>
<A NAME="idx60"></A><PRE>pos_type
<B>seekoff</B>(off_type off, ios_base::seekdir way,
ios_base::openmode which = ios_base::in |
ios_base::out); </PRE>
<UL>
<P>If the open mode is <SAMP>in|out</SAMP>, may alter the stream position of the input and the output sequence as follows: </P>
</UL>
<UL>
<LI><P CLASS="LIST">If the open mode is <SAMP>in</SAMP>, may alter the stream position of only the input sequence </P></LI>
<LI><P CLASS="LIST">If the open mode is <SAMP>out</SAMP>, may alter the stream position of only the output sequence </P></LI>
</UL>
<UL>
<P>The new position is calculated by combining the two parameters <SAMP>off</SAMP>&nbsp;(displacement) and <SAMP>way</SAMP> (reference point). Note the following cases:</P>
</UL>
<UL>
<LI><P CLASS="LIST">If the current position of the sequence is invalid before repositioning, the operation fails and the return value is: </P></LI>
<P CLASS="LIST"><SAMP>pos_type(off_type(-1))</SAMP></P>
<LI><P CLASS="LIST">If <SAMP>way != basic_ios::cur</SAMP> or <SAMP>off != 0</SAMP>, and the last operation was output, the function updates the output sequence and writes any unshift sequence. It then repositions the file, like a call to <SAMP>std::fseek(file, 0, whence)</SAMP>, and returns the current new position. </P></LI>
</UL>
<P>File buffers that use the <SAMP>locale::codecvt</SAMP> facet, and perform state dependent conversion, support seeking only 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.</P>
<A NAME="idx61"></A><PRE>
pos_type
<B>seekpos</B>(pos_type sp,ios_base::openmode
which = ios_base::in | ios_base::out); </PRE>
<UL>
<P>If the open mode is <SAMP>in|out</SAMP>, alters the stream position of both the input and the output sequence. If the open mode is <SAMP>in</SAMP>, alters the stream position of only the input sequence, and if it is <SAMP>out</SAMP>, 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 <SAMP>pos_type(off_type(-1))</SAMP>. Otherwise, the function returns the current new position. File buffers using <SAMP>locale::codecvt</SAMP> facet performing state dependent conversion <I>only </I>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.</P>
</UL>
<A NAME="idx62"></A><PRE>basic_filebuf&lt;charT,traits&gt;*
<B>setbuf</B>(char_type *s, streamsize n); </PRE>
<UL>
<P>The function first flushes the contents of the <SAMP>put</SAMP> area into the associated file, if necessary. Then:</P>
</UL>
<UL>
<LI><P CLASS="LIST">If both <SAMP>s</SAMP> and <SAMP>n</SAMP> are <SAMP>0</SAMP>, the function places the object in an unbuffered mode, that is, <SAMP>pbase()</SAMP> and <SAMP>pptr()</SAMP> always return null and output to the file appears immediately. </P></LI>
<LI><P CLASS="LIST">If <SAMP>s</SAMP> is null and <SAMP>n</SAMP> is nonzero, the function allocates an internal character buffer of size <SAMP>n</SAMP> and takes ownership of the buffer. </P></LI>
<LI><P CLASS="LIST">If <SAMP>s</SAMP> is non-null and <SAMP>n</SAMP> is nonzero, the function uses the provided buffer in place of its internal buffer. The caller is responsible for deallocating the provided buffer, or the function fails. </P></LI>
</UL>
<UL>
<P>The function returns <SAMP>this</SAMP> on success and <SAMP>0</SAMP> on failure.</P>
</UL>
<A NAME="idx63"></A><PRE>int
<B>sync</B>();</PRE>
<UL>
<P>Synchronizes the contents of the external file, with its image maintained in memory by the file buffer. This is useful, for instance, when two threads of execution simultaneously manipulate the same file. If the function fails, it returns <SAMP>-1</SAMP>; otherwise, it returns <SAMP>0</SAMP>.</P>
</UL>
<A NAME="idx64"></A><PRE>int_type
<B>underflow</B>();</PRE>
<UL>
<P>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 <SAMP>traits_type::eof()</SAMP> to indicate failure. In wide characters file buffer, <SAMP>underflow</SAMP> may convert the external multibytes characters to their wide character representation by using the <SAMP>locale::codecvt</SAMP> facet located in the <B><I><A HREF="locale.html">locale</A></I></B> object imbued in the stream buffer. </P>
</UL>
<A NAME="idx65"></A><PRE>streamsize
<B>xsputn</B>(const char_type* s, streamsize n); </PRE>
<UL>
<P>Writes up to <SAMP>n</SAMP> characters to the output sequence. The characters written are obtained from successive elements of the array whose first element is designated by <SAMP>s</SAMP>. The function returns the number of characters written.</P>
</UL>
<A NAME="sec11"><H3>Example</H3></A>
<UL><PRE>//
// filebuf.cpp
//
#include &lt;iostream&gt; // for cout, endl
#include &lt;fstream&gt; // for ifstream, ofstream
#include &lt;stdio.h&gt; // for tmpnam, remove
int main ( )
{
char filebuf [L_tmpnam];
// create a temporary filename
const char *fname = tmpnam (filebuf);
if (!fname)
return 1;
// create a read/write file-stream object on tiny char
// and attach it to the file "filebuf.out"
std::ofstream out (fname, std::ios::in | std::ios::out |
std::ios::trunc);
// tie the istream object to the ofstream object
std::istream in (out.rdbuf ());
// output to out
out &lt;&lt; "Il errait comme un ame en peine";
// seek to the beginning of the file
in.seekg (0);
// output in to the standard output
std::cout &lt;&lt; in.rdbuf () &lt;&lt; std::endl;
// close the file
out.close ();
// open the existing temporary file and truncate it
out.open (fname, std::ios::in | std::ios::out |
std::ios::trunc);
// set the buffer size
// buffer will be allocated internally
// and deallocated in dtor
out.rdbuf ()-&gt;pubsetbuf (0, 4096);
// open this source code file
std::ifstream ins (__FILE__);
// output it to temporary file
out &lt;&lt; ins.rdbuf ();
// seek to the beginning of the file
out.seekp (0);
// output the all file
std::cout &lt;&lt; out.rdbuf ();
// remove temporary file
remove (fname);
return 0;
}
Program Output:
Il errait comme un ame en peine
//
// filebuf.cpp
//
#include &lt;iostream&gt; // for cout, endl
#include &lt;fstream&gt; // for ifstream, ofstream
#include &lt;stdio.h&gt; // for tmpnam, remove
int main ( )
{
char filebuf [L_tmpnam];
// create a temporary filename
const char *fname = tmpnam (filebuf);
if (!fname)
return 1;
// create a read/write file-stream object on tiny char
// and attach it to the file "filebuf.out"
std::ofstream out (fname, std::ios::in | std::ios::out |
std::ios::trunc);
// tie the istream object to the ofstream object
std::istream in (out.rdbuf ());
// output to out
out &lt;&lt; "Il errait comme un ame en peine";
// seek to the beginning of the file
in.seekg (0);
// output in to the standard output
std::cout &lt;&lt; in.rdbuf () &lt;&lt; std::endl;
// close the file
out.close ();
// open the existing temporary file and truncate it
out.open (fname, std::ios::in | std::ios::out |
std::ios::trunc);
// set the buffer size
// buffer will be allocated internally
// and deallocated in dtor
out.rdbuf ()-&gt;pubsetbuf (0, 4096);
// open this source code file
std::ifstream ins (__FILE__);
// output it to temporary file
out &lt;&lt; ins.rdbuf ();
// seek to the beginning of the file
out.seekp (0);
// output the all file
std::cout &lt;&lt; out.rdbuf ();
// remove temporary file
remove (fname);
return 0;
}
</PRE></UL>
<UL><PRE></PRE></UL>
<A NAME="sec12"><H3>See Also</H3></A>
<P><B><I><A HREF="char-traits.html">char_traits</A></I></B>, <B><I><A HREF="ios-base.html">ios_base</A></I></B>, <B><I><A HREF="basic-ios.html">basic_ios</A></I></B>, <B><I><A HREF="basic-streambuf.html">basic_streambuf</A></I></B>, <B><I><A HREF="basic-ifstream.html">basic_ifstream</A></I></B>, <B><I><A HREF="basic-ofstream.html">basic_ofstream</A></I></B>, <B><I><A HREF="basic-fstream.html">basic_fstream</A></I></B></P>
<A NAME="sec13"><H3>Standards Conformance</H3></A>
<P><I>ISO/IEC 14882:1998 -- International Standard for Information Systems --Programming Language C++, Section 27.8.1.1</I></P>
<BR>
<HR>
<A HREF="bad-typeid.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="basic-fstream.html"><IMG SRC="images/bnext.gif" WIDTH=20 HEIGHT=21 ALT="Next file" BORDER=O></A>
<!-- Google Analytics tracking code -->
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1775151-1";
urchinTracker();
</script>
<!-- end of Google Analytics tracking code -->
</BODY>
</HTML>