   This file describes libio, the GNU library for C++ iostreams and C
stdio.

   libio includes software developed by the University of California,
Berkeley.

   Copyright (C) 1993 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

C-style formatting for `streambuf' objects
==========================================

   The GNU `streambuf' class supports `printf'-like formatting and
scanning.

 - Method: int streambuf::vform (const char *FORMAT, ...)
     Similar to `fprintf(FILE, FORMAT, ...)'.  The FORMAT is a
     `printf'-style format control string, which is used to format the
     (variable number of) arguments, printing the result on the `this'
     streambuf.  The result is the number of characters printed.

 - Method: int streambuf::vform (const char *FORMAT, va_list ARGS)
     Similar to `vfprintf(FILE, FORMAT, ARGS)'.  The FORMAT is a
     `printf'-style format control string, which is used to format the
     argument list ARGS, printing the result on the `this' streambuf.
     The result is the number of characters printed.

 - Method: int streambuf::scan (const char *FORMAT, ...)
     Similar to `fscanf(FILE, FORMAT, ...)'.  The FORMAT is a
     `scanf'-style format control string, which is used to read the
     (variable number of) arguments from the `this' streambuf.  The
     result is the number of items assigned, or `EOF' in case of input
     failure before any conversion.

 - Method: int streambuf::vscan (const char *FORMAT, va_list ARGS)
     Like `streambuf::scan', but takes a single `va_list' argument.

Wrappers for C `stdio'
======================

   A "stdiobuf" is a `streambuf' object that points to a `FILE' object
(as defined by `stdio.h').  All `streambuf' operations on the
`stdiobuf' are forwarded to the `FILE'.  Thus the `stdiobuf' object
provides a wrapper around a `FILE', allowing use of `streambuf'
operations on a `FILE'.  This can be useful when mixing C code with C++
code.

   The pre-defined streams `cin', `cout', and `cerr' are normally
implemented as `stdiobuf' objects that point to respectively `stdin',
`stdout', and `stderr'.  This is convenient, but it does cost some
extra overhead.

   If you set things up to use the implementation of `stdio' provided
with this library, then `cin', `cout', and `cerr' will be set up to to
use `stdiobuf' objects, since you get their benefits for free.  See C Input and Output.

Reading/writing from/to a pipe
==============================

   The "procbuf" class is a GNU extension.  It is derived from
`streambuf'.  A `procbuf' can be "closed" (in which case it does
nothing), or "open" (in which case it allows communicating through a
pipe with some other program).

 - Constructor:  procbuf::procbuf ()
     Creates a `procbuf' in a "closed" state.

 - Method: procbuf* procbuf::open (const char *COMMAND, int MODE)
     Uses the shell (`/bin/sh') to run a program specified by COMMAND.

     If MODE is `ios::in', standard output from the program is sent to
     a pipe; you can read from the pipe by reading from the `procbuf'.
     (This is similar to `popen(COMMAND, "r")'.)

     If MODE is `ios::out', output written written to the `procbuf' is
     written to a pipe; the program is set up to read its standard
     input from (the other end of) the pipe.  (This is similar to
     `popen(COMMAND, "w")'.)

     The `procbuf' must start out in the "closed" state.  Returns
     `*this' on success, and `NULL' on failure.

 - Constructor:  procbuf::procbuf (const char *COMMAND, int MODE)
     Calls `procbuf::open (COMMAND, MODE)'.

 - Method: procbuf* procbuf::close ()
     Waits for the program to finish executing, and then cleans up the
     resources used.  Returns `*this' on success, and `NULL' on failure.

 - Destructor:  procbuf::~procbuf ()
     Calls `procbuf::close'.

Backing up
==========

   The GNU iostream library allows you to ask a `streambuf' to remember
the current position.  This allows you to go back to this position
later, after reading further.  You can back up arbitrary amounts, even
on unbuffered files or multiple buffers' worth, as long as you tell the
library in advance.  This unbounded backup is very useful for scanning
and parsing applications.  This example shows a typical scenario:

     // Read either "dog", "hound", or "hounddog".
     // If "dog" is found, return 1.
     // If "hound" is found, return 2.
     // If "hounddog" is found, return 3.
     // If none of these are found, return -1.
     int my_scan(streambuf* sb)
     {
         streammarker fence(sb);
         char buffer[20];
         // Try reading "hounddog":
         if (sb->sgetn(buffer, 8) == 8
             && strncmp(buffer, "hounddog", 8) == 0)
           return 3;
         // No, no "hounddog":  Back up to 'fence'
         sb->seekmark(fence); //
         // ... and try reading "dog":
         if (sb->sgetn(buffer, 3) == 3
             && strncmp(buffer, "dog", 3) == 0)
           return 1;
         // No, no "dog" either:  Back up to 'fence'
         sb->seekmark(fence); //
         // ... and try reading "hound":
         if (sb->sgetn(buffer, 5) == 5
             && strncmp(buffer, "hound", 5) == 0)
           return 2;
         // No, no "hound" either:  Back up and signal failure.
         sb->seekmark(fence); // Backup to 'fence'
         return -1;
     }

 - Constructor:  streammarker::streammarker (streambuf* SBUF)
     Create a `streammarker' associated with SBUF that remembers the
     current position of the get pointer.

 - Method: int streammarker::delta (streammarker& MARK2)
     Return the difference between the get positions corresponding to
     `*this' and MARK2 (which must point into the same `streambuffer'
     as `this').

 - Method: int streammarker::delta ()
     Return the position relative to the streambuffer's current get
     position.

 - Method: int streambuf::seekmark (streammarker& MARK)
     Move the get pointer to where it (logically) was when MARK was
     constructed.

Forwarding I/O activity
=======================

   An "indirectbuf" is one that forwards all of its I/O requests to
another streambuf.

   An `indirectbuf' can be used to implement Common Lisp
synonym-streams and two-way-streams:

     class synonymbuf : public indirectbuf {
        Symbol *sym;
        synonymbuf(Symbol *s) { sym = s; }
        virtual streambuf *lookup_stream(int mode) {
            return coerce_to_streambuf(lookup_value(sym)); }
     };

C Input and Output
******************

   `libio' is distributed with a complete implementation of the ANSI C
`stdio' facility.  It is implemented using `streambuf' objects.  See
Wrappers for C `stdio'.

   The `stdio' package is intended as a replacement for the whatever
`stdio' is in your C library.  Since `stdio' works best when you build
`libc' to contain it, and that may be inconvenient, it is not installed
by default.

   Extensions beyond ANSI:

   * A stdio `FILE' is identical to a streambuf.  Hence there is no
     need to worry about synchronizing C and C++ input/output--they are
     by definition always synchronized.

   * If you create a new streambuf sub-class (in C++), you can use it
     as a `FILE' from C.  Thus the system is extensible using the
     standard `streambuf' protocol.

   * You can arbitrarily mix reading and writing, without having to seek
     in between.

   * Unbounded `ungetc()' buffer.

Index
*****