1 <?xml version="1.0" encoding="ISO-8859-1"?>
3 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
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"
19 <link rel="Next" href="../ext/howto.html" type="text/html"
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." />
26 <h1 class="centered"><a name="top">Chapter 27: Input/Output</a></h1>
28 <p>Chapter 27 deals with iostreams and all their subcomponents
29 and extensions. All <em>kinds</em> of fun stuff.
33 <!-- ####################################################### -->
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>
51 <!-- ####################################################### -->
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):
59 #include <fstream>
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:
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
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.
77 <p>Seriously, go do it. Get surprised, then come back. It's worth it.
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.
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:
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.
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
113 <p>Return <a href="#top">to top of page</a> or
114 <a href="../faq/index.html">to the FAQ</a>.
118 <h2><a name="2">The buffering is screwing up my program!</a></h2>
120 This is not written very well. I need to redo this section.
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?
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.)
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:
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:
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.
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
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):
177 os.rdbuf()->pubsetbuf(0,0);
178 is.rdbuf()->pubsetbuf(0,0);
180 os.open("/foo/bar/baz");
181 is.open("/qux/quux/quuux");
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).
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.)
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.
210 <p>Return <a href="#top">to top of page</a> or
211 <a href="../faq/index.html">to the FAQ</a>.
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.
222 <p>Sorry. Them's the breaks.
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.
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).
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
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.)
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:
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.
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...
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.
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.
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.
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>.)
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
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
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>
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.
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.
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
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.
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):
369 #include <iostream>
370 #include <streambuf>
371 #include <locale>
372 #include <cstdio>
374 class outbuf : public std::streambuf
377 /* central output function
378 * - print characters in uppercase mode
380 virtual int_type overflow (int_type c) {
382 // convert lowercase to uppercase
383 c = std::toupper(static_cast<char>(c),getloc());
385 // and write the character to the standard output
386 if (putchar(c) == EOF) {
396 // create special output buffer
398 // initialize output stream with that output buffer
399 std::ostream out(&ob);
401 out << "31 hexadecimal: "
402 << std::hex << 31 << std::endl;
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>.
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>.)
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.
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.
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.
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:
446 #include <iostream>
447 #include <cstdio>
449 std::cout << "Hel";
450 std::printf ("lo, worl");
451 std::cout << "d!\n";
453 <p>This must do what you think it does.
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.
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.
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
474 #include <em>any of the I/O headers such as ios, iostream, etc</em>
476 std::ios::sync_with_stdio(false);
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.
483 <p>Note, by the way, that the synchronization requirement only applies to
484 the standard streams (<code>cin</code>, <code>cout</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
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>,
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,
501 <p>This gets a bit tricky. Please read carefully, and bear with me.
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>.
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).
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.
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.
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.)
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.
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.
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.
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.
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++.
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.
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.
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,
594 #include <iosfwd>
599 std::ifstream& input_file;
602 extern std::ostream& operator<< (std::ostream&, MyClass&);
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.
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
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.
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.
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.
634 #include <istream>
636 std::ostream& operator<< (std::ostream& os, MyClass& c)
638 return os << c.data1() << c.data2();
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.
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>.
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
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
662 #include <ostream>
663 #include <istream>
671 // this is explained below
672 <strong>static ios_base::Init __foo;</strong> // not its real name
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.
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.
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.
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.)
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.
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.
721 <li>3.0.x <code>filebuf</code>s have another ctor with this signature:
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:
729 <li><code>__c_file_type* F </code>
730 // the __c_file_type typedef usually boils down to stdio's FILE
732 <li><code>ios_base::openmode M </code>
733 // same as all the other uses of openmode
735 <li><code>int_type B </code>
736 // buffer size, defaults to BUFSIZ if not specified
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>.
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
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.
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>
766 <!-- ####################################################### -->
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>.
projects / l4.git / blob