diff options
Diffstat (limited to 'libstdc++-v3/docs/html/27_io/howto.html')
| -rw-r--r-- | libstdc++-v3/docs/html/27_io/howto.html | 779 |
1 files changed, 0 insertions, 779 deletions
diff --git a/libstdc++-v3/docs/html/27_io/howto.html b/libstdc++-v3/docs/html/27_io/howto.html deleted file mode 100644 index 14720537b95..00000000000 --- a/libstdc++-v3/docs/html/27_io/howto.html +++ /dev/null @@ -1,779 +0,0 @@ -<?xml version="1.0" encoding="ISO-8859-1"?> -<!DOCTYPE html - PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> - <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> - <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 27." /> - <meta name="GENERATOR" content="vi and eight fingers" /> - <title>libstdc++-v3 HOWTO: Chapter 27: Input/Output</title> -<link rel="StyleSheet" href="../lib3styles.css" type="text/css" /> -<link rel="Start" href="../documentation.html" type="text/html" - title="GNU C++ Standard Library" /> -<link rel="Prev" href="../26_numerics/howto.html" type="text/html" - title="Numerics" /> -<link rel="Next" href="../ext/howto.html" type="text/html" - title="Extensions" /> -<link rel="Copyright" href="../17_intro/license.html" type="text/html" /> -<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." /> -</head> -<body> - -<h1 class="centered"><a name="top">Chapter 27: Input/Output</a></h1> - -<p>Chapter 27 deals with iostreams and all their subcomponents - and extensions. All <em>kinds</em> of fun stuff. -</p> - - -<!-- ####################################################### --> -<hr /> -<h1>Contents</h1> -<ul> - <li><a href="#1">Copying a file</a></li> - <li><a href="#2">The buffering is screwing up my program!</a></li> - <li><a href="#3">Binary I/O</a></li> - <li><a href="#5">What is this <sstream>/stringstreams thing?</a></li> - <li><a href="#6">Deriving a stream buffer</a></li> - <li><a href="#7">More on binary I/O</a></li> - <li><a href="#8">Pathetic performance? Ditch C.</a></li> - <li><a href="#9">Threads and I/O</a></li> - <li><a href="#10">Which header?</a></li> - <li><a href="#11">Using FILE*s and file descriptors with IOStreams</a></li> -</ul> - -<hr /> - -<!-- ####################################################### --> - -<h2><a name="1">Copying a file</a></h2> - <p>So you want to copy a file quickly and easily, and most important, - completely portably. And since this is C++, you have an open - ifstream (call it IN) and an open ofstream (call it OUT): - </p> - <pre> - #include <fstream> - - std::ifstream IN ("input_file"); - std::ofstream OUT ("output_file"); </pre> - <p>Here's the easiest way to get it completely wrong: - </p> - <pre> - OUT << IN;</pre> - <p>For those of you who don't already know why this doesn't work - (probably from having done it before), I invite you to quickly - create a simple text file called "input_file" containing - the sentence - </p> - <pre> - The quick brown fox jumped over the lazy dog.</pre> - <p>surrounded by blank lines. Code it up and try it. The contents - of "output_file" may surprise you. - </p> - <p>Seriously, go do it. Get surprised, then come back. It's worth it. - </p> - <hr width="60%" /> - <p>The thing to remember is that the <code>basic_[io]stream</code> classes - handle formatting, nothing else. In particular, they break up on - whitespace. The actual reading, writing, and storing of data is - handled by the <code>basic_streambuf</code> family. Fortunately, the - <code>operator<<</code> is overloaded to take an ostream and - a pointer-to-streambuf, in order to help with just this kind of - "dump the data verbatim" situation. - </p> - <p>Why a <em>pointer</em> to streambuf and not just a streambuf? Well, - the [io]streams hold pointers (or references, depending on the - implementation) to their buffers, not the actual - buffers. This allows polymorphic behavior on the part of the buffers - as well as the streams themselves. The pointer is easily retrieved - using the <code>rdbuf()</code> member function. Therefore, the easiest - way to copy the file is: - </p> - <pre> - OUT << IN.rdbuf();</pre> - <p>So what <em>was</em> happening with OUT<<IN? Undefined - behavior, since that particular << isn't defined by the Standard. - I have seen instances where it is implemented, but the character - extraction process removes all the whitespace, leaving you with no - blank lines and only "Thequickbrownfox...". With - libraries that do not define that operator, IN (or one of IN's - member pointers) sometimes gets converted to a void*, and the output - file then contains a perfect text representation of a hexadecimal - address (quite a big surprise). Others don't compile at all. - </p> - <p>Also note that none of this is specific to o<b>*f*</b>streams. - The operators shown above are all defined in the parent - basic_ostream class and are therefore available with all possible - descendants. - </p> - <p>Return <a href="#top">to top of page</a> or - <a href="../faq/index.html">to the FAQ</a>. - </p> - -<hr /> -<h2><a name="2">The buffering is screwing up my program!</a></h2> -<!-- - This is not written very well. I need to redo this section. ---> - <p>First, are you sure that you understand buffering? Particularly - the fact that C++ may not, in fact, have anything to do with it? - </p> - <p>The rules for buffering can be a little odd, but they aren't any - different from those of C. (Maybe that's why they can be a bit - odd.) Many people think that writing a newline to an output - stream automatically flushes the output buffer. This is true only - when the output stream is, in fact, a terminal and not a file - or some other device -- and <em>that</em> may not even be true - since C++ says nothing about files nor terminals. All of that is - system-dependent. (The "newline-buffer-flushing only occurring - on terminals" thing is mostly true on Unix systems, though.) - </p> - <p>Some people also believe that sending <code>endl</code> down an - output stream only writes a newline. This is incorrect; after a - newline is written, the buffer is also flushed. Perhaps this - is the effect you want when writing to a screen -- get the text - out as soon as possible, etc -- but the buffering is largely - wasted when doing this to a file: - </p> - <pre> - output << "a line of text" << endl; - output << some_data_variable << endl; - output << "another line of text" << endl; </pre> - <p>The proper thing to do in this case to just write the data out - and let the libraries and the system worry about the buffering. - If you need a newline, just write a newline: - </p> - <pre> - output << "a line of text\n" - << some_data_variable << '\n' - << "another line of text\n"; </pre> - <p>I have also joined the output statements into a single statement. - You could make the code prettier by moving the single newline to - the start of the quoted text on the last line, for example. - </p> - <p>If you do need to flush the buffer above, you can send an - <code>endl</code> if you also need a newline, or just flush the buffer - yourself: - </p> - <pre> - output << ...... << flush; // can use std::flush manipulator - output.flush(); // or call a member fn </pre> - <p>On the other hand, there are times when writing to a file should - be like writing to standard error; no buffering should be done - because the data needs to appear quickly (a prime example is a - log file for security-related information). The way to do this is - just to turn off the buffering <em>before any I/O operations at - all</em> have been done (note that opening counts as an I/O operation): - </p> - <pre> - std::ofstream os; - std::ifstream is; - int i; - - os.rdbuf()->pubsetbuf(0,0); - is.rdbuf()->pubsetbuf(0,0); - - os.open("/foo/bar/baz"); - is.open("/qux/quux/quuux"); - ... - os << "this data is written immediately\n"; - is >> i; // and this will probably cause a disk read </pre> - <p>Since all aspects of buffering are handled by a streambuf-derived - member, it is necessary to get at that member with <code>rdbuf()</code>. - Then the public version of <code>setbuf</code> can be called. The - arguments are the same as those for the Standard C I/O Library - function (a buffer area followed by its size). - </p> - <p>A great deal of this is implementation-dependent. For example, - <code>streambuf</code> does not specify any actions for its own - <code>setbuf()</code>-ish functions; the classes derived from - <code>streambuf</code> each define behavior that "makes - sense" for that class: an argument of (0,0) turns off buffering - for <code>filebuf</code> but does nothing at all for its siblings - <code>stringbuf</code> and <code>strstreambuf</code>, and specifying - anything other than (0,0) has varying effects. - User-defined classes derived from <code>streambuf</code> can - do whatever they want. (For <code>filebuf</code> and arguments for - <code>(p,s)</code> other than zeros, libstdc++ does what you'd expect: - the first <code>s</code> bytes of <code>p</code> are used as a buffer, - which you must allocate and deallocate.) - </p> - <p>A last reminder: there are usually more buffers involved than - just those at the language/library level. Kernel buffers, disk - buffers, and the like will also have an effect. Inspecting and - changing those are system-dependent. - </p> - <p>Return <a href="#top">to top of page</a> or - <a href="../faq/index.html">to the FAQ</a>. - </p> - -<hr /> -<h2><a name="3">Binary I/O</a></h2> - <p>The first and most important thing to remember about binary I/O is - that opening a file with <code>ios::binary</code> is not, repeat - <em>not</em>, the only thing you have to do. It is not a silver - bullet, and will not allow you to use the <code><</>></code> - operators of the normal fstreams to do binary I/O. - </p> - <p>Sorry. Them's the breaks. - </p> - <p>This isn't going to try and be a complete tutorial on reading and - writing binary files (because "binary" - <a href="#7">covers a lot of ground)</a>, but we will try and clear - up a couple of misconceptions and common errors. - </p> - <p>First, <code>ios::binary</code> has exactly one defined effect, no more - and no less. Normal text mode has to be concerned with the newline - characters, and the runtime system will translate between (for - example) '\n' and the appropriate end-of-line sequence (LF on Unix, - CRLF on DOS, CR on Macintosh, etc). (There are other things that - normal mode does, but that's the most obvious.) Opening a file in - binary mode disables this conversion, so reading a CRLF sequence - under Windows won't accidentally get mapped to a '\n' character, etc. - Binary mode is not supposed to suddenly give you a bitstream, and - if it is doing so in your program then you've discovered a bug in - your vendor's compiler (or some other part of the C++ implementation, - possibly the runtime system). - </p> - <p>Second, using <code><<</code> to write and <code>>></code> to - read isn't going to work with the standard file stream classes, even - if you use <code>skipws</code> during reading. Why not? Because - ifstream and ofstream exist for the purpose of <em>formatting</em>, - not reading and writing. Their job is to interpret the data into - text characters, and that's exactly what you don't want to happen - during binary I/O. - </p> - <p>Third, using the <code>get()</code> and <code>put()/write()</code> member - functions still aren't guaranteed to help you. These are - "unformatted" I/O functions, but still character-based. - (This may or may not be what you want, see below.) - </p> - <p>Notice how all the problems here are due to the inappropriate use - of <em>formatting</em> functions and classes to perform something - which <em>requires</em> that formatting not be done? There are a - seemingly infinite number of solutions, and a few are listed here: - </p> - <ul> - <li>"Derive your own fstream-type classes and write your own - <</>> operators to do binary I/O on whatever data - types you're using." This is a Bad Thing, because while - the compiler would probably be just fine with it, other humans - are going to be confused. The overloaded bitshift operators - have a well-defined meaning (formatting), and this breaks it. - </li> - <li>"Build the file structure in memory, then <code>mmap()</code> - the file and copy the structure." Well, this is easy to - make work, and easy to break, and is pretty equivalent to - using <code>::read()</code> and <code>::write()</code> directly, and - makes no use of the iostream library at all... - </li> - <li>"Use streambufs, that's what they're there for." - While not trivial for the beginner, this is the best of all - solutions. The streambuf/filebuf layer is the layer that is - responsible for actual I/O. If you want to use the C++ - library for binary I/O, this is where you start. - </li> - </ul> - <p>How to go about using streambufs is a bit beyond the scope of this - document (at least for now), but while streambufs go a long way, - they still leave a couple of things up to you, the programmer. - As an example, byte ordering is completely between you and the - operating system, and you have to handle it yourself. - </p> - <p>Deriving a streambuf or filebuf - class from the standard ones, one that is specific to your data - types (or an abstraction thereof) is probably a good idea, and - lots of examples exist in journals and on Usenet. Using the - standard filebufs directly (either by declaring your own or by - using the pointer returned from an fstream's <code>rdbuf()</code>) - is certainly feasible as well. - </p> - <p>One area that causes problems is trying to do bit-by-bit operations - with filebufs. C++ is no different from C in this respect: I/O - must be done at the byte level. If you're trying to read or write - a few bits at a time, you're going about it the wrong way. You - must read/write an integral number of bytes and then process the - bytes. (For example, the streambuf functions take and return - variables of type <code>int_type</code>.) - </p> - <p>Another area of problems is opening text files in binary mode. - Generally, binary mode is intended for binary files, and opening - text files in binary mode means that you now have to deal with all of - those end-of-line and end-of-file problems that we mentioned before. - An instructive thread from comp.lang.c++.moderated delved off into - this topic starting more or less at - <a href="http://groups.google.com/groups?oi=djq&selm=an_436187505">this</a> - article and continuing to the end of the thread. (You'll have to - sort through some flames every couple of paragraphs, but the points - made are good ones.) - </p> - -<hr /> -<h2><a name="5">What is this <sstream>/stringstreams thing?</a></h2> - <p>Stringstreams (defined in the header <code><sstream></code>) - are in this author's opinion one of the coolest things since - sliced time. An example of their use is in the Received Wisdom - section for Chapter 21 (Strings), - <a href="../21_strings/howto.html#1.1internal"> describing how to - format strings</a>. - </p> - <p>The quick definition is: they are siblings of ifstream and ofstream, - and they do for <code>std::string</code> what their siblings do for - files. All that work you put into writing <code><<</code> and - <code>>></code> functions for your classes now pays off - <em>again!</em> Need to format a string before passing the string - to a function? Send your stuff via <code><<</code> to an - ostringstream. You've read a string as input and need to parse it? - Initialize an istringstream with that string, and then pull pieces - out of it with <code>>></code>. Have a stringstream and need to - get a copy of the string inside? Just call the <code>str()</code> - member function. - </p> - <p>This only works if you've written your - <code><<</code>/<code>>></code> functions correctly, though, - and correctly means that they take istreams and ostreams as - parameters, not i<b>f</b>streams and o<b>f</b>streams. If they - take the latter, then your I/O operators will work fine with - file streams, but with nothing else -- including stringstreams. - </p> - <p>If you are a user of the strstream classes, you need to update - your code. You don't have to explicitly append <code>ends</code> to - terminate the C-style character array, you don't have to mess with - "freezing" functions, and you don't have to manage the - memory yourself. The strstreams have been officially deprecated, - which means that 1) future revisions of the C++ Standard won't - support them, and 2) if you use them, people will laugh at you. - </p> - -<hr /> -<h2><a name="6">Deriving a stream buffer</a></h2> - <p>Creating your own stream buffers for I/O can be remarkably easy. - If you are interested in doing so, we highly recommend two very - excellent books: - <a href="http://www.langer.camelot.de/iostreams.html">Standard C++ - IOStreams and Locales</a> by Langer and Kreft, ISBN 0-201-18395-1, and - <a href="http://www.josuttis.com/libbook/">The C++ Standard Library</a> - by Nicolai Josuttis, ISBN 0-201-37926-0. Both are published by - Addison-Wesley, who isn't paying us a cent for saying that, honest. - </p> - <p>Here is a simple example, io/outbuf1, from the Josuttis text. It - transforms everything sent through it to uppercase. This version - assumes many things about the nature of the character type being - used (for more information, read the books or the newsgroups): - </p> - <pre> - #include <iostream> - #include <streambuf> - #include <locale> - #include <cstdio> - - class outbuf : public std::streambuf - { - protected: - /* central output function - * - print characters in uppercase mode - */ - virtual int_type overflow (int_type c) { - if (c != EOF) { - // convert lowercase to uppercase - c = std::toupper(static_cast<char>(c),getloc()); - - // and write the character to the standard output - if (putchar(c) == EOF) { - return EOF; - } - } - return c; - } - }; - - int main() - { - // create special output buffer - outbuf ob; - // initialize output stream with that output buffer - std::ostream out(&ob); - - out << "31 hexadecimal: " - << std::hex << 31 << std::endl; - return 0; - } - </pre> - <p>Try it yourself! More examples can be found in 3.1.x code, in - <code>include/ext/*_filebuf.h</code>, and on - <a href="http://www.informatik.uni-konstanz.de/~kuehl/c++/iostream/">Dietmar - Kühl's IOStreams page</a>. - </p> - -<hr /> -<h2><a name="7">More on binary I/O</a></h2> - <p>Towards the beginning of February 2001, the subject of - "binary" I/O was brought up in a couple of places at the - same time. One notable place was Usenet, where James Kanze and - Dietmar Kühl separately posted articles on why attempting - generic binary I/O was not a good idea. (Here are copies of - <a href="binary_iostreams_kanze.txt">Kanze's article</a> and - <a href="binary_iostreams_kuehl.txt">Kühl's article</a>.) - </p> - <p>Briefly, the problems of byte ordering and type sizes mean that - the unformatted functions like <code>ostream::put()</code> and - <code>istream::get()</code> cannot safely be used to communicate - between arbitrary programs, or across a network, or from one - invocation of a program to another invocation of the same program - on a different platform, etc. - </p> - <p>The entire Usenet thread is instructive, and took place under the - subject heading "binary iostreams" on both comp.std.c++ - and comp.lang.c++.moderated in parallel. Also in that thread, - Dietmar Kühl mentioned that he had written a pair of stream - classes that would read and write XDR, which is a good step towards - a portable binary format. - </p> - -<hr /> -<h2><a name="8">Pathetic performance? Ditch C.</a></h2> - <p>It sounds like a flame on C, but it isn't. Really. Calm down. - I'm just saying it to get your attention. - </p> - <p>Because the C++ library includes the C library, both C-style and - C++-style I/O have to work at the same time. For example: - </p> - <pre> - #include <iostream> - #include <cstdio> - - std::cout << "Hel"; - std::printf ("lo, worl"); - std::cout << "d!\n"; - </pre> - <p>This must do what you think it does. - </p> - <p>Alert members of the audience will immediately notice that buffering - is going to make a hash of the output unless special steps are taken. - </p> - <p>The special steps taken by libstdc++, at least for version 3.0, - involve doing very little buffering for the standard streams, leaving - most of the buffering to the underlying C library. (This kind of - thing is <a href="../explanations.html#cstdio">tricky to get right</a>.) - The upside is that correctness is ensured. The downside is that - writing through <code>cout</code> can quite easily lead to awful - performance when the C++ I/O library is layered on top of the C I/O - library (as it is for 3.0 by default). Some patches have been applied - which improve the situation for 3.1. - </p> - <p>However, the C and C++ standard streams only need to be kept in sync - when both libraries' facilities are in use. If your program only uses - C++ I/O, then there's no need to sync with the C streams. The right - thing to do in this case is to call - </p> - <pre> - #include <em>any of the I/O headers such as ios, iostream, etc</em> - - std::ios::sync_with_stdio(false); - </pre> - <p>You must do this before performing any I/O via the C++ stream objects. - Once you call this, the C++ streams will operate independently of the - (unused) C streams. For GCC 3.x, this means that <code>cout</code> and - company will become fully buffered on their own. - </p> - <p>Note, by the way, that the synchronization requirement only applies to - the standard streams (<code>cin</code>, <code>cout</code>, - <code>cerr</code>, - <code>clog</code>, and their wide-character counterparts). File stream - objects that you declare yourself have no such requirement and are fully - buffered. - </p> - -<hr /> -<h2><a name="9">Threads and I/O</a></h2> - <p>I'll assume that you have already read the - <a href="../17_intro/howto.html#3">general notes on library threads</a>, - and the - <a href="../23_containers/howto.html#3">notes on threaded container - access</a> (you might not think of an I/O stream as a container, but - the points made there also hold here). If you have not read them, - please do so first. - </p> - <p>This gets a bit tricky. Please read carefully, and bear with me. - </p> - <h3>Structure</h3> - <p>As described <a href="../explanations.html#cstdio">here</a>, a wrapper - type called <code>__basic_file</code> provides our abstraction layer - for the <code>std::filebuf</code> classes. Nearly all decisions dealing - with actual input and output must be made in <code>__basic_file</code>. - </p> - <p>A generic locking mechanism is somewhat in place at the filebuf layer, - but is not used in the current code. Providing locking at any higher - level is akin to providing locking within containers, and is not done - for the same reasons (see the links above). - </p> - <h3>The defaults for 3.0.x</h3> - <p>The __basic_file type is simply a collection of small wrappers around - the C stdio layer (again, see the link under Structure). We do no - locking ourselves, but simply pass through to calls to <code>fopen</code>, - <code>fwrite</code>, and so forth. - </p> - <p>So, for 3.0, the question of "is multithreading safe for I/O" - must be answered with, "is your platform's C library threadsafe - for I/O?" Some are by default, some are not; many offer multiple - implementations of the C library with varying tradeoffs of threadsafety - and efficiency. You, the programmer, are always required to take care - with multiple threads. - </p> - <p>(As an example, the POSIX standard requires that C stdio FILE* - operations are atomic. POSIX-conforming C libraries (e.g, on Solaris - and GNU/Linux) have an internal mutex to serialize operations on - FILE*s. However, you still need to not do stupid things like calling - <code>fclose(fs)</code> in one thread followed by an access of - <code>fs</code> in another.) - </p> - <p>So, if your platform's C library is threadsafe, then your - <code>fstream</code> I/O operations will be threadsafe at the lowest - level. For higher-level operations, such as manipulating the data - contained in the stream formatting classes (e.g., setting up callbacks - inside an <code>std::ofstream</code>), you need to guard such accesses - like any other critical shared resource. - </p> - <h3>The future</h3> - <p>As already mentioned <a href="../explanations.html#cstdio">here</a>, a - second choice is available for I/O implementations: libio. This is - disabled by default, and in fact will not currently work due to other - issues. It will be revisited, however. - </p> - <p>The libio code is a subset of the guts of the GNU libc (glibc) I/O - implementation. When libio is in use, the <code>__basic_file</code> - type is basically derived from FILE. (The real situation is more - complex than that... it's derived from an internal type used to - implement FILE. See libio/libioP.h to see scary things done with - vtbls.) The result is that there is no "layer" of C stdio - to go through; the filebuf makes calls directly into the same - functions used to implement <code>fread</code>, <code>fwrite</code>, - and so forth, using internal data structures. (And when I say - "makes calls directly," I mean the function is literally - replaced by a jump into an internal function. Fast but frightening. - *grin*) - </p> - <p>Also, the libio internal locks are used. This requires pulling in - large chunks of glibc, such as a pthreads implementation, and is one - of the issues preventing widespread use of libio as the libstdc++ - cstdio implementation. - </p> - <p>But we plan to make this work, at least as an option if not a future - default. Platforms running a copy of glibc with a recent-enough - version will see calls from libstdc++ directly into the glibc already - installed. For other platforms, a copy of the libio subsection will - be built and included in libstdc++. - </p> - <h3>Alternatives</h3> - <p>Don't forget that other cstdio implementations are possible. You could - easily write one to perform your own forms of locking, to solve your - "interesting" problems. - </p> - -<hr /> -<h2><a name="10">Which header?</a></h2> - <p>To minimize the time you have to wait on the compiler, it's good to - only include the headers you really need. Many people simply include - <iostream> when they don't need to -- and that can <em>penalize - your runtime as well.</em> Here are some tips on which header to use - for which situations, starting with the simplest. - </p> - <p><strong><iosfwd></strong> should be included whenever you simply - need the <em>name</em> of an I/O-related class, such as - "ofstream" or "basic_streambuf". Like the name - implies, these are forward declarations. (A word to all you fellow - old school programmers: trying to forward declare classes like - "class istream;" won't work. Look in the iosfwd header if - you'd like to know why.) For example, - </p> - <pre> - #include <iosfwd> - - class MyClass - { - .... - std::ifstream& input_file; - }; - - extern std::ostream& operator<< (std::ostream&, MyClass&); - </pre> - <p><strong><ios></strong> declares the base classes for the entire - I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the - counting types std::streamoff and std::streamsize, the file - positioning type std::fpos, and the various manipulators like - std::hex, std::fixed, std::noshowbase, and so forth. - </p> - <p>The ios_base class is what holds the format flags, the state flags, - and the functions which change them (setf(), width(), precision(), - etc). You can also store extra data and register callback functions - through ios_base, but that has been historically underused. Anything - which doesn't depend on the type of characters stored is consolidated - here. - </p> - <p>The template class basic_ios is the highest template class in the - hierarchy; it is the first one depending on the character type, and - holds all general state associated with that type: the pointer to the - polymorphic stream buffer, the facet information, etc. - </p> - <p><strong><streambuf></strong> declares the template class - basic_streambuf, and two standard instantiations, streambuf and - wstreambuf. If you need to work with the vastly useful and capable - stream buffer classes, e.g., to create a new form of storage - transport, this header is the one to include. - </p> - <p><strong><istream></strong>/<strong><ostream></strong> are - the headers to include when you are using the >>/<< - interface, or any of the other abstract stream formatting functions. - For example, - </p> - <pre> - #include <istream> - - std::ostream& operator<< (std::ostream& os, MyClass& c) - { - return os << c.data1() << c.data2(); - } - </pre> - <p>The std::istream and std::ostream classes are the abstract parents of - the various concrete implementations. If you are only using the - interfaces, then you only need to use the appropriate interface header. - </p> - <p><strong><iomanip></strong> provides "extractors and inserters - that alter information maintained by class ios_base and its derived - classes," such as std::setprecision and std::setw. If you need - to write expressions like <code>os << setw(3);</code> or - <code>is >> setbase(8);</code>, you must include <iomanip>. - </p> - <p><strong><sstream></strong>/<strong><fstream></strong> - declare the six stringstream and fstream classes. As they are the - standard concrete descendants of istream and ostream, you will already - know about them. - </p> - <p>Finally, <strong><iostream></strong> provides the eight standard - global objects (cin, cout, etc). To do this correctly, this header - also provides the contents of the <istream> and <ostream> - headers, but nothing else. The contents of this header look like - </p> - <pre> - #include <ostream> - #include <istream> - - namespace std - { - extern istream cin; - extern ostream cout; - .... - - // this is explained below - <strong>static ios_base::Init __foo;</strong> // not its real name - } - </pre> - <p>Now, the runtime penalty mentioned previously: the global objects - must be initialized before any of your own code uses them; this is - guaranteed by the standard. Like any other global object, they must - be initialized once and only once. This is typically done with a - construct like the one above, and the nested class ios_base::Init is - specified in the standard for just this reason. - </p> - <p>How does it work? Because the header is included before any of your - code, the <strong>__foo</strong> object is constructed before any of - your objects. (Global objects are built in the order in which they - are declared, and destroyed in reverse order.) The first time the - constructor runs, the eight stream objects are set up. - </p> - <p>The <code>static</code> keyword means that each object file compiled - from a source file containing <iostream> will have its own - private copy of <strong>__foo</strong>. There is no specified order - of construction across object files (it's one of those pesky NP - problems that make life so interesting), so one copy in each object - file means that the stream objects are guaranteed to be set up before - any of your code which uses them could run, thereby meeting the - requirements of the standard. - </p> - <p>The penalty, of course, is that after the first copy of - <strong>__foo</strong> is constructed, all the others are just wasted - processor time. The time spent is merely for an increment-and-test - inside a function call, but over several dozen or hundreds of object - files, that time can add up. (It's not in a tight loop, either.) - </p> - <p>The lesson? Only include <iostream> when you need to use one of - the standard objects in that source file; you'll pay less startup - time. Only include the header files you need to in general; your - compile times will go down when there's less parsing work to do. - </p> - - -<hr /> -<h2><a name="11">Using FILE*s and file descriptors with IOStreams</a></h2> - <!-- referenced by ext/howto.html#2, update link if numbering changes --> - <p>The v2 library included non-standard extensions to construct - <code>std::filebuf</code>s from C stdio types such as - <code>FILE*</code>s and POSIX file descriptors. - Today the recommended way to use stdio types with libstdc++-v3 - IOStreams is via the <code>stdio_filebuf</code> class (see below), - but earlier releases provided slightly different mechanisms. - </p> - <ul> - <li>3.0.x <code>filebuf</code>s have another ctor with this signature: - <br /> - <code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);</code> - <br />This comes in very handy in a number of places, such as - attaching Unix sockets, pipes, and anything else which uses file - descriptors, into the IOStream buffering classes. The three - arguments are as follows: - <ul> - <li><code>__c_file_type* F </code> - // the __c_file_type typedef usually boils down to stdio's FILE - </li> - <li><code>ios_base::openmode M </code> - // same as all the other uses of openmode - </li> - <li><code>int_type B </code> - // buffer size, defaults to BUFSIZ if not specified - </li> - </ul> - For those wanting to use file descriptors instead of FILE*'s, I - invite you to contemplate the mysteries of C's <code>fdopen()</code>. - </li> - <li>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring - back an old extension: the <code>fd()</code> member function. The - integer returned from this function can be used for whatever file - descriptors can be used for on your platform. Naturally, the - library cannot track what you do on your own with a file descriptor, - so if you perform any I/O directly, don't expect the library to be - aware of it. - </li> - <li>Beginning with 3.1, the extra <code>filebuf</code> constructor and - the <code>fd()</code> function were removed from the standard - filebuf. Instead, <code><ext/stdio_filebuf.h></code> contains - a derived class called - <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/class____gnu__cxx_1_1stdio__filebuf.html"><code>__gnu_cxx::stdio_filebuf</code></a>. - This class can be constructed from a C <code>FILE*</code> or a file - descriptor, and provides the <code>fd()</code> function. - </li> - </ul> - <p>If you want to access a <code>filebuf</code>s file descriptor to - implement file locking (e.g. using the <code>fcntl()</code> system - call) then you might be interested in Henry Suter's - <a href="http://suter.home.cern.ch/suter/RWLock.html">RWLock</a> - class. - </p> - -<!-- ####################################################### --> - -<hr /> -<p class="fineprint"><em> -See <a href="../17_intro/license.html">license.html</a> for copying conditions. -Comments and suggestions are welcome, and may be sent to -<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>. -</em></p> - - -</body> -</html> - - |