OpenE2K/gcc
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

howto.html: New section on stdio_filebuf.

Browse Source 
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.

From-SVN: r62383
This commit is contained in:
Jonathan Wakely 2003-02-04 17:42:19 +00:00
parent 9e80ada7a7
commit e7cc090e91
4 changed files with 65 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
libstdc++-v3/ChangeLog
View File

@ -1,3 +1,9 @@
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.
2003-02-04 Joseph S. Myers <jsm@polyomino.org.uk>
* docs/html/17_intro/porting.texi: Update to GFDL 1.2.

55
libstdc++-v3/docs/html/27_io/howto.html
View File

@ -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 />
@ -692,6 +693,60 @@
</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>&lt;ext/stdio_filebuf.h&gt;</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>
<!-- ####################################################### -->
<hr />

1
libstdc++-v3/docs/html/documentation.html
View File

@ -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>

37
libstdc++-v3/docs/html/ext/howto.html
View File

@ -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>&lt;ext/stdio_filebuf.h&gt;</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>.