1 |
20 |
jlechner |
<?xml version="1.0" encoding="ISO-8859-1"?>
|
2 |
|
|
<!DOCTYPE html
|
3 |
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
4 |
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
5 |
|
|
|
6 |
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
7 |
|
|
<head>
|
8 |
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
9 |
|
|
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
|
10 |
|
|
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
|
11 |
|
|
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 27." />
|
12 |
|
|
<meta name="GENERATOR" content="vi and eight fingers" />
|
13 |
|
|
<title>libstdc++-v3 HOWTO: Chapter 27: Input/Output</title>
|
14 |
|
|
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
|
15 |
|
|
<link rel="Start" href="../documentation.html" type="text/html"
|
16 |
|
|
title="GNU C++ Standard Library" />
|
17 |
|
|
<link rel="Prev" href="../26_numerics/howto.html" type="text/html"
|
18 |
|
|
title="Numerics" />
|
19 |
|
|
<link rel="Next" href="../ext/howto.html" type="text/html"
|
20 |
|
|
title="Extensions" />
|
21 |
|
|
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
|
22 |
|
|
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
|
23 |
|
|
</head>
|
24 |
|
|
<body>
|
25 |
|
|
|
26 |
|
|
<h1 class="centered"><a name="top">Chapter 27: Input/Output</a></h1>
|
27 |
|
|
|
28 |
|
|
<p>Chapter 27 deals with iostreams and all their subcomponents
|
29 |
|
|
and extensions. All <em>kinds</em> of fun stuff.
|
30 |
|
|
</p>
|
31 |
|
|
|
32 |
|
|
|
33 |
|
|
<!-- ####################################################### -->
|
34 |
|
|
<hr />
|
35 |
|
|
<h1>Contents</h1>
|
36 |
|
|
<ul>
|
37 |
|
|
<li><a href="#1">Copying a file</a></li>
|
38 |
|
|
<li><a href="#2">The buffering is screwing up my program!</a></li>
|
39 |
|
|
<li><a href="#3">Binary I/O</a></li>
|
40 |
|
|
<li><a href="#5">What is this <sstream>/stringstreams thing?</a></li>
|
41 |
|
|
<li><a href="#6">Deriving a stream buffer</a></li>
|
42 |
|
|
<li><a href="#7">More on binary I/O</a></li>
|
43 |
|
|
<li><a href="#8">Pathetic performance? Ditch C.</a></li>
|
44 |
|
|
<li><a href="#9">Threads and I/O</a></li>
|
45 |
|
|
<li><a href="#10">Which header?</a></li>
|
46 |
|
|
<li><a href="#11">Using FILE*s and file descriptors with IOStreams</a></li>
|
47 |
|
|
</ul>
|
48 |
|
|
|
49 |
|
|
<hr />
|
50 |
|
|
|
51 |
|
|
<!-- ####################################################### -->
|
52 |
|
|
|
53 |
|
|
<h2><a name="1">Copying a file</a></h2>
|
54 |
|
|
<p>So you want to copy a file quickly and easily, and most important,
|
55 |
|
|
completely portably. And since this is C++, you have an open
|
56 |
|
|
ifstream (call it IN) and an open ofstream (call it OUT):
|
57 |
|
|
</p>
|
58 |
|
|
<pre>
|
59 |
|
|
#include <fstream>
|
60 |
|
|
|
61 |
|
|
std::ifstream IN ("input_file");
|
62 |
|
|
std::ofstream OUT ("output_file"); </pre>
|
63 |
|
|
<p>Here's the easiest way to get it completely wrong:
|
64 |
|
|
</p>
|
65 |
|
|
<pre>
|
66 |
|
|
OUT << IN;</pre>
|
67 |
|
|
<p>For those of you who don't already know why this doesn't work
|
68 |
|
|
(probably from having done it before), I invite you to quickly
|
69 |
|
|
create a simple text file called "input_file" containing
|
70 |
|
|
the sentence
|
71 |
|
|
</p>
|
72 |
|
|
<pre>
|
73 |
|
|
The quick brown fox jumped over the lazy dog.</pre>
|
74 |
|
|
<p>surrounded by blank lines. Code it up and try it. The contents
|
75 |
|
|
of "output_file" may surprise you.
|
76 |
|
|
</p>
|
77 |
|
|
<p>Seriously, go do it. Get surprised, then come back. It's worth it.
|
78 |
|
|
</p>
|
79 |
|
|
<hr width="60%" />
|
80 |
|
|
<p>The thing to remember is that the <code>basic_[io]stream</code> classes
|
81 |
|
|
handle formatting, nothing else. In particular, they break up on
|
82 |
|
|
whitespace. The actual reading, writing, and storing of data is
|
83 |
|
|
handled by the <code>basic_streambuf</code> family. Fortunately, the
|
84 |
|
|
<code>operator<<</code> is overloaded to take an ostream and
|
85 |
|
|
a pointer-to-streambuf, in order to help with just this kind of
|
86 |
|
|
"dump the data verbatim" situation.
|
87 |
|
|
</p>
|
88 |
|
|
<p>Why a <em>pointer</em> to streambuf and not just a streambuf? Well,
|
89 |
|
|
the [io]streams hold pointers (or references, depending on the
|
90 |
|
|
implementation) to their buffers, not the actual
|
91 |
|
|
buffers. This allows polymorphic behavior on the part of the buffers
|
92 |
|
|
as well as the streams themselves. The pointer is easily retrieved
|
93 |
|
|
using the <code>rdbuf()</code> member function. Therefore, the easiest
|
94 |
|
|
way to copy the file is:
|
95 |
|
|
</p>
|
96 |
|
|
<pre>
|
97 |
|
|
OUT << IN.rdbuf();</pre>
|
98 |
|
|
<p>So what <em>was</em> happening with OUT<<IN? Undefined
|
99 |
|
|
behavior, since that particular << isn't defined by the Standard.
|
100 |
|
|
I have seen instances where it is implemented, but the character
|
101 |
|
|
extraction process removes all the whitespace, leaving you with no
|
102 |
|
|
blank lines and only "Thequickbrownfox...". With
|
103 |
|
|
libraries that do not define that operator, IN (or one of IN's
|
104 |
|
|
member pointers) sometimes gets converted to a void*, and the output
|
105 |
|
|
file then contains a perfect text representation of a hexidecimal
|
106 |
|
|
address (quite a big surprise). Others don't compile at all.
|
107 |
|
|
</p>
|
108 |
|
|
<p>Also note that none of this is specific to o<b>*f*</b>streams.
|
109 |
|
|
The operators shown above are all defined in the parent
|
110 |
|
|
basic_ostream class and are therefore available with all possible
|
111 |
|
|
descendents.
|
112 |
|
|
</p>
|
113 |
|
|
<p>Return <a href="#top">to top of page</a> or
|
114 |
|
|
<a href="../faq/index.html">to the FAQ</a>.
|
115 |
|
|
</p>
|
116 |
|
|
|
117 |
|
|
<hr />
|
118 |
|
|
<h2><a name="2">The buffering is screwing up my program!</a></h2>
|
119 |
|
|
<!--
|
120 |
|
|
This is not written very well. I need to redo this section.
|
121 |
|
|
-->
|
122 |
|
|
<p>First, are you sure that you understand buffering? Particularly
|
123 |
|
|
the fact that C++ may not, in fact, have anything to do with it?
|
124 |
|
|
</p>
|
125 |
|
|
<p>The rules for buffering can be a little odd, but they aren't any
|
126 |
|
|
different from those of C. (Maybe that's why they can be a bit
|
127 |
|
|
odd.) Many people think that writing a newline to an output
|
128 |
|
|
stream automatically flushes the output buffer. This is true only
|
129 |
|
|
when the output stream is, in fact, a terminal and not a file
|
130 |
|
|
or some other device -- and <em>that</em> may not even be true
|
131 |
|
|
since C++ says nothing about files nor terminals. All of that is
|
132 |
|
|
system-dependent. (The "newline-buffer-flushing only occurring
|
133 |
|
|
on terminals" thing is mostly true on Unix systems, though.)
|
134 |
|
|
</p>
|
135 |
|
|
<p>Some people also believe that sending <code>endl</code> down an
|
136 |
|
|
output stream only writes a newline. This is incorrect; after a
|
137 |
|
|
newline is written, the buffer is also flushed. Perhaps this
|
138 |
|
|
is the effect you want when writing to a screen -- get the text
|
139 |
|
|
out as soon as possible, etc -- but the buffering is largely
|
140 |
|
|
wasted when doing this to a file:
|
141 |
|
|
</p>
|
142 |
|
|
<pre>
|
143 |
|
|
output << "a line of text" << endl;
|
144 |
|
|
output << some_data_variable << endl;
|
145 |
|
|
output << "another line of text" << endl; </pre>
|
146 |
|
|
<p>The proper thing to do in this case to just write the data out
|
147 |
|
|
and let the libraries and the system worry about the buffering.
|
148 |
|
|
If you need a newline, just write a newline:
|
149 |
|
|
</p>
|
150 |
|
|
<pre>
|
151 |
|
|
output << "a line of text\n"
|
152 |
|
|
<< some_data_variable << '\n'
|
153 |
|
|
<< "another line of text\n"; </pre>
|
154 |
|
|
<p>I have also joined the output statements into a single statement.
|
155 |
|
|
You could make the code prettier by moving the single newline to
|
156 |
|
|
the start of the quoted text on the last line, for example.
|
157 |
|
|
</p>
|
158 |
|
|
<p>If you do need to flush the buffer above, you can send an
|
159 |
|
|
<code>endl</code> if you also need a newline, or just flush the buffer
|
160 |
|
|
yourself:
|
161 |
|
|
</p>
|
162 |
|
|
<pre>
|
163 |
|
|
output << ...... << flush; // can use std::flush manipulator
|
164 |
|
|
output.flush(); // or call a member fn </pre>
|
165 |
|
|
<p>On the other hand, there are times when writing to a file should
|
166 |
|
|
be like writing to standard error; no buffering should be done
|
167 |
|
|
because the data needs to appear quickly (a prime example is a
|
168 |
|
|
log file for security-related information). The way to do this is
|
169 |
|
|
just to turn off the buffering <em>before any I/O operations at
|
170 |
|
|
all</em> have been done (note that opening counts as an I/O operation):
|
171 |
|
|
</p>
|
172 |
|
|
<pre>
|
173 |
|
|
std::ofstream os;
|
174 |
|
|
std::ifstream is;
|
175 |
|
|
int i;
|
176 |
|
|
|
177 |
|
|
os.rdbuf()->pubsetbuf(0,0);
|
178 |
|
|
is.rdbuf()->pubsetbuf(0,0);
|
179 |
|
|
|
180 |
|
|
os.open("/foo/bar/baz");
|
181 |
|
|
is.open("/qux/quux/quuux");
|
182 |
|
|
...
|
183 |
|
|
os << "this data is written immediately\n";
|
184 |
|
|
is >> i; // and this will probably cause a disk read </pre>
|
185 |
|
|
<p>Since all aspects of buffering are handled by a streambuf-derived
|
186 |
|
|
member, it is necessary to get at that member with <code>rdbuf()</code>.
|
187 |
|
|
Then the public version of <code>setbuf</code> can be called. The
|
188 |
|
|
arguments are the same as those for the Standard C I/O Library
|
189 |
|
|
function (a buffer area followed by its size).
|
190 |
|
|
</p>
|
191 |
|
|
<p>A great deal of this is implementation-dependent. For example,
|
192 |
|
|
<code>streambuf</code> does not specify any actions for its own
|
193 |
|
|
<code>setbuf()</code>-ish functions; the classes derived from
|
194 |
|
|
<code>streambuf</code> each define behavior that "makes
|
195 |
|
|
sense" for that class: an argument of (0,0) turns off buffering
|
196 |
|
|
for <code>filebuf</code> but does nothing at all for its siblings
|
197 |
|
|
<code>stringbuf</code> and <code>strstreambuf</code>, and specifying
|
198 |
|
|
anything other than (0,0) has varying effects.
|
199 |
|
|
User-defined classes derived from <code>streambuf</code> can
|
200 |
|
|
do whatever they want. (For <code>filebuf</code> and arguments for
|
201 |
|
|
<code>(p,s)</code> other than zeros, libstdc++ does what you'd expect:
|
202 |
|
|
the first <code>s</code> bytes of <code>p</code> are used as a buffer,
|
203 |
|
|
which you must allocate and deallocate.)
|
204 |
|
|
</p>
|
205 |
|
|
<p>A last reminder: there are usually more buffers involved than
|
206 |
|
|
just those at the language/library level. Kernel buffers, disk
|
207 |
|
|
buffers, and the like will also have an effect. Inspecting and
|
208 |
|
|
changing those are system-dependent.
|
209 |
|
|
</p>
|
210 |
|
|
<p>Return <a href="#top">to top of page</a> or
|
211 |
|
|
<a href="../faq/index.html">to the FAQ</a>.
|
212 |
|
|
</p>
|
213 |
|
|
|
214 |
|
|
<hr />
|
215 |
|
|
<h2><a name="3">Binary I/O</a></h2>
|
216 |
|
|
<p>The first and most important thing to remember about binary I/O is
|
217 |
|
|
that opening a file with <code>ios::binary</code> is not, repeat
|
218 |
|
|
<em>not</em>, the only thing you have to do. It is not a silver
|
219 |
|
|
bullet, and will not allow you to use the <code><</>></code>
|
220 |
|
|
operators of the normal fstreams to do binary I/O.
|
221 |
|
|
</p>
|
222 |
|
|
<p>Sorry. Them's the breaks.
|
223 |
|
|
</p>
|
224 |
|
|
<p>This isn't going to try and be a complete tutorial on reading and
|
225 |
|
|
writing binary files (because "binary"
|
226 |
|
|
<a href="#7">covers a lot of ground)</a>, but we will try and clear
|
227 |
|
|
up a couple of misconceptions and common errors.
|
228 |
|
|
</p>
|
229 |
|
|
<p>First, <code>ios::binary</code> has exactly one defined effect, no more
|
230 |
|
|
and no less. Normal text mode has to be concerned with the newline
|
231 |
|
|
characters, and the runtime system will translate between (for
|
232 |
|
|
example) '\n' and the appropriate end-of-line sequence (LF on Unix,
|
233 |
|
|
CRLF on DOS, CR on Macintosh, etc). (There are other things that
|
234 |
|
|
normal mode does, but that's the most obvious.) Opening a file in
|
235 |
|
|
binary mode disables this conversion, so reading a CRLF sequence
|
236 |
|
|
under Windows won't accidentally get mapped to a '\n' character, etc.
|
237 |
|
|
Binary mode is not supposed to suddenly give you a bitstream, and
|
238 |
|
|
if it is doing so in your program then you've discovered a bug in
|
239 |
|
|
your vendor's compiler (or some other part of the C++ implementation,
|
240 |
|
|
possibly the runtime system).
|
241 |
|
|
</p>
|
242 |
|
|
<p>Second, using <code><<</code> to write and <code>>></code> to
|
243 |
|
|
read isn't going to work with the standard file stream classes, even
|
244 |
|
|
if you use <code>skipws</code> during reading. Why not? Because
|
245 |
|
|
ifstream and ofstream exist for the purpose of <em>formatting</em>,
|
246 |
|
|
not reading and writing. Their job is to interpret the data into
|
247 |
|
|
text characters, and that's exactly what you don't want to happen
|
248 |
|
|
during binary I/O.
|
249 |
|
|
</p>
|
250 |
|
|
<p>Third, using the <code>get()</code> and <code>put()/write()</code> member
|
251 |
|
|
functions still aren't guaranteed to help you. These are
|
252 |
|
|
"unformatted" I/O functions, but still character-based.
|
253 |
|
|
(This may or may not be what you want, see below.)
|
254 |
|
|
</p>
|
255 |
|
|
<p>Notice how all the problems here are due to the inappropriate use
|
256 |
|
|
of <em>formatting</em> functions and classes to perform something
|
257 |
|
|
which <em>requires</em> that formatting not be done? There are a
|
258 |
|
|
seemingly infinite number of solutions, and a few are listed here:
|
259 |
|
|
</p>
|
260 |
|
|
<ul>
|
261 |
|
|
<li>"Derive your own fstream-type classes and write your own
|
262 |
|
|
<</>> operators to do binary I/O on whatever data
|
263 |
|
|
types you're using." This is a Bad Thing, because while
|
264 |
|
|
the compiler would probably be just fine with it, other humans
|
265 |
|
|
are going to be confused. The overloaded bitshift operators
|
266 |
|
|
have a well-defined meaning (formatting), and this breaks it.
|
267 |
|
|
</li>
|
268 |
|
|
<li>"Build the file structure in memory, then <code>mmap()</code>
|
269 |
|
|
the file and copy the structure." Well, this is easy to
|
270 |
|
|
make work, and easy to break, and is pretty equivalent to
|
271 |
|
|
using <code>::read()</code> and <code>::write()</code> directly, and
|
272 |
|
|
makes no use of the iostream library at all...
|
273 |
|
|
</li>
|
274 |
|
|
<li>"Use streambufs, that's what they're there for."
|
275 |
|
|
While not trivial for the beginner, this is the best of all
|
276 |
|
|
solutions. The streambuf/filebuf layer is the layer that is
|
277 |
|
|
responsible for actual I/O. If you want to use the C++
|
278 |
|
|
library for binary I/O, this is where you start.
|
279 |
|
|
</li>
|
280 |
|
|
</ul>
|
281 |
|
|
<p>How to go about using streambufs is a bit beyond the scope of this
|
282 |
|
|
document (at least for now), but while streambufs go a long way,
|
283 |
|
|
they still leave a couple of things up to you, the programmer.
|
284 |
|
|
As an example, byte ordering is completely between you and the
|
285 |
|
|
operating system, and you have to handle it yourself.
|
286 |
|
|
</p>
|
287 |
|
|
<p>Deriving a streambuf or filebuf
|
288 |
|
|
class from the standard ones, one that is specific to your data
|
289 |
|
|
types (or an abstraction thereof) is probably a good idea, and
|
290 |
|
|
lots of examples exist in journals and on Usenet. Using the
|
291 |
|
|
standard filebufs directly (either by declaring your own or by
|
292 |
|
|
using the pointer returned from an fstream's <code>rdbuf()</code>)
|
293 |
|
|
is certainly feasible as well.
|
294 |
|
|
</p>
|
295 |
|
|
<p>One area that causes problems is trying to do bit-by-bit operations
|
296 |
|
|
with filebufs. C++ is no different from C in this respect: I/O
|
297 |
|
|
must be done at the byte level. If you're trying to read or write
|
298 |
|
|
a few bits at a time, you're going about it the wrong way. You
|
299 |
|
|
must read/write an integral number of bytes and then process the
|
300 |
|
|
bytes. (For example, the streambuf functions take and return
|
301 |
|
|
variables of type <code>int_type</code>.)
|
302 |
|
|
</p>
|
303 |
|
|
<p>Another area of problems is opening text files in binary mode.
|
304 |
|
|
Generally, binary mode is intended for binary files, and opening
|
305 |
|
|
text files in binary mode means that you now have to deal with all of
|
306 |
|
|
those end-of-line and end-of-file problems that we mentioned before.
|
307 |
|
|
An instructive thread from comp.lang.c++.moderated delved off into
|
308 |
|
|
this topic starting more or less at
|
309 |
|
|
<a href="http://groups.google.com/groups?oi=djq&selm=an_436187505">this</a>
|
310 |
|
|
article and continuing to the end of the thread. (You'll have to
|
311 |
|
|
sort through some flames every couple of paragraphs, but the points
|
312 |
|
|
made are good ones.)
|
313 |
|
|
</p>
|
314 |
|
|
|
315 |
|
|
<hr />
|
316 |
|
|
<h2><a name="5">What is this <sstream>/stringstreams thing?</a></h2>
|
317 |
|
|
<p>Stringstreams (defined in the header <code><sstream></code>)
|
318 |
|
|
are in this author's opinion one of the coolest things since
|
319 |
|
|
sliced time. An example of their use is in the Received Wisdom
|
320 |
|
|
section for Chapter 21 (Strings),
|
321 |
|
|
<a href="../21_strings/howto.html#1.1internal"> describing how to
|
322 |
|
|
format strings</a>.
|
323 |
|
|
</p>
|
324 |
|
|
<p>The quick definition is: they are siblings of ifstream and ofstream,
|
325 |
|
|
and they do for <code>std::string</code> what their siblings do for
|
326 |
|
|
files. All that work you put into writing <code><<</code> and
|
327 |
|
|
<code>>></code> functions for your classes now pays off
|
328 |
|
|
<em>again!</em> Need to format a string before passing the string
|
329 |
|
|
to a function? Send your stuff via <code><<</code> to an
|
330 |
|
|
ostringstream. You've read a string as input and need to parse it?
|
331 |
|
|
Initialize an istringstream with that string, and then pull pieces
|
332 |
|
|
out of it with <code>>></code>. Have a stringstream and need to
|
333 |
|
|
get a copy of the string inside? Just call the <code>str()</code>
|
334 |
|
|
member function.
|
335 |
|
|
</p>
|
336 |
|
|
<p>This only works if you've written your
|
337 |
|
|
<code><<</code>/<code>>></code> functions correctly, though,
|
338 |
|
|
and correctly means that they take istreams and ostreams as
|
339 |
|
|
parameters, not i<b>f</b>streams and o<b>f</b>streams. If they
|
340 |
|
|
take the latter, then your I/O operators will work fine with
|
341 |
|
|
file streams, but with nothing else -- including stringstreams.
|
342 |
|
|
</p>
|
343 |
|
|
<p>If you are a user of the strstream classes, you need to update
|
344 |
|
|
your code. You don't have to explicitly append <code>ends</code> to
|
345 |
|
|
terminate the C-style character array, you don't have to mess with
|
346 |
|
|
"freezing" functions, and you don't have to manage the
|
347 |
|
|
memory yourself. The strstreams have been officially deprecated,
|
348 |
|
|
which means that 1) future revisions of the C++ Standard won't
|
349 |
|
|
support them, and 2) if you use them, people will laugh at you.
|
350 |
|
|
</p>
|
351 |
|
|
|
352 |
|
|
<hr />
|
353 |
|
|
<h2><a name="6">Deriving a stream buffer</a></h2>
|
354 |
|
|
<p>Creating your own stream buffers for I/O can be remarkably easy.
|
355 |
|
|
If you are interested in doing so, we highly recommend two very
|
356 |
|
|
excellent books:
|
357 |
|
|
<a href="http://www.langer.camelot.de/iostreams.html">Standard C++
|
358 |
|
|
IOStreams and Locales</a> by Langer and Kreft, ISBN 0-201-18395-1, and
|
359 |
|
|
<a href="http://www.josuttis.com/libbook/">The C++ Standard Library</a>
|
360 |
|
|
by Nicolai Josuttis, ISBN 0-201-37926-0. Both are published by
|
361 |
|
|
Addison-Wesley, who isn't paying us a cent for saying that, honest.
|
362 |
|
|
</p>
|
363 |
|
|
<p>Here is a simple example, io/outbuf1, from the Josuttis text. It
|
364 |
|
|
transforms everything sent through it to uppercase. This version
|
365 |
|
|
assumes many things about the nature of the character type being
|
366 |
|
|
used (for more information, read the books or the newsgroups):
|
367 |
|
|
</p>
|
368 |
|
|
<pre>
|
369 |
|
|
#include <iostream>
|
370 |
|
|
#include <streambuf>
|
371 |
|
|
#include <locale>
|
372 |
|
|
#include <cstdio>
|
373 |
|
|
|
374 |
|
|
class outbuf : public std::streambuf
|
375 |
|
|
{
|
376 |
|
|
protected:
|
377 |
|
|
/* central output function
|
378 |
|
|
* - print characters in uppercase mode
|
379 |
|
|
*/
|
380 |
|
|
virtual int_type overflow (int_type c) {
|
381 |
|
|
if (c != EOF) {
|
382 |
|
|
// convert lowercase to uppercase
|
383 |
|
|
c = std::toupper(static_cast<char>(c),getloc());
|
384 |
|
|
|
385 |
|
|
// and write the character to the standard output
|
386 |
|
|
if (putchar(c) == EOF) {
|
387 |
|
|
return EOF;
|
388 |
|
|
}
|
389 |
|
|
}
|
390 |
|
|
return c;
|
391 |
|
|
}
|
392 |
|
|
};
|
393 |
|
|
|
394 |
|
|
int main()
|
395 |
|
|
{
|
396 |
|
|
// create special output buffer
|
397 |
|
|
outbuf ob;
|
398 |
|
|
// initialize output stream with that output buffer
|
399 |
|
|
std::ostream out(&ob);
|
400 |
|
|
|
401 |
|
|
out << "31 hexadecimal: "
|
402 |
|
|
<< std::hex << 31 << std::endl;
|
403 |
|
|
return 0;
|
404 |
|
|
}
|
405 |
|
|
</pre>
|
406 |
|
|
<p>Try it yourself! More examples can be found in 3.1.x code, in
|
407 |
|
|
<code>include/ext/*_filebuf.h</code>, and on
|
408 |
|
|
<a href="http://www.informatik.uni-konstanz.de/~kuehl/c++/iostream/">Dietmar
|
409 |
|
|
Kühl's IOStreams page</a>.
|
410 |
|
|
</p>
|
411 |
|
|
|
412 |
|
|
<hr />
|
413 |
|
|
<h2><a name="7">More on binary I/O</a></h2>
|
414 |
|
|
<p>Towards the beginning of February 2001, the subject of
|
415 |
|
|
"binary" I/O was brought up in a couple of places at the
|
416 |
|
|
same time. One notable place was Usenet, where James Kanze and
|
417 |
|
|
Dietmar Kühl separately posted articles on why attempting
|
418 |
|
|
generic binary I/O was not a good idea. (Here are copies of
|
419 |
|
|
<a href="binary_iostreams_kanze.txt">Kanze's article</a> and
|
420 |
|
|
<a href="binary_iostreams_kuehl.txt">Kühl's article</a>.)
|
421 |
|
|
</p>
|
422 |
|
|
<p>Briefly, the problems of byte ordering and type sizes mean that
|
423 |
|
|
the unformatted functions like <code>ostream::put()</code> and
|
424 |
|
|
<code>istream::get()</code> cannot safely be used to communicate
|
425 |
|
|
between arbitrary programs, or across a network, or from one
|
426 |
|
|
invocation of a program to another invocation of the same program
|
427 |
|
|
on a different platform, etc.
|
428 |
|
|
</p>
|
429 |
|
|
<p>The entire Usenet thread is instructive, and took place under the
|
430 |
|
|
subject heading "binary iostreams" on both comp.std.c++
|
431 |
|
|
and comp.lang.c++.moderated in parallel. Also in that thread,
|
432 |
|
|
Dietmar Kühl mentioned that he had written a pair of stream
|
433 |
|
|
classes that would read and write XDR, which is a good step towards
|
434 |
|
|
a portable binary format.
|
435 |
|
|
</p>
|
436 |
|
|
|
437 |
|
|
<hr />
|
438 |
|
|
<h2><a name="8">Pathetic performance? Ditch C.</a></h2>
|
439 |
|
|
<p>It sounds like a flame on C, but it isn't. Really. Calm down.
|
440 |
|
|
I'm just saying it to get your attention.
|
441 |
|
|
</p>
|
442 |
|
|
<p>Because the C++ library includes the C library, both C-style and
|
443 |
|
|
C++-style I/O have to work at the same time. For example:
|
444 |
|
|
</p>
|
445 |
|
|
<pre>
|
446 |
|
|
#include <iostream>
|
447 |
|
|
#include <cstdio>
|
448 |
|
|
|
449 |
|
|
std::cout << "Hel";
|
450 |
|
|
std::printf ("lo, worl");
|
451 |
|
|
std::cout << "d!\n";
|
452 |
|
|
</pre>
|
453 |
|
|
<p>This must do what you think it does.
|
454 |
|
|
</p>
|
455 |
|
|
<p>Alert members of the audience will immediately notice that buffering
|
456 |
|
|
is going to make a hash of the output unless special steps are taken.
|
457 |
|
|
</p>
|
458 |
|
|
<p>The special steps taken by libstdc++, at least for version 3.0,
|
459 |
|
|
involve doing very little buffering for the standard streams, leaving
|
460 |
|
|
most of the buffering to the underlying C library. (This kind of
|
461 |
|
|
thing is <a href="../explanations.html#cstdio">tricky to get right</a>.)
|
462 |
|
|
The upside is that correctness is ensured. The downside is that
|
463 |
|
|
writing through <code>cout</code> can quite easily lead to awful
|
464 |
|
|
performance when the C++ I/O library is layered on top of the C I/O
|
465 |
|
|
library (as it is for 3.0 by default). Some patches have been applied
|
466 |
|
|
which improve the situation for 3.1.
|
467 |
|
|
</p>
|
468 |
|
|
<p>However, the C and C++ standard streams only need to be kept in sync
|
469 |
|
|
when both libraries' facilities are in use. If your program only uses
|
470 |
|
|
C++ I/O, then there's no need to sync with the C streams. The right
|
471 |
|
|
thing to do in this case is to call
|
472 |
|
|
</p>
|
473 |
|
|
<pre>
|
474 |
|
|
#include <em>any of the I/O headers such as ios, iostream, etc</em>
|
475 |
|
|
|
476 |
|
|
std::ios::sync_with_stdio(false);
|
477 |
|
|
</pre>
|
478 |
|
|
<p>You must do this before performing any I/O via the C++ stream objects.
|
479 |
|
|
Once you call this, the C++ streams will operate independently of the
|
480 |
|
|
(unused) C streams. For GCC 3.x, this means that <code>cout</code> and
|
481 |
|
|
company will become fully buffered on their own.
|
482 |
|
|
</p>
|
483 |
|
|
<p>Note, by the way, that the synchronization requirement only applies to
|
484 |
|
|
the standard streams (<code>cin</code>, <code>cout</code>,
|
485 |
|
|
<code>cerr</code>,
|
486 |
|
|
<code>clog</code>, and their wide-character counterparts). File stream
|
487 |
|
|
objects that you declare yourself have no such requirement and are fully
|
488 |
|
|
buffered.
|
489 |
|
|
</p>
|
490 |
|
|
|
491 |
|
|
<hr />
|
492 |
|
|
<h2><a name="9">Threads and I/O</a></h2>
|
493 |
|
|
<p>I'll assume that you have already read the
|
494 |
|
|
<a href="../17_intro/howto.html#3">general notes on library threads</a>,
|
495 |
|
|
and the
|
496 |
|
|
<a href="../23_containers/howto.html#3">notes on threaded container
|
497 |
|
|
access</a> (you might not think of an I/O stream as a container, but
|
498 |
|
|
the points made there also hold here). If you have not read them,
|
499 |
|
|
please do so first.
|
500 |
|
|
</p>
|
501 |
|
|
<p>This gets a bit tricky. Please read carefully, and bear with me.
|
502 |
|
|
</p>
|
503 |
|
|
<h3>Structure</h3>
|
504 |
|
|
<p>As described <a href="../explanations.html#cstdio">here</a>, a wrapper
|
505 |
|
|
type called <code>__basic_file</code> provides our abstraction layer
|
506 |
|
|
for the <code>std::filebuf</code> classes. Nearly all decisions dealing
|
507 |
|
|
with actual input and output must be made in <code>__basic_file</code>.
|
508 |
|
|
</p>
|
509 |
|
|
<p>A generic locking mechanism is somewhat in place at the filebuf layer,
|
510 |
|
|
but is not used in the current code. Providing locking at any higher
|
511 |
|
|
level is akin to providing locking within containers, and is not done
|
512 |
|
|
for the same reasons (see the links above).
|
513 |
|
|
</p>
|
514 |
|
|
<h3>The defaults for 3.0.x</h3>
|
515 |
|
|
<p>The __basic_file type is simply a collection of small wrappers around
|
516 |
|
|
the C stdio layer (again, see the link under Structure). We do no
|
517 |
|
|
locking ourselves, but simply pass through to calls to <code>fopen</code>,
|
518 |
|
|
<code>fwrite</code>, and so forth.
|
519 |
|
|
</p>
|
520 |
|
|
<p>So, for 3.0, the question of "is multithreading safe for I/O"
|
521 |
|
|
must be answered with, "is your platform's C library threadsafe
|
522 |
|
|
for I/O?" Some are by default, some are not; many offer multiple
|
523 |
|
|
implementations of the C library with varying tradeoffs of threadsafety
|
524 |
|
|
and efficiency. You, the programmer, are always required to take care
|
525 |
|
|
with multiple threads.
|
526 |
|
|
</p>
|
527 |
|
|
<p>(As an example, the POSIX standard requires that C stdio FILE*
|
528 |
|
|
operations are atomic. POSIX-conforming C libraries (e.g, on Solaris
|
529 |
|
|
and GNU/Linux) have an internal mutex to serialize operations on
|
530 |
|
|
FILE*s. However, you still need to not do stupid things like calling
|
531 |
|
|
<code>fclose(fs)</code> in one thread followed by an access of
|
532 |
|
|
<code>fs</code> in another.)
|
533 |
|
|
</p>
|
534 |
|
|
<p>So, if your platform's C library is threadsafe, then your
|
535 |
|
|
<code>fstream</code> I/O operations will be threadsafe at the lowest
|
536 |
|
|
level. For higher-level operations, such as manipulating the data
|
537 |
|
|
contained in the stream formatting classes (e.g., setting up callbacks
|
538 |
|
|
inside an <code>std::ofstream</code>), you need to guard such accesses
|
539 |
|
|
like any other critical shared resource.
|
540 |
|
|
</p>
|
541 |
|
|
<h3>The future</h3>
|
542 |
|
|
<p>As already mentioned <a href="../explanations.html#cstdio">here</a>, a
|
543 |
|
|
second choice is available for I/O implementations: libio. This is
|
544 |
|
|
disabled by default, and in fact will not currently work due to other
|
545 |
|
|
issues. It will be revisited, however.
|
546 |
|
|
</p>
|
547 |
|
|
<p>The libio code is a subset of the guts of the GNU libc (glibc) I/O
|
548 |
|
|
implementation. When libio is in use, the <code>__basic_file</code>
|
549 |
|
|
type is basically derived from FILE. (The real situation is more
|
550 |
|
|
complex than that... it's derived from an internal type used to
|
551 |
|
|
implement FILE. See libio/libioP.h to see scary things done with
|
552 |
|
|
vtbls.) The result is that there is no "layer" of C stdio
|
553 |
|
|
to go through; the filebuf makes calls directly into the same
|
554 |
|
|
functions used to implement <code>fread</code>, <code>fwrite</code>,
|
555 |
|
|
and so forth, using internal data structures. (And when I say
|
556 |
|
|
"makes calls directly," I mean the function is literally
|
557 |
|
|
replaced by a jump into an internal function. Fast but frightening.
|
558 |
|
|
*grin*)
|
559 |
|
|
</p>
|
560 |
|
|
<p>Also, the libio internal locks are used. This requires pulling in
|
561 |
|
|
large chunks of glibc, such as a pthreads implementation, and is one
|
562 |
|
|
of the issues preventing widespread use of libio as the libstdc++
|
563 |
|
|
cstdio implementation.
|
564 |
|
|
</p>
|
565 |
|
|
<p>But we plan to make this work, at least as an option if not a future
|
566 |
|
|
default. Platforms running a copy of glibc with a recent-enough
|
567 |
|
|
version will see calls from libstdc++ directly into the glibc already
|
568 |
|
|
installed. For other platforms, a copy of the libio subsection will
|
569 |
|
|
be built and included in libstdc++.
|
570 |
|
|
</p>
|
571 |
|
|
<h3>Alternatives</h3>
|
572 |
|
|
<p>Don't forget that other cstdio implemenations are possible. You could
|
573 |
|
|
easily write one to perform your own forms of locking, to solve your
|
574 |
|
|
"interesting" problems.
|
575 |
|
|
</p>
|
576 |
|
|
|
577 |
|
|
<hr />
|
578 |
|
|
<h2><a name="10">Which header?</a></h2>
|
579 |
|
|
<p>To minimize the time you have to wait on the compiler, it's good to
|
580 |
|
|
only include the headers you really need. Many people simply include
|
581 |
|
|
<iostream> when they don't need to -- and that can <em>penalize
|
582 |
|
|
your runtime as well.</em> Here are some tips on which header to use
|
583 |
|
|
for which situations, starting with the simplest.
|
584 |
|
|
</p>
|
585 |
|
|
<p><strong><iosfwd></strong> should be included whenever you simply
|
586 |
|
|
need the <em>name</em> of an I/O-related class, such as
|
587 |
|
|
"ofstream" or "basic_streambuf". Like the name
|
588 |
|
|
implies, these are forward declarations. (A word to all you fellow
|
589 |
|
|
old school programmers: trying to forward declare classes like
|
590 |
|
|
"class istream;" won't work. Look in the iosfwd header if
|
591 |
|
|
you'd like to know why.) For example,
|
592 |
|
|
</p>
|
593 |
|
|
<pre>
|
594 |
|
|
#include <iosfwd>
|
595 |
|
|
|
596 |
|
|
class MyClass
|
597 |
|
|
{
|
598 |
|
|
....
|
599 |
|
|
std::ifstream& input_file;
|
600 |
|
|
};
|
601 |
|
|
|
602 |
|
|
extern std::ostream& operator<< (std::ostream&, MyClass&);
|
603 |
|
|
</pre>
|
604 |
|
|
<p><strong><ios></strong> declares the base classes for the entire
|
605 |
|
|
I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the
|
606 |
|
|
counting types std::streamoff and std::streamsize, the file
|
607 |
|
|
positioning type std::fpos, and the various manipulators like
|
608 |
|
|
std::hex, std::fixed, std::noshowbase, and so forth.
|
609 |
|
|
</p>
|
610 |
|
|
<p>The ios_base class is what holds the format flags, the state flags,
|
611 |
|
|
and the functions which change them (setf(), width(), precision(),
|
612 |
|
|
etc). You can also store extra data and register callback functions
|
613 |
|
|
through ios_base, but that has been historically underused. Anything
|
614 |
|
|
which doesn't depend on the type of characters stored is consolidated
|
615 |
|
|
here.
|
616 |
|
|
</p>
|
617 |
|
|
<p>The template class basic_ios is the highest template class in the
|
618 |
|
|
hierarchy; it is the first one depending on the character type, and
|
619 |
|
|
holds all general state associated with that type: the pointer to the
|
620 |
|
|
polymorphic stream buffer, the facet information, etc.
|
621 |
|
|
</p>
|
622 |
|
|
<p><strong><streambuf></strong> declares the template class
|
623 |
|
|
basic_streambuf, and two standard instantiations, streambuf and
|
624 |
|
|
wstreambuf. If you need to work with the vastly useful and capable
|
625 |
|
|
stream buffer classes, e.g., to create a new form of storage
|
626 |
|
|
transport, this header is the one to include.
|
627 |
|
|
</p>
|
628 |
|
|
<p><strong><istream></strong>/<strong><ostream></strong> are
|
629 |
|
|
the headers to include when you are using the >>/<<
|
630 |
|
|
interface, or any of the other abstract stream formatting functions.
|
631 |
|
|
For example,
|
632 |
|
|
</p>
|
633 |
|
|
<pre>
|
634 |
|
|
#include <istream>
|
635 |
|
|
|
636 |
|
|
std::ostream& operator<< (std::ostream& os, MyClass& c)
|
637 |
|
|
{
|
638 |
|
|
return os << c.data1() << c.data2();
|
639 |
|
|
}
|
640 |
|
|
</pre>
|
641 |
|
|
<p>The std::istream and std::ostream classes are the abstract parents of
|
642 |
|
|
the various concrete implementations. If you are only using the
|
643 |
|
|
interfaces, then you only need to use the appropriate interface header.
|
644 |
|
|
</p>
|
645 |
|
|
<p><strong><iomanip></strong> provides "extractors and inserters
|
646 |
|
|
that alter information maintained by class ios_base and its dervied
|
647 |
|
|
classes," such as std::setprecision and std::setw. If you need
|
648 |
|
|
to write expressions like <code>os << setw(3);</code> or
|
649 |
|
|
<code>is >> setbase(8);</code>, you must include <iomanip>.
|
650 |
|
|
</p>
|
651 |
|
|
<p><strong><sstream></strong>/<strong><fstream></strong>
|
652 |
|
|
declare the six stringstream and fstream classes. As they are the
|
653 |
|
|
standard concrete descendants of istream and ostream, you will already
|
654 |
|
|
know about them.
|
655 |
|
|
</p>
|
656 |
|
|
<p>Finally, <strong><iostream></strong> provides the eight standard
|
657 |
|
|
global objects (cin, cout, etc). To do this correctly, this header
|
658 |
|
|
also provides the contents of the <istream> and <ostream>
|
659 |
|
|
headers, but nothing else. The contents of this header look like
|
660 |
|
|
</p>
|
661 |
|
|
<pre>
|
662 |
|
|
#include <ostream>
|
663 |
|
|
#include <istream>
|
664 |
|
|
|
665 |
|
|
namespace std
|
666 |
|
|
{
|
667 |
|
|
extern istream cin;
|
668 |
|
|
extern ostream cout;
|
669 |
|
|
....
|
670 |
|
|
|
671 |
|
|
// this is explained below
|
672 |
|
|
<strong>static ios_base::Init __foo;</strong> // not its real name
|
673 |
|
|
}
|
674 |
|
|
</pre>
|
675 |
|
|
<p>Now, the runtime penalty mentioned previously: the global objects
|
676 |
|
|
must be initialized before any of your own code uses them; this is
|
677 |
|
|
guaranteed by the standard. Like any other global object, they must
|
678 |
|
|
be initialized once and only once. This is typically done with a
|
679 |
|
|
construct like the one above, and the nested class ios_base::Init is
|
680 |
|
|
specified in the standard for just this reason.
|
681 |
|
|
</p>
|
682 |
|
|
<p>How does it work? Because the header is included before any of your
|
683 |
|
|
code, the <strong>__foo</strong> object is constructed before any of
|
684 |
|
|
your objects. (Global objects are built in the order in which they
|
685 |
|
|
are declared, and destroyed in reverse order.) The first time the
|
686 |
|
|
constructor runs, the eight stream objects are set up.
|
687 |
|
|
</p>
|
688 |
|
|
<p>The <code>static</code> keyword means that each object file compiled
|
689 |
|
|
from a source file containing <iostream> will have its own
|
690 |
|
|
private copy of <strong>__foo</strong>. There is no specified order
|
691 |
|
|
of construction across object files (it's one of those pesky NP
|
692 |
|
|
problems that make life so interesting), so one copy in each object
|
693 |
|
|
file means that the stream objects are guaranteed to be set up before
|
694 |
|
|
any of your code which uses them could run, thereby meeting the
|
695 |
|
|
requirements of the standard.
|
696 |
|
|
</p>
|
697 |
|
|
<p>The penalty, of course, is that after the first copy of
|
698 |
|
|
<strong>__foo</strong> is constructed, all the others are just wasted
|
699 |
|
|
processor time. The time spent is merely for an increment-and-test
|
700 |
|
|
inside a function call, but over several dozen or hundreds of object
|
701 |
|
|
files, that time can add up. (It's not in a tight loop, either.)
|
702 |
|
|
</p>
|
703 |
|
|
<p>The lesson? Only include <iostream> when you need to use one of
|
704 |
|
|
the standard objects in that source file; you'll pay less startup
|
705 |
|
|
time. Only include the header files you need to in general; your
|
706 |
|
|
compile times will go down when there's less parsing work to do.
|
707 |
|
|
</p>
|
708 |
|
|
|
709 |
|
|
|
710 |
|
|
<hr />
|
711 |
|
|
<h2><a name="11">Using FILE*s and file descriptors with IOStreams</a></h2>
|
712 |
|
|
<!-- referenced by ext/howto.html#2, update link if numbering changes -->
|
713 |
|
|
<p>The v2 library included non-standard extensions to construct
|
714 |
|
|
<code>std::filebuf</code>s from C stdio types such as
|
715 |
|
|
<code>FILE*</code>s and POSIX file descriptors.
|
716 |
|
|
Today the recommended way to use stdio types with libstdc++-v3
|
717 |
|
|
IOStreams is via the <code>stdio_filebuf</code> class (see below),
|
718 |
|
|
but earlier releases provided slightly different mechanisms.
|
719 |
|
|
</p>
|
720 |
|
|
<ul>
|
721 |
|
|
<li>3.0.x <code>filebuf</code>s have another ctor with this signature:
|
722 |
|
|
<br />
|
723 |
|
|
<code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);</code>
|
724 |
|
|
<br />This comes in very handy in a number of places, such as
|
725 |
|
|
attaching Unix sockets, pipes, and anything else which uses file
|
726 |
|
|
descriptors, into the IOStream buffering classes. The three
|
727 |
|
|
arguments are as follows:
|
728 |
|
|
<ul>
|
729 |
|
|
<li><code>__c_file_type* F </code>
|
730 |
|
|
// the __c_file_type typedef usually boils down to stdio's FILE
|
731 |
|
|
</li>
|
732 |
|
|
<li><code>ios_base::openmode M </code>
|
733 |
|
|
// same as all the other uses of openmode
|
734 |
|
|
</li>
|
735 |
|
|
<li><code>int_type B </code>
|
736 |
|
|
// buffer size, defaults to BUFSIZ if not specified
|
737 |
|
|
</li>
|
738 |
|
|
</ul>
|
739 |
|
|
For those wanting to use file descriptors instead of FILE*'s, I
|
740 |
|
|
invite you to contemplate the mysteries of C's <code>fdopen()</code>.
|
741 |
|
|
</li>
|
742 |
|
|
<li>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring
|
743 |
|
|
back an old extension: the <code>fd()</code> member function. The
|
744 |
|
|
integer returned from this function can be used for whatever file
|
745 |
|
|
descriptors can be used for on your platform. Naturally, the
|
746 |
|
|
library cannot track what you do on your own with a file descriptor,
|
747 |
|
|
so if you perform any I/O directly, don't expect the library to be
|
748 |
|
|
aware of it.
|
749 |
|
|
</li>
|
750 |
|
|
<li>Beginning with 3.1, the extra <code>filebuf</code> constructor and
|
751 |
|
|
the <code>fd()</code> function were removed from the standard
|
752 |
|
|
filebuf. Instead, <code><ext/stdio_filebuf.h></code> contains
|
753 |
|
|
a derived class called
|
754 |
|
|
<a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/class____gnu__cxx_1_1stdio__filebuf.html"><code>__gnu_cxx::stdio_filebuf</code></a>.
|
755 |
|
|
This class can be constructed from a C <code>FILE*</code> or a file
|
756 |
|
|
descriptor, and provides the <code>fd()</code> function.
|
757 |
|
|
</li>
|
758 |
|
|
</ul>
|
759 |
|
|
<p>If you want to access a <code>filebuf</code>s file descriptor to
|
760 |
|
|
implement file locking (e.g. using the <code>fcntl()</code> system
|
761 |
|
|
call) then you might be interested in Henry Suter's
|
762 |
|
|
<a href="http://suter.home.cern.ch/suter/RWLock.html">RWLock</a>
|
763 |
|
|
class.
|
764 |
|
|
</p>
|
765 |
|
|
|
766 |
|
|
<!-- ####################################################### -->
|
767 |
|
|
|
768 |
|
|
<hr />
|
769 |
|
|
<p class="fineprint"><em>
|
770 |
|
|
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
|
771 |
|
|
Comments and suggestions are welcome, and may be sent to
|
772 |
|
|
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
|
773 |
|
|
</em></p>
|
774 |
|
|
|
775 |
|
|
|
776 |
|
|
</body>
|
777 |
|
|
</html>
|
778 |
|
|
|
779 |
|
|
|