From e7cc090e91b39ff34d75222a21a72d52f2ed6700 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Tue, 4 Feb 2003 17:42:19 +0000 Subject: [PATCH] howto.html: New section on stdio_filebuf. 2002-02-04 Jonathan Wakely * 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 --- libstdc++-v3/ChangeLog | 6 +++ libstdc++-v3/docs/html/27_io/howto.html | 55 +++++++++++++++++++++++ libstdc++-v3/docs/html/documentation.html | 1 + libstdc++-v3/docs/html/ext/howto.html | 37 ++------------- 4 files changed, 65 insertions(+), 34 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 5da889ccf45..d9c4f4ce7f1 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,9 @@ +2002-02-04 Jonathan Wakely + + * 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 * docs/html/17_intro/porting.texi: Update to GFDL 1.2. diff --git a/libstdc++-v3/docs/html/27_io/howto.html b/libstdc++-v3/docs/html/27_io/howto.html index d7a984ec3d5..54c47549fec 100644 --- a/libstdc++-v3/docs/html/27_io/howto.html +++ b/libstdc++-v3/docs/html/27_io/howto.html @@ -35,6 +35,7 @@
  • Pathetic performance? Ditch C.
  • Threads and I/O
  • Which header?
    • +
  • Using FILE*s and file descriptors with IOStreams
    • @@ -692,6 +693,60 @@

    +
    +

    Using FILE*s and file descriptors with IOStreams

    +

    The v2 library included non-standard extensions to construct + std::filebufs from C stdio types such as + FILE*s and POSIX file descriptors. + Today the recommended way to use stdio types with libstdc++-v3 + IOStreams is via the stdio_filebuf class (see below), + but earlier releases provided slightly different mechanisms. +

    +
      +
    • 3.0.x filebufs have another ctor with this signature: +
      + basic_filebuf(__c_file_type*, ios_base::openmode, int_type); +
      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: +
        +
      • __c_file_type* F + // the __c_file_type typedef usually boils down to stdio's FILE +
        • +
      • ios_base::openmode M + // same as all the other uses of openmode +
        • +
      • int_type B + // buffer size, defaults to BUFSIZ if not specified +
        • +
      + For those wanting to use file descriptors instead of FILE*'s, I + invite you to contemplate the mysteries of C's fdopen(). +
      • +
    • In library snapshot 3.0.95 and later, filebufs bring + back an old extension: the fd() 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. +
      • +
    • Beginning with 3.1, the extra filebuf constructor and + the fd() function were removed from the standard + filebuf. Instead, <ext/stdio_filebuf.h> contains + a derived class called __gnu_cxx::stdio_filebuf. This + class can be constructed from a C FILE* or a file + descriptor, and provides the fd() function. +
      • +
    +

    If you want to access a filebufs file descriptor to + implement file locking (e.g. using the fcntl() system + call) then you might be interested in Henry Suter's + RWLock + class. +

    +
    diff --git a/libstdc++-v3/docs/html/documentation.html b/libstdc++-v3/docs/html/documentation.html index c0e3cdb112d..b3f0fc0d97a 100644 --- a/libstdc++-v3/docs/html/documentation.html +++ b/libstdc++-v3/docs/html/documentation.html @@ -212,6 +212,7 @@
  • Pathetic performance? Ditch C.
  • Threads and I/O
  • Which header?
    • +
  • Using FILE*s and file descriptors with IOStreams
    • diff --git a/libstdc++-v3/docs/html/ext/howto.html b/libstdc++-v3/docs/html/ext/howto.html index 3d08c570385..07e5c2776a2 100644 --- a/libstdc++-v3/docs/html/ext/howto.html +++ b/libstdc++-v3/docs/html/ext/howto.html @@ -124,40 +124,9 @@ their own page. Since the SGI STL is no longer actively maintained, we will try and keep this code working ourselves. -
  • 3.0.x filebufs have another ctor with this signature: -
    - basic_filebuf(__c_file_type*, ios_base::openmode, int_type); -
    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: -
      -
    • __c_file_type* F - // the __c_file_type typedef usually boils down to stdio's FILE -
      • -
    • ios_base::openmode M - // same as all the other uses of openmode -
      • -
    • int_type B - // buffer size, defaults to BUFSIZ if not specified -
      • -
    - For those wanting to use file descriptors instead of FILE*'s, I - invite you to contemplate the mysteries of C's fdopen(). -
    • -
  • In library snapshot 3.0.95 and later, filebufs bring - back an old extension: the fd() 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. -
    • -
  • Beginning with 3.1, the extra filebuf constructor and - the fd() function were removed from the standard - filebuf. Instead, <ext/stdio_filebuf.h> contains - a derived class called __gnu_cxx::stdio_filebuf. -
    • +
  • Extensions allowing filebufs to be constructed from + stdio types are described in the + chapter 27 notes.

    • Return to top of page or to the FAQ.