libstdc++-v3/doc/html/manual/streambufs.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Stream Buffers</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io.html" title="Chapter 13.  Input and Output" /><link rel="prev" href="io.html" title="Chapter 13.  Input and Output" /><link rel="next" href="stringstreams.html" title="Memory Based Streams" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Stream Buffers</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="io.html">Prev</a> </td><th width="60%" align="center">Chapter 13.
   4   Input and Output
   5
   6 </th><td width="20%" align="right"> <a accesskey="n" href="stringstreams.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Stream Buffers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.io.streambufs"></a>Stream Buffers</h2></div></div></div><div class="sect2" title="Derived streambuf Classes"><div class="titlepage"><div><div><h3 class="title"><a id="io.streambuf.derived"></a>Derived streambuf Classes</h3></div></div></div><p>
   7     </p><p>Creating your own stream buffers for I/O can be remarkably easy.
   8       If you are interested in doing so, we highly recommend two very
   9       excellent books:
  10       <a class="ulink" href="http://www.angelikalanger.com/iostreams.html" target="_top">Standard C++
  11       IOStreams and Locales</a> by Langer and Kreft, ISBN 0-201-18395-1, and
  12       <a class="ulink" href="http://www.josuttis.com/libbook/" target="_top">The C++ Standard Library</a>
  13       by Nicolai Josuttis, ISBN 0-201-37926-0.  Both are published by
  14       Addison-Wesley, who isn't paying us a cent for saying that, honest.
  15    </p><p>Here is a simple example, io/outbuf1, from the Josuttis text.  It
  16       transforms everything sent through it to uppercase.  This version
  17       assumes many things about the nature of the character type being
  18       used (for more information, read the books or the newsgroups):
  19    </p><pre class="programlisting">
  20     #include &lt;iostream&gt;
  21     #include &lt;streambuf&gt;
  22     #include &lt;locale&gt;
  23     #include &lt;cstdio&gt;
  24
  25     class outbuf : public std::streambuf
  26     {
  27       protected:
  28         /* central output function
  29          * - print characters in uppercase mode
  30          */
  31         virtual int_type overflow (int_type c) {
  32             if (c != EOF) {
  33                 // convert lowercase to uppercase
  34                 c = std::toupper(static_cast&lt;char&gt;(c),getloc());
  35
  36                 // and write the character to the standard output
  37                 if (putchar(c) == EOF) {
  38                     return EOF;
  39                 }
  40             }
  41             return c;
  42         }
  43     };
  44
  45     int main()
  46     {
  47         // create special output buffer
  48         outbuf ob;
  49         // initialize output stream with that output buffer
  50         std::ostream out(&amp;ob);
  51
  52         out &lt;&lt; "31 hexadecimal: "
  53             &lt;&lt; std::hex &lt;&lt; 31 &lt;&lt; std::endl;
  54         return 0;
  55     }
  56    </pre><p>Try it yourself!  More examples can be found in 3.1.x code, in
  57       <code class="code">include/ext/*_filebuf.h</code>, and in this article by James Kanze:
  58       <a class="ulink" href="http://kanze.james.neuf.fr/articles/fltrsbf1.html" target="_top">Filtering
  59       Streambufs</a>.
  60    </p></div><div class="sect2" title="Buffering"><div class="titlepage"><div><div><h3 class="title"><a id="io.streambuf.buffering"></a>Buffering</h3></div></div></div><p>First, are you sure that you understand buffering?  Chaptericularly
  61       the fact that C++ may not, in fact, have anything to do with it?
  62    </p><p>The rules for buffering can be a little odd, but they aren't any
  63       different from those of C.  (Maybe that's why they can be a bit
  64       odd.)  Many people think that writing a newline to an output
  65       stream automatically flushes the output buffer.  This is true only
  66       when the output stream is, in fact, a terminal and not a file
  67       or some other device -- and <span class="emphasis"><em>that</em></span> may not even be true
  68       since C++ says nothing about files nor terminals.  All of that is
  69       system-dependent.  (The "newline-buffer-flushing only occurring
  70       on terminals" thing is mostly true on Unix systems, though.)
  71    </p><p>Some people also believe that sending <code class="code">endl</code> down an
  72       output stream only writes a newline.  This is incorrect; after a
  73       newline is written, the buffer is also flushed.  Perhaps this
  74       is the effect you want when writing to a screen -- get the text
  75       out as soon as possible, etc -- but the buffering is largely
  76       wasted when doing this to a file:
  77    </p><pre class="programlisting">
  78    output &lt;&lt; "a line of text" &lt;&lt; endl;
  79    output &lt;&lt; some_data_variable &lt;&lt; endl;
  80    output &lt;&lt; "another line of text" &lt;&lt; endl; </pre><p>The proper thing to do in this case to just write the data out
  81       and let the libraries and the system worry about the buffering.
  82       If you need a newline, just write a newline:
  83    </p><pre class="programlisting">
  84    output &lt;&lt; "a line of text\n"
  85           &lt;&lt; some_data_variable &lt;&lt; '\n'
  86           &lt;&lt; "another line of text\n"; </pre><p>I have also joined the output statements into a single statement.
  87       You could make the code prettier by moving the single newline to
  88       the start of the quoted text on the last line, for example.
  89    </p><p>If you do need to flush the buffer above, you can send an
  90       <code class="code">endl</code> if you also need a newline, or just flush the buffer
  91       yourself:
  92    </p><pre class="programlisting">
  93    output &lt;&lt; ...... &lt;&lt; flush;    // can use std::flush manipulator
  94    output.flush();               // or call a member fn </pre><p>On the other hand, there are times when writing to a file should
  95       be like writing to standard error; no buffering should be done
  96       because the data needs to appear quickly (a prime example is a
  97       log file for security-related information).  The way to do this is
  98       just to turn off the buffering <span class="emphasis"><em>before any I/O operations at
  99       all</em></span> have been done (note that opening counts as an I/O operation):
 100    </p><pre class="programlisting">
 101    std::ofstream    os;
 102    std::ifstream    is;
 103    int   i;
 104
 105    os.rdbuf()-&gt;pubsetbuf(0,0);
 106    is.rdbuf()-&gt;pubsetbuf(0,0);
 107
 108    os.open("/foo/bar/baz");
 109    is.open("/qux/quux/quuux");
 110    ...
 111    os &lt;&lt; "this data is written immediately\n";
 112    is &gt;&gt; i;   // and this will probably cause a disk read </pre><p>Since all aspects of buffering are handled by a streambuf-derived
 113       member, it is necessary to get at that member with <code class="code">rdbuf()</code>.
 114       Then the public version of <code class="code">setbuf</code> can be called.  The
 115       arguments are the same as those for the Standard C I/O Library
 116       function (a buffer area followed by its size).
 117    </p><p>A great deal of this is implementation-dependent.  For example,
 118       <code class="code">streambuf</code> does not specify any actions for its own
 119       <code class="code">setbuf()</code>-ish functions; the classes derived from
 120       <code class="code">streambuf</code> each define behavior that "makes
 121       sense" for that class:  an argument of (0,0) turns off buffering
 122       for <code class="code">filebuf</code> but does nothing at all for its siblings
 123       <code class="code">stringbuf</code> and <code class="code">strstreambuf</code>, and specifying
 124       anything other than (0,0) has varying effects.
 125       User-defined classes derived from <code class="code">streambuf</code> can
 126       do whatever they want.  (For <code class="code">filebuf</code> and arguments for
 127       <code class="code">(p,s)</code> other than zeros, libstdc++ does what you'd expect:
 128       the first <code class="code">s</code> bytes of <code class="code">p</code> are used as a buffer,
 129       which you must allocate and deallocate.)
 130    </p><p>A last reminder:  there are usually more buffers involved than
 131       just those at the language/library level.  Kernel buffers, disk
 132       buffers, and the like will also have an effect.  Inspecting and
 133       changing those are system-dependent.
 134    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="io.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="io.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="stringstreams.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 13.
 135   Input and Output
 136
 137  </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Memory Based Streams</td></tr></table></div></body></html>