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

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