stdio_filebuf docs
Jonathan Wakely
cow@compsoc.man.ac.uk
Tue Feb 4 13:57:00 GMT 2003
Hi all,
I've added a new section to the chapter 27 (I/O) HOWTO, and moved the
stdio_filebuf notes into it from the extensions HOWTO, leaving just a
link on the extensions page. This should make it easier to find the
information from the docs TOC. I've also added the link to Henry Suter's
RWLock class that Paulo sent.
Copies of the modified pages can be seen (for a short while) here:
http://www.compsoc.man.ac.uk/~cow/tmp/gcc/documentation.html
http://www.compsoc.man.ac.uk/~cow/tmp/gcc/27_io/howto.html#11
http://www.compsoc.man.ac.uk/~cow/tmp/gcc/ext/howto.html#2
Comments welcome, otherwise I'll commit by tomorrow.
2002-02-04 Jonathan Wakely <redi@gcc.gnu.org>
* docs/html/27_io/howto.html: New section on stdio_filebuf.
* docs/html/ext/howto.html: Move stdio_filebuf notes to 27_io.
* docs/html/documentation.html: Regenerate.
I'll also added a link from the "Deriving a stream buffer" section to
Dietmar Kuehl's iostreams page, but I'll do this as a separate patch.
jon
--
"The value of a technical conversation is inversely proportional to
how well the participants are dressed."
- Larry McVoy
-------------- next part --------------
Index: docs/html/documentation.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/documentation.html,v
retrieving revision 1.27
diff -u -r1.27 documentation.html
--- docs/html/documentation.html 26 Dec 2002 21:14:19 -0000 1.27
+++ docs/html/documentation.html 4 Feb 2003 13:52:41 -0000
@@ -212,6 +212,7 @@
<li><a href="27_io/howto.html#8">Pathetic performance? Ditch C.</a></li>
<li><a href="27_io/howto.html#9">Threads and I/O</a></li>
<li><a href="27_io/howto.html#10">Which header?</a></li>
+ <li><a href="27_io/howto.html#11">Using FILE*s and file descriptors with IOStreams</a></li>
</ul>
</li>
Index: docs/html/27_io/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/27_io/howto.html,v
retrieving revision 1.22
diff -u -r1.22 howto.html
--- docs/html/27_io/howto.html 21 Nov 2002 07:15:57 -0000 1.22
+++ docs/html/27_io/howto.html 4 Feb 2003 13:52:41 -0000
@@ -35,6 +35,7 @@
<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 />
@@ -691,6 +692,60 @@
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>
+ <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 <code>__gnu_cxx::stdio_filebuf</code>. 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>
<!-- ####################################################### -->
Index: docs/html/ext/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/ext/howto.html,v
retrieving revision 1.25
diff -u -r1.25 howto.html
--- docs/html/ext/howto.html 11 Nov 2002 01:10:44 -0000 1.25
+++ docs/html/ext/howto.html 4 Feb 2003 13:52:41 -0000
@@ -124,40 +124,9 @@
<a href="sgiexts.html">their own page</a>. Since the SGI STL is no
longer actively maintained, we will try and keep this code working
ourselves.</li>
- <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 <code>__gnu_cxx::stdio_filebuf</code>.
- </li>
+ <li>Extensions allowing <code>filebuf</code>s to be constructed from
+ stdio types are described in the
+ <a href="../27_io/howto.html#11">chapter 27 notes</a>.</li>
</ul>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
More information about the Libstdc++
mailing list