home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / gnu / libg++-2.6.2.lha / libg++-2.6.2 / libio / iostream.info-2 (.txt) < prev    next >
GNU Info File  |  1994-12-15  |  19KB  |  365 lines
  1. This is Info file iostream.info, produced by Makeinfo-1.55 from the
  2. input file ./iostream.texi.
  3. START-INFO-DIR-ENTRY
  4. * iostream: (iostream).                    The C++ input/output facility.
  5. END-INFO-DIR-ENTRY
  6.    This file describes libio, the GNU library for C++ iostreams and C
  7. stdio.
  8.    libio includes software developed by the University of California,
  9. Berkeley.
  10.    Copyright (C) 1993 Free Software Foundation, Inc.
  11.    Permission is granted to make and distribute verbatim copies of this
  12. manual provided the copyright notice and this permission notice are
  13. preserved on all copies.
  14.    Permission is granted to copy and distribute modified versions of
  15. this manual under the conditions for verbatim copying, provided also
  16. that the entire resulting derived work is distributed under the terms
  17. of a permission notice identical to this one.
  18.    Permission is granted to copy and distribute translations of this
  19. manual into another language, under the above conditions for modified
  20. versions.
  21. File: iostream.info,  Node: Formatting,  Next: Stdiobuf,  Prev: Overflow,  Up: Streambuf
  22. C-style formatting for `streambuf' objects
  23. ==========================================
  24.    The GNU `streambuf' class supports `printf'-like formatting and
  25. scanning.
  26.  - Method: int streambuf::vform (const char *FORMAT, ...)
  27.      Similar to `fprintf(FILE, FORMAT, ...)'.  The FORMAT is a
  28.      `printf'-style format control string, which is used to format the
  29.      (variable number of) arguments, printing the result on the `this'
  30.      streambuf.  The result is the number of characters printed.
  31.  - Method: int streambuf::vform (const char *FORMAT, va_list ARGS)
  32.      Similar to `vfprintf(FILE, FORMAT, ARGS)'.  The FORMAT is a
  33.      `printf'-style format control string, which is used to format the
  34.      argument list ARGS, printing the result on the `this' streambuf.
  35.      The result is the number of characters printed.
  36.  - Method: int streambuf::scan (const char *FORMAT, ...)
  37.      Similar to `fscanf(FILE, FORMAT, ...)'.  The FORMAT is a
  38.      `scanf'-style format control string, which is used to read the
  39.      (variable number of) arguments from the `this' streambuf.  The
  40.      result is the number of items assigned, or `EOF' in case of input
  41.      failure before any conversion.
  42.  - Method: int streambuf::vscan (const char *FORMAT, va_list ARGS)
  43.      Like `streambuf::scan', but takes a single `va_list' argument.
  44. File: iostream.info,  Node: Stdiobuf,  Next: Procbuf,  Prev: Formatting,  Up: Streambuf
  45. Wrappers for C `stdio'
  46. ======================
  47.    A "stdiobuf" is a `streambuf' object that points to a `FILE' object
  48. (as defined by `stdio.h').  All `streambuf' operations on the
  49. `stdiobuf' are forwarded to the `FILE'.  Thus the `stdiobuf' object
  50. provides a wrapper around a `FILE', allowing use of `streambuf'
  51. operations on a `FILE'.  This can be useful when mixing C code with C++
  52. code.
  53.    The pre-defined streams `cin', `cout', and `cerr' are normally
  54. implemented as `stdiobuf' objects that point to respectively `stdin',
  55. `stdout', and `stderr'.  This is convenient, but it does cost some
  56. extra overhead.
  57.    If you set things up to use the implementation of `stdio' provided
  58. with this library, then `cin', `cout', and `cerr' will be set up to to
  59. use `stdiobuf' objects, since you get their benefits for free.  *Note C
  60. Input and Output: Stdio.
  61. File: iostream.info,  Node: Procbuf,  Next: Backing Up,  Prev: Stdiobuf,  Up: Streambuf
  62. Reading/writing from/to a pipe
  63. ==============================
  64.    The "procbuf" class is a GNU extension.  It is derived from
  65. `streambuf'.  A `procbuf' can be "closed" (in which case it does
  66. nothing), or "open" (in which case it allows communicating through a
  67. pipe with some other program).
  68.  - Constructor:  procbuf::procbuf ()
  69.      Creates a `procbuf' in a "closed" state.
  70.  - Method: procbuf* procbuf::open (const char *COMMAND, int MODE)
  71.      Uses the shell (`/bin/sh') to run a program specified by COMMAND.
  72.      If MODE is `ios::in', standard output from the program is sent to
  73.      a pipe; you can read from the pipe by reading from the `procbuf'.
  74.      (This is similar to `popen(COMMAND, "r")'.)
  75.      If MODE is `ios::out', output written written to the `procbuf' is
  76.      written to a pipe; the program is set up to read its standard
  77.      input from (the other end of) the pipe.  (This is similar to
  78.      `popen(COMMAND, "w")'.)
  79.      The `procbuf' must start out in the "closed" state.  Returns
  80.      `*this' on success, and `NULL' on failure.
  81.  - Constructor:  procbuf::procbuf (const char *COMMAND, int MODE)
  82.      Calls `procbuf::open (COMMAND, MODE)'.
  83.  - Method: procbuf* procbuf::close ()
  84.      Waits for the program to finish executing, and then cleans up the
  85.      resources used.  Returns `*this' on success, and `NULL' on failure.
  86.  - Destructor:  procbuf::~procbuf ()
  87.      Calls `procbuf::close'.
  88. File: iostream.info,  Node: Backing Up,  Next: Indirectbuf,  Prev: Procbuf,  Up: Streambuf
  89. Backing up
  90. ==========
  91.    The GNU iostream library allows you to ask a `streambuf' to remember
  92. the current position.  This allows you to go back to this position
  93. later, after reading further.  You can back up arbitrary amounts, even
  94. on unbuffered files or multiple buffers' worth, as long as you tell the
  95. library in advance.  This unbounded backup is very useful for scanning
  96. and parsing applications.  This example shows a typical scenario:
  97.      // Read either "dog", "hound", or "hounddog".
  98.      // If "dog" is found, return 1.
  99.      // If "hound" is found, return 2.
  100.      // If "hounddog" is found, return 3.
  101.      // If none of these are found, return -1.
  102.      int my_scan(streambuf* sb)
  103.      {
  104.          streammarker fence(sb);
  105.          char buffer[20];
  106.          // Try reading "hounddog":
  107.          if (sb->sgetn(buffer, 8) == 8
  108.              && strncmp(buffer, "hounddog", 8) == 0)
  109.            return 3;
  110.          // No, no "hounddog":  Back up to 'fence'
  111.          sb->seekmark(fence); //
  112.          // ... and try reading "dog":
  113.          if (sb->sgetn(buffer, 3) == 3
  114.              && strncmp(buffer, "dog", 3) == 0)
  115.            return 1;
  116.          // No, no "dog" either:  Back up to 'fence'
  117.          sb->seekmark(fence); //
  118.          // ... and try reading "hound":
  119.          if (sb->sgetn(buffer, 5) == 5
  120.              && strncmp(buffer, "hound", 5) == 0)
  121.            return 2;
  122.          // No, no "hound" either:  Back up and signal failure.
  123.          sb->seekmark(fence); // Backup to 'fence'
  124.          return -1;
  125.      }
  126.  - Constructor:  streammarker::streammarker (streambuf* SBUF)
  127.      Create a `streammarker' associated with SBUF that remembers the
  128.      current position of the get pointer.
  129.  - Method: int streammarker::delta (streammarker& MARK2)
  130.      Return the difference between the get positions corresponding to
  131.      `*this' and MARK2 (which must point into the same `streambuffer'
  132.      as `this').
  133.  - Method: int streammarker::delta ()
  134.      Return the position relative to the streambuffer's current get
  135.      position.
  136.  - Method: int streambuf::seekmark (streammarker& MARK)
  137.      Move the get pointer to where it (logically) was when MARK was
  138.      constructed.
  139. File: iostream.info,  Node: Indirectbuf,  Prev: Backing Up,  Up: Streambuf
  140. Forwarding I/O activity
  141. =======================
  142.    An "indirectbuf" is one that forwards all of its I/O requests to
  143. another streambuf.
  144.    An `indirectbuf' can be used to implement Common Lisp
  145. synonym-streams and two-way-streams:
  146.      class synonymbuf : public indirectbuf {
  147.         Symbol *sym;
  148.         synonymbuf(Symbol *s) { sym = s; }
  149.         virtual streambuf *lookup_stream(int mode) {
  150.             return coerce_to_streambuf(lookup_value(sym)); }
  151.      };
  152. File: iostream.info,  Node: Stdio,  Next: Index,  Prev: Streambuf,  Up: Top
  153. C Input and Output
  154. ******************
  155.    `libio' is distributed with a complete implementation of the ANSI C
  156. `stdio' facility.  It is implemented using `streambuf' objects.  *Note
  157. Wrappers for C `stdio': Stdiobuf.
  158.    The `stdio' package is intended as a replacement for the whatever
  159. `stdio' is in your C library.  Since `stdio' works best when you build
  160. `libc' to contain it, and that may be inconvenient, it is not installed
  161. by default.
  162.    Extensions beyond ANSI:
  163.    * A stdio `FILE' is identical to a stre