libstdc++-v3/doc/html/manual/fstreams.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>File Based Streams</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="stringstreams.html" title="Memory Based Streams" /><link rel="next" href="io_and_c.html" title="Interacting with C" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">File Based Streams</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="stringstreams.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="io_and_c.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="File Based Streams"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.io.filestreams"></a>File Based Streams</h2></div></div></div><div class="sect2" title="Copying a File"><div class="titlepage"><div><div><h3 class="title"><a id="std.io.filestreams.copying_a_file"></a>Copying a File</h3></div></div></div><p>
   7   </p><p>So you want to copy a file quickly and easily, and most important,
   8       completely portably.  And since this is C++, you have an open
   9       ifstream (call it IN) and an open ofstream (call it OUT):
  10    </p><pre class="programlisting">
  11    #include &lt;fstream&gt;
  12
  13    std::ifstream  IN ("input_file");
  14    std::ofstream  OUT ("output_file"); </pre><p>Here's the easiest way to get it completely wrong:
  15    </p><pre class="programlisting">
  16    OUT &lt;&lt; IN;</pre><p>For those of you who don't already know why this doesn't work
  17       (probably from having done it before), I invite you to quickly
  18       create a simple text file called "input_file" containing
  19       the sentence
  20    </p><pre class="programlisting">
  21       The quick brown fox jumped over the lazy dog.</pre><p>surrounded by blank lines.  Code it up and try it.  The contents
  22       of "output_file" may surprise you.
  23    </p><p>Seriously, go do it.  Get surprised, then come back.  It's worth it.
  24    </p><p>The thing to remember is that the <code class="code">basic_[io]stream</code> classes
  25       handle formatting, nothing else.  In chaptericular, they break up on
  26       whitespace.  The actual reading, writing, and storing of data is
  27       handled by the <code class="code">basic_streambuf</code> family.  Fortunately, the
  28       <code class="code">operator&lt;&lt;</code> is overloaded to take an ostream and
  29       a pointer-to-streambuf, in order to help with just this kind of
  30       "dump the data verbatim" situation.
  31    </p><p>Why a <span class="emphasis"><em>pointer</em></span> to streambuf and not just a streambuf?  Well,
  32       the [io]streams hold pointers (or references, depending on the
  33       implementation) to their buffers, not the actual
  34       buffers.  This allows polymorphic behavior on the chapter of the buffers
  35       as well as the streams themselves.  The pointer is easily retrieved
  36       using the <code class="code">rdbuf()</code> member function.  Therefore, the easiest
  37       way to copy the file is:
  38    </p><pre class="programlisting">
  39    OUT &lt;&lt; IN.rdbuf();</pre><p>So what <span class="emphasis"><em>was</em></span> happening with OUT&lt;&lt;IN?  Undefined
  40       behavior, since that chaptericular &lt;&lt; isn't defined by the Standard.
  41       I have seen instances where it is implemented, but the character
  42       extraction process removes all the whitespace, leaving you with no
  43       blank lines and only "Thequickbrownfox...".  With
  44       libraries that do not define that operator, IN (or one of IN's
  45       member pointers) sometimes gets converted to a void*, and the output
  46       file then contains a perfect text representation of a hexadecimal
  47       address (quite a big surprise).  Others don't compile at all.
  48    </p><p>Also note that none of this is specific to o<span class="emphasis"><em>*f*</em></span>streams.
  49       The operators shown above are all defined in the parent
  50       basic_ostream class and are therefore available with all possible
  51       descendants.
  52    </p></div><div class="sect2" title="Binary Input and Output"><div class="titlepage"><div><div><h3 class="title"><a id="std.io.filestreams.binary"></a>Binary Input and Output</h3></div></div></div><p>
  53     </p><p>The first and most important thing to remember about binary I/O is
  54       that opening a file with <code class="code">ios::binary</code> is not, repeat
  55       <span class="emphasis"><em>not</em></span>, the only thing you have to do.  It is not a silver
  56       bullet, and will not allow you to use the <code class="code">&lt;&lt;/&gt;&gt;</code>
  57       operators of the normal fstreams to do binary I/O.
  58    </p><p>Sorry.  Them's the breaks.
  59    </p><p>This isn't going to try and be a complete tutorial on reading and
  60       writing binary files (because "binary"
  61       covers a lot of ground), but we will try and clear
  62       up a couple of misconceptions and common errors.
  63    </p><p>First, <code class="code">ios::binary</code> has exactly one defined effect, no more
  64       and no less.  Normal text mode has to be concerned with the newline
  65       characters, and the runtime system will translate between (for
  66       example) '\n' and the appropriate end-of-line sequence (LF on Unix,
  67       CRLF on DOS, CR on Macintosh, etc).  (There are other things that
  68       normal mode does, but that's the most obvious.)  Opening a file in
  69       binary mode disables this conversion, so reading a CRLF sequence
  70       under Windows won't accidentally get mapped to a '\n' character, etc.
  71       Binary mode is not supposed to suddenly give you a bitstream, and
  72       if it is doing so in your program then you've discovered a bug in
  73       your vendor's compiler (or some other chapter of the C++ implementation,
  74       possibly the runtime system).
  75    </p><p>Second, using <code class="code">&lt;&lt;</code> to write and <code class="code">&gt;&gt;</code> to
  76       read isn't going to work with the standard file stream classes, even
  77       if you use <code class="code">skipws</code> during reading.  Why not?  Because
  78       ifstream and ofstream exist for the purpose of <span class="emphasis"><em>formatting</em></span>,
  79       not reading and writing.  Their job is to interpret the data into
  80       text characters, and that's exactly what you don't want to happen
  81       during binary I/O.
  82    </p><p>Third, using the <code class="code">get()</code> and <code class="code">put()/write()</code> member
  83       functions still aren't guaranteed to help you.  These are
  84       "unformatted" I/O functions, but still character-based.
  85       (This may or may not be what you want, see below.)
  86    </p><p>Notice how all the problems here are due to the inappropriate use
  87       of <span class="emphasis"><em>formatting</em></span> functions and classes to perform something
  88       which <span class="emphasis"><em>requires</em></span> that formatting not be done?  There are a
  89       seemingly infinite number of solutions, and a few are listed here:
  90    </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="quote">“<span class="quote">Derive your own fstream-type classes and write your own
  91           &lt;&lt;/&gt;&gt; operators to do binary I/O on whatever data
  92           types you're using.</span>”</span>
  93         </p><p>
  94           This is a Bad Thing, because while
  95           the compiler would probably be just fine with it, other humans
  96           are going to be confused.  The overloaded bitshift operators
  97           have a well-defined meaning (formatting), and this breaks it.
  98         </p></li><li class="listitem"><p>
  99           <span class="quote">“<span class="quote">Build the file structure in memory, then
 100           <code class="code">mmap()</code> the file and copy the
 101           structure.
 102         </span>”</span>
 103         </p><p>
 104           Well, this is easy to make work, and easy to break, and is
 105           pretty equivalent to using <code class="code">::read()</code> and
 106           <code class="code">::write()</code> directly, and makes no use of the
 107           iostream library at all...
 108           </p></li><li class="listitem"><p>
 109           <span class="quote">“<span class="quote">Use streambufs, that's what they're there for.</span>”</span>
 110         </p><p>
 111           While not trivial for the beginner, this is the best of all
 112           solutions.  The streambuf/filebuf layer is the layer that is
 113           responsible for actual I/O.  If you want to use the C++
 114           library for binary I/O, this is where you start.
 115         </p></li></ul></div><p>How to go about using streambufs is a bit beyond the scope of this
 116       document (at least for now), but while streambufs go a long way,
 117       they still leave a couple of things up to you, the programmer.
 118       As an example, byte ordering is completely between you and the
 119       operating system, and you have to handle it yourself.
 120    </p><p>Deriving a streambuf or filebuf
 121       class from the standard ones, one that is specific to your data
 122       types (or an abstraction thereof) is probably a good idea, and
 123       lots of examples exist in journals and on Usenet.  Using the
 124       standard filebufs directly (either by declaring your own or by
 125       using the pointer returned from an fstream's <code class="code">rdbuf()</code>)
 126       is certainly feasible as well.
 127    </p><p>One area that causes problems is trying to do bit-by-bit operations
 128       with filebufs.  C++ is no different from C in this respect:  I/O
 129       must be done at the byte level.  If you're trying to read or write
 130       a few bits at a time, you're going about it the wrong way.  You
 131       must read/write an integral number of bytes and then process the
 132       bytes.  (For example, the streambuf functions take and return
 133       variables of type <code class="code">int_type</code>.)
 134    </p><p>Another area of problems is opening text files in binary mode.
 135       Generally, binary mode is intended for binary files, and opening
 136       text files in binary mode means that you now have to deal with all of
 137       those end-of-line and end-of-file problems that we mentioned before.
 138    </p><p>
 139       An instructive thread from comp.lang.c++.moderated delved off into
 140       this topic starting more or less at
 141       <a class="ulink" href="http://groups.google.com/group/comp.std.c++/browse_thread/thread/f87b4abd7954a87/946a3eb9921e382d?q=comp.std.c%2B%2B+binary+iostream#946a3eb9921e382d" target="_top">this</a>
 142       post and continuing to the end of the thread. (The subject heading is "binary iostreams" on both comp.std.c++
 143       and comp.lang.c++.moderated.) Take special note of the replies by James Kanze and Dietmar Kühl.
 144    </p><p>Briefly, the problems of byte ordering and type sizes mean that
 145       the unformatted functions like <code class="code">ostream::put()</code> and
 146       <code class="code">istream::get()</code> cannot safely be used to communicate
 147       between arbitrary programs, or across a network, or from one
 148       invocation of a program to another invocation of the same program
 149       on a different platform, etc.
 150    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="stringstreams.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="io_and_c.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Memory Based Streams </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Interacting with C</td></tr></table></div></body></html>