home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / gnu / libg++-2.5.3-bin.lha / info / iostream.info (.txt) next >
GNU Info File  |  1994-02-27  |  63KB  |  1,270 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::                    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: Top,  Next: Introduction,  Prev: (DIR),  Up: (DIR)
  22. The GNU C++ Iostream Library
  23. ****************************
  24.    This file provides reference information on the GNU C++ iostream
  25. library (`libio'), version 0.50.
  26. * Menu:
  27. * Introduction::
  28. * Operators::            Operators and default streams.
  29. * Streams::            Stream classes.
  30. * Files and Strings::        Classes for files and strings.
  31. * Streambuf::            Using the streambuf layer.
  32. * Stdio::            C input and output.
  33. * Index::
  34. File: iostream.info,  Node: Introduction,  Next: Operators,  Prev: Top,  Up: Top
  35. Introduction
  36. ************
  37.    The iostream classes implement most of the features of AT&T version
  38. 2.0 iostream library classes, and most of the features of the ANSI X3J16
  39. library draft (which is based on the AT&T design).
  40.    This manual is meant as a reference; for tutorial material on
  41. iostreams, see the corresponding section of any recent popular
  42. introduction to C++.
  43. * Menu:
  44. * Copying::        Special GNU licensing terms for libio.
  45. * Acknowledgements::    Contributors to GNU iostream.
  46. File: iostream.info,  Node: Copying,  Next: Acknowledgements,  Up: Introduction
  47. Licensing terms for `libio'
  48. ===========================
  49.    Since the `iostream' classes are so fundamental to standard C++, the
  50. Free Software Foundation has agreed to a special exception to its
  51. standard license, when you link programs with `libio.a':
  52.      As a special exception, if you link this library with files
  53.      compiled with a GNU compiler to produce an executable, this does
  54.      not cause the resulting executable to be covered by the GNU
  55.      General Public License.  This exception does not however
  56.      invalidate any other reasons why the executable file might be
  57.      covered by the GNU General Public License.
  58.    The code is under the GNU General Public License (version 2) for all
  59. other purposes than linking with this library; that means that you can
  60. modify and redistribute the code as usual, but remember that if you do,
  61. your modifications, and anything you link with the modified code, must
  62. be available to others on the same terms.
  63.    These functions are also available as part of the `libg++' library;
  64. if you link with that library instead of `libio', the GNU Library
  65. General Public License applies.
  66. File: iostream.info,  Node: Acknowledgements,  Prev: Copying,  Up: Introduction
  67. Acknowledgements
  68. ================
  69.    Per Bothner wrote most of the `iostream' library, but some portions
  70. have their origins elsewhere in the free software community.  Heinz
  71. Seidl wrote the IO manipulators.  The floating-point conversion software
  72. is by David M. Gay of AT&T.  Some code was derived from parts of BSD
  73. 4.4, which was written at the University of California, Berkeley.
  74.    The iostream classes are found in the `libio' library.  An early
  75. version was originally distributed in `libg++', and they are still
  76. included there as well, for convenience if you need other `libg++'
  77. classes.  Doug Lea was the original author of `libg++', and some of the
  78. file-management code still in `libio' is his.
  79.    Various people found bugs or offered suggestions.  Hongjiu Lu worked
  80. hard to use the library as the default stdio implementation for Linux,
  81. and has provided much stress-testing of the library.
  82. File: iostream.info,  Node: Operators,  Next: Streams,  Prev: Introduction,  Up: Top
  83. Operators and Default Streams
  84. *****************************
  85.    The GNU iostream library, `libio', implements the standard input and
  86. output facilities for C++.  These facilities are roughly analogous (in
  87. their purpose and ubiquity, at least) with those defined by the C
  88. `stdio' functions.
  89.    Although these definitions come from a library, rather than being
  90. part of the "core language", they are sufficiently central to be
  91. specified in the latest working papers for C++.
  92.    You can use two operators defined in this library for basic input and
  93. output operations.  They are familiar from any C++ introductory
  94. textbook: `<<' for output, and `>>' for input.  (Think of data flowing
  95. in the direction of the "arrows".)
  96.    These operators are often used in conjunction with three streams that
  97. are open by default:
  98.  - Variable: ostream cout
  99.      The standard output stream, analogous to the C `stdout'.
  100.  - Variable: istream cin
  101.      The standard input stream, analogous to the C `stdin'.
  102.  - Variable: ostream cerr
  103.      An alternative output stream for errors, analogous to the C
  104.      `stderr'.
  105. For example, this bare-bones C++ version of the traditional "hello"
  106. program uses `<<' and `cout':
  107.      #include <iostream.h>
  108.      
  109.      int main(int argc, char **argv)
  110.      {
  111.        cout << "Well, hi there.\n";
  112.        return 0;
  113.      }
  114.    Casual use of these operators may be seductive, but--other than in
  115. writing throwaway code for your own use--it is not necessarily simpler
  116. than managing input and output in any other language.  For example,
  117. robust code should check the state of the input and output streams
  118. between operations (for example, using the method `good').  *Note
  119. Checking the state of a stream: States.  You may also need to adjust
  120. maximum input or output field widths, using manipulators like `setw' or
  121. `setprecision'.
  122.  - Operator on ostream: <<
  123.      Write output to an open output stream of class `ostream'.  Defined
  124.      by this library on any OBJECT of a C++ primitive type, and on
  125.      other classes of the library.  You can overload the definition for
  126.      any of your own applications' classes.
  127.      Returns a reference to the implied argument `*this' (the open
  128.      stream it writes on), permitting statements like
  129.           cout << "The value of i is " << i << "\n";
  130.  - Operator on istream: >>
  131.      Read input from an open input stream of class `istream'.  Defined
  132.      by this library on primitive numeric, pointer, and string types;
  133.      you can extend the definition for any of your own applications'
  134.      classes.
  135.      Returns a reference to the implied argument `*this' (the open
  136.      stream it reads), permitting multiple inputs in one statement.
  137. File: iostream.info,  Node: Streams,  Next: Files and Strings,  Prev: Operators,  Up: Top
  138. Stream Classes
  139. **************
  140.    The previous chapter referred in passing to the classes `ostream'
  141. and `istream', for output and input respectively.  These classes share
  142. certain properties, captured in their base class `ios'.
  143. * Menu:
  144. * Ios::       Shared properties.
  145. * Ostream::   Managing output streams.
  146. * Istream::   Managing input streams.
  147. * Iostream::  Input and output together.
  148. File: iostream.info,  Node: Ios,  Next: Ostream,  Up: Streams
  149. Shared properties: class `ios'
  150. ==============================
  151.    The base class `ios' provides methods to test and manage the state
  152. of input or output streams.
  153.    `ios' delegates the job of actually reading and writing bytes to the
  154. abstract class `streambuf', which is designed to provide buffered
  155. streams (compatible with C, in the GNU implementation).  *Note Using
  156. the `streambuf' layer: Streambuf, for information on the facilities
  157. available at the `streambuf' level.
  158.  - Constructor:  ios::ios ([streambuf* SB [, ostream* TIE])
  159.      The `ios' constructor by default initializes a new `ios', and if
  160.      you supply a `streambuf' SB to associate with it, sets the state
  161.      `good' in the new `ios' object.  It also sets the default
  162.      properties of the new object.
  163.      You can also supply an optional second argument TIE to the
  164.      constructor: if present, it is an initial value for `ios::tie', to
  165.      associate the new `ios' object with another stream.
  166.  - Destructor:  ios::~ios ()
  167.      The `ios' destructor is virtual, permitting application-specific
  168.      behavior when a stream is closed--typically, the destructor frees
  169.      any storage associated with the stream and releases any other
  170.      associated objects.
  171. * Menu:
  172. * States::        Checking the state of a stream.
  173. * Format Control::    Choices in formatting.
  174. * Manipulators::    Convenient ways of changing stream properties.
  175. * Extending::        Extended data fields.
  176. * Synchronization::    Synchronizing related streams.
  177. * Streambuf from Ios::    Reaching the underlying streambuf.
  178. File: iostream.info,  Node: States,  Next: Format Control,  Up: Ios
  179. Checking the state of a stream
  180. ------------------------------
  181.    Use this collection of methods to test for (or signal) errors and
  182. other exceptional conditions of streams:
  183.  - Method: ios::operator void* () const
  184.      You can do a quick check on the state of the most recent operation
  185.      on a stream by examining a pointer to the stream itself.  The
  186.      pointer is arbitrary except for its truth value; it is true if no
  187.      failures have occurred (`ios::fail' is not true).  For example,
  188.      you might ask for input on `cin' only if all prior output
  189.      operations succeeded:
  190.           if (cout)
  191.           {
  192.             // Everything OK so far
  193.             cin >> new_value;
  194.             ...
  195.           }
  196.  - Method: ios::operator ! () const
  197.      In case it is more convenient to check whether something has
  198.      failed, the operator `!' returns true if `ios::fail' is true (an
  199.      operation has failed).  For example, you might issue an error
  200.      message if input failed:
  201.           if (!cin)
  202.           {
  203.             // Oops
  204.             cerr << "Eh?\n";
  205.           }
  206.  - Method: iostate ios::rdstate () const
  207.      Return the state flags for this stream.  The value is from the
  208.      enumeration `iostate'.  You can test for any combination of
  209.     `goodbit'
  210.           There are no indications of exceptional states on this stream.
  211.     `eofbit'
  212.           End of file.
  213.     `failbit'
  214.           An operation has failed on this stream; this usually
  215.           indicates bad format of input.
  216.     `badbit'
  217.           The stream is unusable.
  218.  - Method: void ios::setstate (iostate STATE)
  219.      Set the state flag for this stream to STATE *in addition to* any
  220.      state flags already set.  Synonym (for upward compatibility):
  221.      `ios::set'.
  222.      See `ios::clear' to set the stream state without regard to existing
  223.      state flags.  See `ios::good', `ios::eof', `ios::fail', and
  224.      `ios::bad', to test the state.
  225.  - Method: int ios::good () const
  226.      Test the state flags associated with this stream; true if no error
  227.      indicators are set.
  228.  - Method: int ios::bad () const
  229.      Test whether a stream is marked as unusable.  (Whether
  230.      `ios::badbit' is set.)
  231.  - Method: int ios::eof () const
  232.      True if end of file was reached on this stream.  (If `ios::eofbit'
  233.      is set.)
  234.  - Method: int ios::fail () const
  235.      Test for any kind of failure on this stream: *either* some
  236.      operation failed, *or* the stream is marked as bad.  (If either
  237.      `ios::failbit' or `ios::badbit' is set.)
  238.  - Method: void ios::clear (iostate STATE)
  239.      Set the state indication for this stream to the argument STATE.
  240.      You may call `ios::clear' with no argument, in which case the state
  241.      is set to `good' (no errors pending).
  242.      See `ios::good', `ios::eof', `ios::fail', and `ios::bad', to test
  243.      the state; see `ios::set' or `ios::setstate' for an alternative
  244.      way of setting the state.
  245. File: iostream.info,  Node: Format Control,  Next: Manipulators,  Prev: States,  Up: Ios
  246. Choices in formatting
  247. ---------------------
  248.    These methods control (or report on) settings for some details of
  249. controlling streams, primarily to do with formatting output:
  250.  - Method: char ios::fill () const
  251.      Report on the padding character in use.
  252.  - Method: char ios::fill (char PADDING)
  253.      Set the padding character.  You can also use the manipulator
  254.      `setfill'.  *Note Changing stream properties in expressions:
  255.      Manipulators.
  256.      Default: blank.
  257.  - Method: int ios::precision () const
  258.      Report the number of significant digits currently in use for
  259.      output of floating point numbers.
  260.      Default: `6'.
  261.  - Method: int ios::precision (int SIGNIF)
  262.      Set the number of significant digits (for input and output numeric
  263.      conversions) to SIGNIF.
  264.      You can also use the manipulator `setprecision' for this purpose.
  265.      *Note Changing stream properties using manipulators: Manipulators.
  266.  - Method: int ios::width () const
  267.      Report the current output field width setting (the number of
  268.      characters to write on the next `<<' output operation).
  269.      Default: `0', which means to use as many characters as necessary.
  270.  - Method: int ios::width (int NUM)
  271.      Set the input field width setting to NUM.  Return the *previous*
  272.      value for this stream.
  273.      This value resets to zero (the default) every time you use `<<';
  274.      it is essentially an additional implicit argument to that
  275.      operator.  You can also use the manipulator `setw' for this
  276.      purpose.  *Note Changing stream properties using manipulators:
  277.      Manipulators.
  278.  - Method: fmtflags ios::flags () const
  279.      Return the current value of the complete collection of flags
  280.      controlling the format state.  These are the flags and their
  281.      meanings when set:
  282.     `ios::dec'
  283.     `ios::oct'
  284.     `ios::hex'
  285.           What numeric base to use in converting integers from internal
  286.           to display representation, or vice versa: decimal, octal, or
  287.           hexadecimal, respectively.  (You can change the base using
  288.           the manipulator `setbase', or any of the manipulators `dec',
  289.           `oct', or `hex'; *note Changing stream properties in
  290.           expressions: Manipulators..)
  291.           On input, if none of these flags is set, read numeric
  292.           constants according to the prefix: decimal if no prefix (or a
  293.           `.' suffix), octal if a `0' prefix is present, hexadecimal if
  294.           a `0x' prefix is present.
  295.           Default: `dec'.
  296.     `ios::fixed'
  297.           Avoid scientific notation, and always show a fixed number of
  298.           digits after the decimal point, according to the output
  299.           precision in effect.  Use `ios::precision' to set precision.
  300.     `ios::left'
  301.     `ios::right'
  302.     `ios::internal'
  303.           Where output is to appear in a fixed-width field;
  304.           left-justified, right-justified, or with padding in the
  305.           middle (e.g. between a numeric sign and the associated
  306.           value), respectively.
  307.     `ios::scientific'
  308.           Use scientific (exponential) notation to display numbers.
  309.     `ios::showbase'
  310.           Display the conventional prefix as a visual indicator of the
  311.           conversion base: no prefix for decimal, `0' for octal, `0x'
  312.           for hexadecimal.
  313.     `ios::showpoint'
  314.           Display a decimal point and trailing zeros after it to fill
  315.           out numeric fields, even when redundant.
  316.     `ios::showpos'
  317.           Display a positive sign on display of positive numbers.
  318.     `ios::skipws'
  319.           Skip white space.  (On by default).
  320.     `ios::stdio'
  321.           Flush the C `stdio' streams `stdout' and `stderr' after each
  322.           output operation (for programs that mix C and C++ output
  323.           conventions).
  324.     `ios::unitbuf'
  325.           Flush after each output operation.
  326.     `ios::uppercase'
  327.           Use upper-case characters for the non-numeral elements in
  328.           numeric displays; for instance, `0X7A' rather than `0x7a', or
  329.           `3.14E+09' rather than `3.14e+09'.
  330.  - Method: fmtflags ios::flags (fmtflags VALUE)
  331.      Set VALUE as the complete collection of flags controlling the
  332.      format state.  The flag values are described under `ios::flags ()'.
  333.      Use `ios::setf' or `ios::unsetf' to change one property at a time.
  334.  - Method: fmtflags ios::setf (fmtflags FLAG)
  335.      Set one particular flag (of those described for `ios::flags ()';
  336.      return the complete collection of flags *previously* in effect.
  337.      (Use `ios::unsetf' to cancel.)
  338.  - Method: fmtflags ios::setf (fmtflags FLAG, fmtflags MASK)
  339.      Clear the flag values indicated by MASK, then set any of them that
  340.      are also in FLAG.  (Flag values are described for `ios::flags
  341.      ()'.)  Return the complete collection of flags *previously* in
  342.      effect.  (See `ios::unsetf' for another way of clearing flags.)
  343.  - Method: fmtflags ios::unsetf (fmtflags FLAG)
  344.      Make certain FLAG (a combination of flag values described for
  345.      `ios::flags ()') is not set for this stream; converse of
  346.      `ios::setf'.  Returns the old values of those flags.
  347. File: iostream.info,  Node: Manipulators,  Next: Extending,  Prev: Format Control,  Up: Ios
  348. Changing stream properties using manipulators
  349. ---------------------------------------------
  350.    For convenience, MANIPULATORS provide a way to change certain
  351. properties of streams, or otherwise affect them, in the middle of
  352. expressions involving `<<' or `>>'.  For example, you might write
  353.      cout << "|" << setfill('*') << setw(5) << 234 << "|";
  354. to produce `|**234|' as output.
  355.  - Manipulator:  ws
  356.      Skip whitespace.
  357.  - Manipulator:  flush
  358.      Flush an output stream.  For example, `cout << ... <<flush;' has
  359.      the same effect as `cout << ...; cout.flush();'.
  360.  - Manipulator:  endl
  361.      Write an end of line character `\n', then flushes the output
  362.      stream.
  363.  - Manipulator:  ends
  364.      Write `\0' (the string terminator character).
  365.  - Manipulator:  setprecision (int SIGNIF)
  366.      You can change the value of `ios::precision' in `<<' expressions
  367.      with the manipulator `setprecision(SIGNIF)'; for example,
  368.           cout << setprecision(2) << 4.567;
  369.      prints `4.6'.  Requires `#include <iomanip.h>'.
  370.  - Manipulator:  setw (int N)
  371.      You can change the value of `ios::width' in `<<' expressions with
  372.      the manipulator `setw(N)'; for example,
  373.           cout << setw(5) << 234;
  374.      prints `  234' with two leading blanks.  Requires `#include
  375.      <iomanip.h>'.
  376.  - Manipulator:  setbase (int BASE)
  377.      Where BASE is one of `10' (decimal), `8' (octal), or `16'
  378.      (hexadecimal), change the base value for numeric representations.
  379.      Requires `#include <iomanip.h>'.
  380.  - Manipulator:  dec
  381.      Select decimal base; equivalent to `setbase(10)'.
  382.  - Manipulator:  hex
  383.      Select hexadecimal base; equivalent to `setbase(16)'.
  384.  - Manipulator:  oct
  385.      Select octal base; equivalent to `setbase(8)'.
  386.  - Manipulator:  setfill (char PADDING)
  387.      Set the padding character, in the same way as `ios::fill'.
  388.      Requires `#include <iomanip.h>'.
  389. File: iostream.info,  Node: Extending,  Next: Synchronization,  Prev: Manipulators,  Up: Ios
  390. Extended data fields
  391. --------------------
  392.    A related collection of methods allows you to extend this collection
  393. of flags and parameters for your own applications, without risk of
  394. conflict between them:
  395.  - Method: static fmtflags ios::bitalloc ()
  396.      Reserve a bit (the single bit on in the result) to use as a flag.
  397.      Using `bitalloc' guards against conflict between two packages that
  398.      use `ios' objects for different purposes.
  399.      This method is available for upward compatibility, but is not in
  400.      the ANSI working paper.  The number of bits available is limited; a
  401.      return value of `0' means no bit is available.
  402.  - Method: static int ios::xalloc ()
  403.      Reserve space for a long integer or pointer parameter.  The result
  404.      is a unique nonnegative integer.  You can use it as an index to
  405.      `ios::iword' or `ios::pword'.  Use `xalloc' to arrange for
  406.      arbitrary special-purpose data in your `ios' objects, without risk
  407.      of conflict between packages designed for different purposes.
  408.  - Method: long& ios::iword (int INDEX)
  409.      Return a reference to arbitrary data, of long integer type, stored
  410.      in an `ios' instance.  INDEX, conventionally returned from
  411.      `ios::xalloc', identifies what particular data you need.
  412.  - Method: long ios::iword (int INDEX) const
  413.      Return the actual value of a long integer stored in an `ios'.
  414.  - Method: void*& ios::pword (int INDEX)
  415.      Return a reference to an arbitrary pointer, stored in an `ios'
  416.      instance.  INDEX, originally returned from `ios::xalloc',
  417.      identifies what particular pointer you need.
  418.  - Method: void* ios::pword (int INDEX) const
  419.      Return the actual value of a pointer stored in an `ios'.
  420. File: iostream.info,  Node: Synchronization,  Next: Streambuf from Ios,  Prev: Extending,  Up: Ios
  421. Synchronizing related streams
  422. -----------------------------
  423.    You can use these methods to synchronize related streams with one
  424. another:
  425.  - Method: ostream* ios::tie () const
  426.      Report on what output stream, if any, is to be flushed before
  427.      accessing this one.  A pointer value of `0' means no stream is
  428.      tied.
  429.  - Method: ostream* ios::tie (ostream* ASSOC)
  430.      Declare that output stream ASSOC must be flushed before accessing
  431.      this stream.
  432.  - Method: int ios::sync_with_stdio ([int SWITCH])
  433.      Unless iostreams and C `stdio' are designed to work together, you
  434.      may have to choose between efficient C++ streams output and output
  435.      compatible with C `stdio'.  Use `ios::sync_with_stdio()' to select
  436.      C compatibility.
  437.      The argument SWITCH is a GNU extension; use `0' as the argument to
  438.      choose output that is not necessarily compatible with C `stdio'.
  439.      The default value for SWITCH is `1'.
  440.      If you install the `stdio' implementation that comes with GNU
  441.      `libio', there are compatible input/output facilities for both C
  442.      and C++.  In that situation, this method is unnecessary--but you
  443.      may still want to write programs that call it, for portability.
  444. File: iostream.info,  Node: Streambuf from Ios,  Prev: Synchronization,  Up: Ios
  445. Reaching the underlying `streambuf'
  446. -----------------------------------
  447.    Finally, you can use this method to access the underlying object:
  448.  - Method: streambuf* ios::rdbuf () const
  449.      Return a pointer to the `streambuf' object that underlies this
  450.      `ios'.
  451. File: iostream.info,  Node: Ostream,  Next: Istream,  Prev: Ios,  Up: Streams
  452. Managing output streams: class `ostream'
  453. ========================================
  454.    Objects of class `ostream' inherit the generic methods from `ios',
  455. and in addition have the following methods available.  Declarations for
  456. this class come from `iostream.h'.
  457.  - Constructor:  ostream::ostream ()
  458.      The simplest form of the constructor for an `ostream' simply
  459.      allocates a new `ios' object.
  460.  - Constructor:  ostream::ostream (streambuf* SB [, ostream TIE])
  461.      This alternative constructor requires a first argument SB of type
  462.      `streambuf*', to use an existing open stream for output.  It also
  463.      accepts an optional second argument TIE, to specify a related
  464.      `ostream*' as the initial value for `ios::tie'.
  465.      If you give the `ostream' a `streambuf' explicitly, using this
  466.      constructor, the SB is *not* destroyed (or deleted or closed) when
  467.      the `ostream' is destroyed.
  468. * Menu:
  469. * Writing::        Writing on an ostream.
  470. * Output Position::    Repositioning an ostream.
  471. * Ostream Housekeeping:: Miscellaneous ostream utilities.
  472. File: iostream.info,  Node: Writing,  Next: Output Position,  Up: Ostream
  473. Writing on an `ostream'
  474. -----------------------
  475.    These methods write on an `ostream' (you may also use the operator
  476. `<<'; *note Operators and Default Streams: Operators.).
  477.  - Method: ostream& ostream::put (char C)
  478.      Write the single character C.
  479.  - Method: ostream& ostream::write (STRING, int LENGTH)
  480.      Write LENGTH characters of a string to this `ostream', beginning
  481.      at the pointer STRING.
  482.      STRING may have any of these types: `char*', `unsigned char*',
  483.      `signed char*'.
  484.  - Method: ostream& ostream::form (const char *FORMAT, ...)
  485.      A GNU extension, similar to `fprintf(FILE, FORMAT, ...)'.
  486.      FORMAT is a `printf'-style format control string, which is used to
  487.      format the (variable number of) arguments, printing the result on
  488.      this `ostream'.  See `ostream::vform' for a version that uses an
  489.      argument list rather than a variable number of arguments.
  490.  - Method: ostream& ostream::vform (const char *FORMAT, va_list ARGS)
  491.      A GNU extension, similar to `vfprintf(FILE, FORMAT, ARGS)'.
  492.      FORMAT is a `printf'-style format control string, which is used to
  493.      format the argument list ARGS, printing the result on this
  494.      `ostream'.  See `ostream::form' for a version that uses a variable
  495.      number of arguments rather than an argument list.
  496. File: iostream.info,  Node: Output Position,  Next: Ostream Housekeeping,  Prev: Writing,  Up: Ostream
  497. Repositioning an `ostream'
  498. --------------------------
  499.    You can control the output position (on output streams that actually
  500. support positions, typically files) with these methods:
  501.  - Method: streampos ostream::tellp ()
  502.      Return the current write position in the stream.
  503.  - Method: ostream& ostream::seekp (streampos LOC)
  504.      Reset the output position to LOC (which is usually the result of a
  505.      previous call to `ostream::tellp').  LOC specifies an absolute
  506.      position in the output stream.
  507.  - Method: ostream& ostream::seekp (streamoff LOC, REL)
  508.      Reset the output position to LOC, relative to the beginning, end,
  509.      or current output position in the stream, as indicated by REL (a
  510.      value from the enumeration `ios::seekdir'):
  511.     `beg'
  512.           Interpret LOC as an absolute offset from the beginning of the
  513.           file.
  514.     `cur'
  515.           Interpret LOC as an offset relative to the current output
  516.           position.
  517.     `end'
  518.           Interpret LOC as an offset from the current end of the output
  519.           stream.
  520. File: iostream.info,  Node: Ostream Housekeeping,  Prev: Output Position,  Up: Ostream
  521. Miscellaneous `ostream' utilities
  522. ---------------------------------
  523.    You may need to use these `ostream' methods for housekeeping:
  524.  - Method: ostream& flush ()
  525.      Deliver any pending buffered output for this `ostream'.
  526.  - Method: int ostream::opfx ()
  527.      `opfx' is a "prefix" method for operations on `ostream' objects;
  528.      it is designed to be called before any further processing.  See
  529.      `ostream::osfx' for the converse.
  530.      `opfx' tests that the stream is in state `good', and if so flushes
  531.      any stream tied to this one.
  532.      The result is `1' when `opfx' succeeds; else (if the stream state
  533.      is not `good'), the result is `0'.
  534.  - Method: void ostream::osfx ()
  535.      `osfx' is a "suffix" method for operations on `ostream' objects;
  536.      it is designed to be called at the conclusion of any processing.
  537.      All the `ostream' methods end by calling `osfx'.  See
  538.      `ostream::opfx' for the converse.
  539.      If the `unitbuf' flag is set for this stream, `osfx' flushes any
  540.      buffered output for it.
  541.      If the `stdio' flag is set for this stream, `osfx' flushes any
  542.      output buffered for the C output streams `stdout' and `stderr'.
  543. File: iostream.info,  Node: Istream,  Next: Iostream,  Prev: Ostream,  Up: Streams
  544. Managing input streams: class `istream'
  545. =======================================
  546.    Class `istream' objects are specialized for input; as for `ostream',
  547. they are derived from `ios', so you can use any of the general-purpose
  548. methods from that base class.  Declarations for this class also come
  549. from `iostream.h'.
  550.  - Constructor:  istream::istream ()
  551.      When used without arguments, the `istream' constructor simply
  552.      allocates a new `ios' object and initializes the input counter (the
  553.      value reported by `istream::gcount') to `0'.
  554.  - Constructor:  istream::istream (streambuf *SB [, ostream TIE])
  555.      You can also call the constructor with one or two arguments.  The
  556.      first argument SB is a `streambuf*'; if you supply this pointer,
  557.      the constructor uses that `streambuf' for input.  You can use the
  558.      second optional argument TIE to specify a related output stream as
  559.      the initial value for `ios::tie'.
  560.      If you give the `istream' a `streambuf' explicitly, using this
  561.      constructor, the SB is *not* destroyed (or deleted or closed) when
  562.      the `ostream' is destroyed.
  563. * Menu:
  564. * Char Input::        Reading one character.
  565. * String Input::    Reading strings.
  566. * Input Position::    Repositioning an istream.
  567. * Istream Housekeeping:: Miscellaneous istream utilities.
  568. File: iostream.info,  Node: Char Input,  Next: String Input,  Up: Istream
  569. Reading one character
  570. ---------------------
  571.    Use these methods to read a single character from the input stream:
  572.  - Method: int istream::get ()
  573.      Read a single character (or `EOF') from the input stream, returning
  574.      it (coerced to an unsigned char) as the result.
  575.  - Method: istream& istream::get (char& C)
  576.      Read a single character from the input stream, into `&C'.
  577.  - Method: int istream::peek ()
  578.      Return the next available input character, but *without* changing
  579.      the current input position.
  580. File: iostream.info,  Node: String Input,  Next: Input Position,  Prev: Char Input,  Up: Istream
  581. Reading strings
  582. ---------------
  583.    Use these methods to read strings (for example, a line at a time)
  584. from the input stream:
  585.  - Method: istream& istream::get (char* C, int LEN [, char DELIM])
  586.      Read a string from the input stream, into the array at C.
  587.      The remaining arguments limit how much to read: up to `len-1'
  588.      characters, or up to (but not including) the first occurrence in
  589.      the input of a particular delimiter character DELIM--newline
  590.      (`\n') by default.  (Naturally, if the stream reaches end of file
  591.      first, that too will terminate reading.)
  592.      If DELIM was present in the input, it remains available as if
  593.      unread; to discard it instead, see `iostream::getline'.
  594.      `get' writes `\0' at the end of the string, regardless of which
  595.      condition terminates the read.
  596.  - Method: istream& istream::get (streambuf& SB [, char DELIM])
  597.      Read characters from the input stream and copy them on the
  598.      `streambuf' object SB.  Copying ends either just before the next
  599.      instance of the delimiter character DELIM (newline `\n' by
  600.      default), or when either stream ends.   If DELIM was present in
  601.      the input, it remains available as if unread.
  602.  - Method: istream& istream::getline (CHARPTR, int LEN [, char DELIM])
  603.      Read a line from the input stream, into the array at CHARPTR.
  604.      cHARPTR may be any of three kinds of pointer: `char*', `unsigned
  605.      char*', or `signed char*'.
  606.      The remaining arguments limit how much to read: up to (but not
  607.      including) the first occurrence in the input of a line delimiter
  608.      character DELIM--newline (`\n') by default, or up to `len-1'
  609.      characters (or to end of file, if that happens sooner).
  610.      If `getline' succeeds in reading a "full line", it also discards
  611.      the trailing delimiter character from the input stream.  (To
  612.      preserve it as available input, see the similar form of
  613.      `iostream::get'.)
  614.      If DELIM was *not* found before LEN characters or end of file,
  615.      `getline' sets the `ios::fail' flag, as well as the `ios::eof'
  616.      flag if appropriate.
  617.      `getline' writes a null character at the end of the string,
  618.      regardless of which condition terminates the read.
  619.  - Method: istream& istream::read (POINTER, int LEN)
  620.      Read LEN bytes into the location at POINTER, unless the input ends
  621.      first.
  622.      POINTER may be of type `char*', `void*', `unsigned char*', or
  623.      `signed char*'.
  624.      If the `istream' ends before reading LEN bytes, `read' sets the
  625.      `ios::fail' flag.
  626.  - Method: istream& istream::gets (char **S [, char DELIM])
  627.      A GNU extension, to read an arbitrarily long string from the
  628.      current input position to the next instance of the DELIM character
  629.      (newline `\n' by default).
  630.      To permit reading a string of arbitrary length, `gets' allocates
  631.      whatever memory is required.  Notice that the first argument S is
  632.      an address to record a character pointer, rather than the pointer
  633.      itself.
  634.  - Method: istream& istream::scan (const char *format ...)
  635.      A GNU extension, similar to `fscanf(FILE, FORMAT, ...)'.  The
  636.      FORMAT is a `scanf'-style format control string, which is used to
  637.      read the variables in the remainder of the argument list from the
  638.      `istream'.
  639.  - Method: istream& istream::vscan (const char *format, va_list args)
  640.      Like `istream::scan', but takes a single `va_list' argument.
  641. File: iostream.info,  Node: Input Position,  Next: Istream Housekeeping,  Prev: String Input,  Up: Istream
  642. Repositioning an `istream'
  643. --------------------------
  644.    Use these methods to control the current input position:
  645.  - Method: streampos istream::tellg ()
  646.      Return the current read position, so that you can save it and
  647.      return to it later with `istream::seekg'.
  648.  - Method: istream& istream::seekg (streampos P)
  649.      Reset the input pointer (if the input device permits it) to P,
  650.      usually the result of an earlier call to `istream::tellg'.
  651.  - Method: istream& istream::seekg (streamoff OFFSET, ios::seek_dir REF)
  652.      Reset the input pointer (if the input device permits it) to OFFSET
  653.      characters from the beginning of the input, the current position,
  654.      or the end of input.  Specify how to interpret OFFSET with one of
  655.      these values for the second argument:
  656.     `ios::beg'
  657.           Interpret LOC as an absolute offset from the beginning of the
  658.           file.
  659.     `ios::cur'
  660.           Interpret LOC as an offset relative to the current output
  661.           position.
  662.     `ios::end'
  663.           Interpret LOC as an offset from the current end of the output
  664.           stream.
  665. File: iostream.info,  Node: Istream Housekeeping,  Prev: Input Position,  Up: Istream
  666. Miscellaneous `istream' utilities
  667. ---------------------------------
  668.    Use these methods for housekeeping on `istream' objects:
  669.  - Method: int istream::gcount ()
  670.      Report how many characters were read from this `istream' in the
  671.      last unformatted input operation.
  672.  - Method: int istream::ipfx (int KEEPWHITE)
  673.      Ensure that the `istream' object is ready for reading; check for
  674.      errors and end of file and flush any tied stream.  `ipfx' skips
  675.      whitespace if you specify `0' as the KEEPWHITE argument, *and*
  676.      `ios::skipws' is set for this stream.
  677.      To avoid skipping whitespace (regardless of the `skipws' setting on
  678.      the stream), use `1' as the argument.
  679.      Call `istream::ipfx' to simplify writing your own methods for
  680.      reading `istream' objects.
  681.  - Method: void istream::isfx ()
  682.      A placeholder for compliance with the draft ANSI standard; this
  683.      method does nothing whatever.
  684.      If you wish to write portable standard-conforming code on `istream'
  685.      objects, call `isfx' after any operation that reads from an
  686.      `istream'; if `istream::ipfx' has any special effects that must be
  687.      cancelled when done, `istream::isfx' will cancel them.
  688.  - Method: istream& istream::ignore ([int N] [, int DELIM])
  689.      Discard some number of characters pending input.  The first
  690.      optional argument N specifies how many characters to skip.  The
  691.      second optional argument DELIM specifies a "boundary" character:
  692.      `ignore' returns immediately if this character appears in the
  693.      input.
  694.      By default, DELIM is `EOF'; that is, if you do not specify a
  695.      second argument, only the count N restricts how much to ignore
  696.      (while input is still available).
  697.      If you do not specify how many characters to ignore, `ignore'
  698.      returns after discarding only one character.
  699.  - Method: istream& istream::putback (char CH)
  700.      Attempts to back up one character, replacing the character
  701.      backed-up over by CH.  Returns `EOF' if this is not allowed.
  702.      Putting back the most recently read character is always allowed.
  703.      (This method corresponds to the C function `ungetc'.)
  704.  - Method: istream& istream::unget ()
  705.      Attempt to back up one character.
  706. File: iostream.info,  Node: Iostream,  Prev: Istream,  Up: Streams
  707. Input and output together: class `iostream'
  708. ===========================================
  709.    If you need to use the same stream for input and output, you can use
  710. an object of the class `iostream', which is derived from *both*
  711. `istream' and `ostream'.
  712.    The constructors for `iostream' behave just like the constructors
  713. for `istream'.
  714.  - Constructor:  iostream::iostream ()
  715.      When used without arguments, the `iostream' constructor simply
  716.      allocates a new `ios' object, and initializes the input counter
  717.      (the value reported by `istream::gcount') to `0'.
  718.  - Constructor:  iostream::iostream (streambuf* SB [, ostream* TIE])
  719.      You can also call a constructor with one or two arguments.  The
  720.      first argument SB is a `streambuf*'; if you supply this pointer,
  721.      the constructor uses that `streambuf' for input and output.
  722.      You can use the optional second argument TIE (an `ostream*') to
  723.      specify a related output stream as the initial value for
  724.      `ios::tie'.
  725.    As for `ostream' and `istream', `iostream' simply uses the `ios'
  726. destructor.  However, an `iostream' is not deleted by its destructor.
  727.    You can use all the `istream', `ostream', and `ios' methods with an
  728. `iostream' object.
  729. File: iostream.info,  Node: Files and Strings,  Next: Streambuf,  Prev: Streams,  Up: Top
  730. Classes for Files and Strings
  731. *****************************
  732.    There are two very common special cases of input and output: using
  733. files, and using strings in memory.
  734.    `libio' defines four specialized classes for these cases:
  735. `ifstream'
  736.      Methods for reading files.
  737. `ofstream'
  738.      Methods for writing files.
  739. `istrstream'
  740.      Methods for reading strings from memory.
  741. `ostrstream'
  742.      Methods for writing strings in memory.
  743. * Menu:
  744. * Files::    Reading and writing files.
  745. * Strings::    Reading and writing strings in memory.
  746. File: iostream.info,  Node: Files,  Next: Strings,  Up: Files and Strings
  747. Reading and writing files
  748. =========================
  749.    These methods are declared in `fstream.h'.
  750.    You can read data from class `ifstream' with any operation from class
  751. `istream'.  There are also a few specialized facilities:
  752.  - Constructor:  ifstream::ifstream ()
  753.      Make an `ifstream' associated with a new file for input.  (If you
  754.      use this version of the constructor, you need to call
  755.      `ifstream::open' before actually reading anything)
  756.  - Constructor:  ifstream::ifstream (int FD)
  757.      Make an `ifstream' for reading from a file that was already open,
  758.      using file descriptor FD.  (This constructor is compatible with
  759.      other versions of iostreams for POSIX systems, but is not part of
  760.      the ANSI working paper.)
  761.  - Constructor:  ifstream::ifstream (const char* FNAME [, int MODE
  762.           [, int PROT]])
  763.      Open a file `*FNAME' for this `ifstream' object.
  764.      By default, the file is opened for input (with `ios::in' as MODE).
  765.      If you use this constructor, the file will be closed when the
  766.      `ifstream' is destroyed.
  767.      You can use the optional argument MODE to specify how to open the
  768.      file, by combining these enumerated values (with `|' bitwise or).
  769.      (These values are actually defined in class `ios', so that all
  770.      file-related streams may inherit them.)  Only some of these modes
  771.      are defined in the latest draft ANSI specification; if portability
  772.      is important, you may wish to avoid the others.
  773.     `ios::in'
  774.           Open for input.  (Included in ANSI draft.)
  775.     `ios::out'
  776.           Open for output.  (Included in ANSI draft.)
  777.     `ios::ate'
  778.           Set the initial input (or output) position to the end of the
  779.           file.
  780.     `ios::app'
  781.           Seek to end of file before each write.  (Included in ANSI
  782.           draft.)
  783.     `ios::trunc'
  784.           Guarantee a fresh file; discard any contents that were
  785.           previously associated with it.
  786.     `ios::nocreate'
  787.           Guarantee an existing file; fail if the specified file did
  788.           not already exist.
  789.     `ios::noreplace'
  790.           Guarantee a new file; fail if the specified file already
  791.           existed.
  792.     `ios::bin'
  793.           Open as a binary file (on systems where binary and text files
  794.           have different properties, typically how `\n' is mapped;
  795.           included in ANSI draft).
  796.      The last optional argument PROT is specific to Unix-like systems;
  797.      it specifies the file protection (by default `644').
  798.  - Method: void ifstream::open (const char* FNAME [, int MODE [, int
  799.           PROT]])
  800.      Open a file explicitly after the associated `ifstream' object
  801.      already exists (for instance, after using the default
  802.      constructor).  The arguments, options and defaults all have the
  803.      same meanings as in the fully specified `ifstream' constructor.
  804.    You can write data to class `ofstream' with any operation from class
  805. `ostream'.  There are also a few specialized facilities:
  806.  - Constructor:  ofstream::ofstream ()
  807.      Make an `ofstream' associated with a new file for output.
  808.  - Constructor:  ofstream::ofstream (int FD)
  809.      Make an `ofstream' for writing to a file that was already open,
  810.      using file descriptor FD.
  811.  - Constructor:  ofstream::ofstream (const char* FNAME [, int MODE
  812.           [, int PROT]])
  813.      Open a file `*FNAME' for this `ofstream' object.
  814.      By default, the file is opened for output (with `ios::out' as
  815.      MODE).  You can use the optional argument MODE to specify how to
  816.      open the file, just as described for `ifstream::ifstream'.
  817.      The last optional argument PROT specifies the file protection (by
  818.      default `644').
  819.  - Destructor:  ofstream::~ofstream ()
  820.      The files associated with `ofstream' objects are closed when the
  821.      corresponding object is destroyed.
  822.  - Method: void ofstream::open (const char* FNAME [, int MODE [, int
  823.           PROT]])
  824.      Open a file explicitly after the associated `ofstream' object
  825.      already exists (for instance, after using the default
  826.      constructor).  The arguments, options and defaults all have the
  827.      same meanings as in the fully specified `ofstream' constructor.
  828.    The class `fstream' combines the facilities of `ifstream' and
  829. `ofstream', just as `iostream' combines `istream' and `ostream'.
  830.    The class `fstreambase' underlies both `ifstream' and `ofstream'.
  831. They both inherit this additional method:
  832.  - Method: void fstreambase::close ()
  833.      Close the file associated with this object, and set `ios::fail' in
  834.      this object to mark the event.
  835. File: iostream.info,  Node: Strings,  Prev: Files,  Up: Files and Strings
  836. Reading and writing in memory
  837. =============================
  838.    The classes `istrstream', `ostrstream', and `strstream' provide some
  839. additional features for reading and writing strings in memory--both
  840. static strings, and dynamically allocated strings.  The underlying
  841. class `strstreambase' provides some features common to all three;
  842. `strstreambuf' underlies that in turn.
  843.  - Constructor:  istrstream::istrstream (const char* STR [, int SIZE])
  844.      Associate the new input string class `istrstream' with an existing
  845.      static string starting at STR, of size SIZE.  If you do not
  846.      specify SIZE, the string is treated as a `NUL' terminated string.
  847.  - Constructor:  ostrstream::ostrstream ()
  848.      Create a new stream for output to a dynamically managed string,
  849.      which will grow as needed.
  850.  - Constructor:  ostrstream::ostrstream (char* STR, int SIZE [,int
  851.           MODE])
  852.      A new stream for output to a statically defined string of length
  853.      SIZE, starting at STR.  You may optionally specify one of the
  854.      modes described for `ifstream::ifstream'; if you do not specify
  855.      one, the new stream is simply open for output, with mode
  856.      `ios::out'.
  857.  - Method: int ostrstream::pcount ()
  858.      Report the current length of the string associated with this
  859.      `ostrstream'.
  860.  - Method: char* ostrstream::str ()
  861.      A pointer to the string managed by this `ostrstream'.  Implies
  862.      `ostrstream::freeze()'.
  863.  - Method: void ostrstream::freeze ([int N])
  864.      If N is nonzero (the default), declare that the string associated
  865.      with this `ostrstream' is not to change dynamically; while frozen,
  866.      it will not be reallocated if it needs more space, and it will not
  867.      be deallocated when the `ostrstream' is destroyed.  Use
  868.      `freeze(1)' if you refer to the string as a pointer after creating
  869.      it via `ostrstream' facilities.
  870.      `freeze(0)' cancels this declaration, allowing a dynamically
  871.      allocated string to be freed when its `ostrstream' is destroyed.
  872.      If this `ostrstream' is already static--that is, if it was created
  873.      to manage an existing statically allocated string--`freeze' is
  874.      unnecessary, and has no effect.
  875.  - Method: int ostrstream::frozen ()
  876.      Test whether `freeze(1)' is in effect for this string.
  877.  - Method: strstreambuf* strstreambase::rdbuf ()
  878.      A pointer to the underlying `strstreambuf'.
  879. File: iostream.info,  Node: Streambuf,  Next: Stdio,  Prev: Files and Strings,  Up: Top
  880. Using the `streambuf' Layer
  881. ***************************
  882.    The `istream' and `ostream' classes are meant to handle conversion
  883. between objects in your program and their textual representation.
  884.    By contrast, the underlying `streambuf' class is for transferring
  885. raw bytes between your program, and input sources or output sinks.
  886. Different `streambuf' subclasses connect to different kinds of sources
  887. and sinks.
  888.    The GNU implementation of `streambuf' is still evolving; we describe
  889. only some of the highlights.
  890. * Menu:
  891. * Areas::        Areas in a streambuf.
  892. * Formatting::        C-style formatting for streambuf objects.
  893. * Stdiobuf::        Wrappers for C stdio.
  894. * Backing Up::        Marking and returning to a position.
  895. * Indirectbuf::        Forwarding I/O activity.
  896. File: iostream.info,  Node: Areas,  Next: Formatting,  Up: Streambuf
  897. Areas of a `streambuf'
  898. ======================
  899.    Streambuf buffer management is fairly sophisticated (this is a nice
  900. way to say "complicated").  The standard protocol has the following
  901. "areas":
  902.    * The "put area" contains characters waiting for output.
  903.    * The "get area" contains characters available for reading.
  904.    The GNU `streambuf' design extends this, but the details are still
  905. evolving.
  906. File: iostream.info,  Node: Formatting,  Next: Stdiobuf,  Prev: Areas,  Up: Streambuf
  907. C-style formatting for `streambuf' objects
  908. ==========================================
  909.    The GNU `streambuf' class supports `printf'-like formatting and
  910. scanning.
  911.  - Method: int streambuf::vform (const char *FORMAT, ...)
  912.      Similar to `fprintf(FILE, FORMAT, ...)'.  The FORMAT is a
  913.      `printf'-style format control string, which is used to format the
  914.      (variable number of) arguments, printing the result on the `this'
  915.      streambuf.  The result is the number of characters printed.
  916.  - Method: int streambuf::vform (const char *FORMAT, va_list ARGS)
  917.      Similar to `vfprintf(FILE, FORMAT, ARGS)'.  The FORMAT is a
  918.      `printf'-style format control string, which is used to format the
  919.      argument list ARGS, printing the result on the `this' streambuf.
  920.      The result is the number of characters printed.
  921.  - Method: int streambuf::scan (const char *FORMAT, ...)
  922.      Similar to `fscanf(FILE, FORMAT, ...)'.  The FORMAT is a
  923.      `scanf'-style format control string, which is used to read the
  924.      (variable number of) arguments from the `this' streambuf.  The
  925.      result is the number of items assigned, or `EOF' in case of input
  926.      failure before any conversion.
  927.  - Method: int streambuf::vscan (const char *FORMAT, va_list ARGS)
  928.      Like `streambuf::scan', but takes a single `va_list' argument.
  929. File: iostream.info,  Node: Stdiobuf,  Next: Backing Up,  Prev: Formatting,  Up: Streambuf
  930. Wrappers for C `stdio'
  931. ======================
  932.    A "stdiobuf" is a `streambuf' object that points to a `FILE' object
  933. (as defined by `stdio.h').  All `streambuf' operations on the
  934. `stdiobuf' are forwarded to the `FILE'.  Thus the `stdiobuf' object
  935. provides a wrapper around a `FILE', allowing use of `streambuf'
  936. operations on a `FILE'.  This can be useful when mixing C code with C++
  937. code.
  938.    The pre-defined streams `cin', `cout', and `cerr' are normally
  939. implemented as `stdiobuf' objects that point to respectively `stdin',
  940. `stdout', and `stderr'.  This is convenient, but it does cost some
  941. extra overhead.
  942.    If you set things up to use the implementation of `stdio' provided
  943. with this library, then `cin', `cout', and `cerr' will be set up to to
  944. use `stdiobuf' objects, since you get their benefits for free.  *Note C
  945. Input and Output: Stdio.
  946. File: iostream.info,  Node: Backing Up,  Next: Indirectbuf,  Prev: Stdiobuf,  Up: Streambuf
  947. Backing up
  948. ==========
  949.    The GNU iostream library allows you to ask a `streambuf' to remember
  950. the current position.  This allows you to go back to this position
  951. later, after reading further.  You can back up arbitrary amounts, even
  952. on unbuffered files or multiple buffers' worth, as long as you tell the
  953. library in advance.  This unbounded backup is very useful for scanning
  954. and parsing applications.  This example shows a typical scenario:
  955.      // Read either "dog", "hound", or "hounddog".
  956.      // If "dog" is found, return 1.
  957.      // If "hound" is found, return 2.
  958.      // If "hounddog" is found, return 3.
  959.      // If none of these are found, return -1.
  960.      int my_scan(streambuf* sb)
  961.      {
  962.          streammarker fence(sb);
  963.          char buffer[20];
  964.          // Try reading "hounddog":
  965.          if (sb->sgetn(buffer, 8) == 8
  966.              && strncmp(buffer, "hounddog", 8) == 0)
  967.            return 3;
  968.          // No, no "hounddog":  Back up to 'fence'
  969.          sb->seekmark(fence); //
  970.          // ... and try reading "dog":
  971.          if (sb->sgetn(buffer, 3) == 3
  972.              && strncmp(buffer, "dog", 3) == 0)
  973.            return 1;
  974.          // No, no "dog" either:  Back up to 'fence'
  975.          sb->seekmark(fence); //
  976.          // ... and try reading "hound":
  977.          if (sb->sgetn(buffer, 5) == 5
  978.              && strncmp(buffer, "hound", 5) == 0)
  979.            return 2;
  980.          // No, no "hound" either:  Back up and signal failure.
  981.          sb->seekmark(fence); // Backup to 'fence'
  982.          return -1;
  983.      }
  984.  - Constructor:  streammarker::streammarker (streambuf* SBUF)
  985.      Create a `streammarker' associated with SBUF that remembers the
  986.      current position of the get pointer.
  987.  - Method: int streammarker::delta (streammarker& MARK2)
  988.      Return the difference between the get positions corresponding to
  989.      `*this' and MARK2 (which must point into the same `streambuffer'
  990.      as `this').
  991.  - Method: int streammarker::delta ()
  992.      Return the position relative to the streambuffer's current get
  993.      position.
  994.  - Method: int streambuffer::seekmark (streammarker& MARK)
  995.      Move the get pointer to where it (logically) was when MARK was
  996.      constructed.
  997. File: iostream.info,  Node: Indirectbuf,  Prev: Backing Up,  Up: Streambuf
  998. Forwarding I/O activity
  999. =======================
  1000.    An "indirectbuf" is one that forwards all of its I/O requests to
  1001. another streambuf.
  1002.    An `indirectbuf' can be used to implement Common Lisp
  1003. synonym-streams and two-way-streams:
  1004.      class synonymbuf : public indirectbuf {
  1005.         Symbol *sym;
  1006.         synonymbuf(Symbol *s) { sym = s; }
  1007.         virtual streambuf *lookup_stream(int mode) {
  1008.             return coerce_to_streambuf(lookup_value(sym)); }
  1009.      };
  1010. File: iostream.info,  Node: Stdio,  Next: Index,  Prev: Streambuf,  Up: Top
  1011. C Input and Output
  1012. ******************
  1013.    `libio' is distributed with a complete implementation of the ANSI C
  1014. `stdio' facility.  It is implemented using `streambuf' objects.  *Note
  1015. Wrappers for C `stdio': Stdiobuf.
  1016.    The `stdio' package is intended as a replacement for the whatever
  1017. `stdio' is in your C library.  Since `stdio' works best when you build
  1018. `libc' to contain it, and that may be inconvenient, it is not installed
  1019. by default.
  1020.    Extensions beyond ANSI:
  1021.    * A stdio `FILE' is identical to a streambuf.  Hence there is no
  1022.      need to worry about synchronizing C and C++ input/output--they are
  1023.      by definition always synchronized.
  1024.    * If you create a new streambuf sub-class (in C++), you can use it
  1025.      as a `FILE' from C.  Thus the system is extensible using the
  1026.      standard `streambuf' protocol.
  1027.    * You can arbitrarily mix reading and writing, without having to seek
  1028.      in between.
  1029.    * Unbounded `ungetc()' buffer.
  1030. File: iostream.info,  Node: Index,  Prev: Stdio,  Up: Top
  1031. Index
  1032. *****
  1033. * Menu:
  1034. * (:                                    States.
  1035. * (:                                    States.
  1036. * << on ostream:                        Operators.
  1037. * >> on istream:                        Operators.
  1038. * iostream destructor:                  Iostream.
  1039. * badbit:                               States.
  1040. * beg:                                  Output Position.
  1041. * cerr:                                 Operators.
  1042. * cin:                                  Operators.
  1043. * class fstreambase:                    Files.
  1044. * class fstream:                        Files.
  1045. * class ifstream:                       Files.
  1046. * class istrstream:                     Strings.
  1047. * class ostream:                        Files.
  1048. * class ostrstream:                     Strings.
  1049. * class strstreambase:                  Strings.
  1050. * class strstreambuf:                   Strings.
  1051. * class strstream:                      Strings.
  1052. * cout:                                 Operators.
  1053. * cur:                                  Output Position.
  1054. * dec:                                  Manipulators.
  1055. * destructor for iostream:              Iostream.
  1056. * end:                                  Output Position.
  1057. * endl:                                 Manipulators.
  1058. * ends:                                 Manipulators.
  1059. * eofbit:                               States.
  1060. * failbit:                              States.
  1061. * flush:                                Manipulators.
  1062. * flush:                                Ostream Housekeeping.
  1063. * fstream:                              Files.
  1064. * fstreambase:                          Files.
  1065. * fstreambase::close:                   Files.
  1066. * get area:                             Areas.
  1067. * goodbit:                              States.
  1068. * hex:                                  Manipulators.
  1069. * ifstream:                             Files.
  1070. * ifstream:                             Files and Strings.
  1071. * ifstream::ifstream:                   Files.
  1072. * ifstream::ifstream:                   Files.
  1073. * ifstream::ifstream:                   Files.
  1074. * ifstream::open:                       Files.
  1075. * ios::app:                             Files.
  1076. * ios::ate:                             Files.
  1077. * ios::bad:                             States.
  1078. * ios::beg:                             Input Position.
  1079. * ios::bin:                             Files.
  1080. * ios::bitalloc:                        Extending.
  1081. * ios::clear:                           States.
  1082. * ios::cur:                             Input Position.
  1083. * ios::dec:                             Format Control.
  1084. * ios::end:                             Input Position.
  1085. * ios::eof:                             States.
  1086. * ios::fail:                            States.
  1087. * ios::fill:                            Format Control.
  1088. * ios::fill:                            Format Control.
  1089. * ios::fixed:                           Format Control.
  1090. * ios::flags:                           Format Control.
  1091. * ios::flags:                           Format Control.
  1092. * ios::good:                            States.
  1093. * ios::hex:                             Format Control.
  1094. * ios::in:                              Files.
  1095. * ios::internal:                        Format Control.
  1096. * ios::ios:                             Ios.
  1097. * ios::iword:                           Extending.
  1098. * ios::iword:                           Extending.
  1099. * ios::left:                            Format Control.
  1100. * ios::nocreate:                        Files.
  1101. * ios::noreplace:                       Files.
  1102. * ios::oct:                             Format Control.
  1103. * ios::out:                             Files.
  1104. * ios::precision:                       Format Control.
  1105. * ios::precision:                       Format Control.
  1106. * ios::pword:                           Extending.
  1107. * ios::pword:                           Extending.
  1108. * ios::rdbuf:                           Streambuf from Ios.
  1109. * ios::rdstate:                         States.
  1110. * ios::right:                           Format Control.
  1111. * ios::scientific:                      Format Control.
  1112. * ios::seekdir:                         Output Position.
  1113. * ios::set:                             States.
  1114. * ios::setf:                            Format Control.
  1115. * ios::setf:                            Format Control.
  1116. * ios::setstate:                        States.
  1117. * ios::showbase:                        Format Control.
  1118. * ios::showpoint:                       Format Control.
  1119. * ios::showpos:                         Format Control.
  1120. * ios::skipws:                          Format Control.
  1121. * ios::stdio:                           Format Control.
  1122. * ios::sync_with_stdio:                 Synchronization.
  1123. * ios::tie:                             Synchronization.
  1124. * ios::tie:                             Synchronization.
  1125. * ios::trunc:                           Files.
  1126. * ios::unitbuf:                         Format Control.
  1127. * ios::unsetf:                          Format Control.
  1128. * ios::uppercase:                       Format Control.
  1129. * ios::width:                           Format Control.
  1130. * ios::width:                           Format Control.
  1131. * ios::xalloc:                          Extending.
  1132. * ios::~ios:                            Ios.
  1133. * iostream::iostream:                   Iostream.
  1134. * iostream::iostream:                   Iostream.
  1135. * istream::gcount:                      Istream Housekeeping.
  1136. * istream::get:                         String Input.
  1137. * istream::get:                         Char Input.
  1138. * istream::get:                         String Input.
  1139. * istream::get:                         Char Input.
  1140. * istream::getline:                     String Input.
  1141. * istream::gets:                        String Input.
  1142. * istream::ignore:                      Istream Housekeeping.
  1143. * istream::ipfx:                        Istream Housekeeping.
  1144. * istream::isfx:                        Istream Housekeeping.
  1145. * istream::istream:                     Istream.
  1146. * istream::istream:                     Istream.
  1147. * istream::peek:                        Char Input.
  1148. * istream::putback:                     Istream Housekeeping.
  1149. * istream::read:                        String Input.
  1150. * istream::scan:                        String Input.
  1151. * istream::seekg:                       Input Position.
  1152. * istream::seekg:                       Input Position.
  1153. * istream::tellg:                       Input Position.
  1154. * istream::unget:                       Istream Housekeeping.
  1155. * istream::vscan:                       String Input.
  1156. * istrstream:                           Files and Strings.
  1157. * istrstream:                           Strings.
  1158. * istrstream::istrstream:               Strings.
  1159. * oct:                                  Manipulators.
  1160. * ofstream:                             Files and Strings.
  1161. * ofstream::ofstream:                   Files.
  1162. * ofstream::ofstream:                   Files.
  1163. * ofstream::ofstream:                   Files.
  1164. * ofstream::open:                       Files.
  1165. * ofstream::~ofstream:                  Files.
  1166. * ostream:                              Files.
  1167. * ostream::form:                        Writing.
  1168. * ostream::opfx:                        Ostream Housekeeping.
  1169. * ostream::osfx:                        Ostream Housekeeping.
  1170. * ostream::ostream:                     Ostream.
  1171. * ostream::ostream:                     Ostream.
  1172. * ostream::put:                         Writing.
  1173. * ostream::seekp:                       Output Position.
  1174. * ostream::seekp:                       Output Position.
  1175. * ostream::tellp:                       Output Position.
  1176. * ostream::vform:                       Writing.
  1177. * ostream::write:                       Writing.
  1178. * ostrstream:                           Strings.
  1179. * ostrstream:                           Files and Strings.
  1180. * ostrstream::freeze:                   Strings.
  1181. * ostrstream::frozen:                   Strings.
  1182. * ostrstream::ostrstream:               Strings.
  1183. * ostrstream::ostrstream:               Strings.
  1184. * ostrstream::pcount:                   Strings.
  1185. * ostrstream::str:                      Strings.
  1186. * put area:                             Areas.
  1187. * setbase:                              Manipulators.
  1188. * setfill:                              Manipulators.
  1189. * setprecision:                         Format Control.
  1190. * setprecision:                         Manipulators.
  1191. * setting ios::precision:               Format Control.
  1192. * setting ios::width:                   Format Control.
  1193. * setw:                                 Manipulators.
  1194. * setw:                                 Format Control.
  1195. * streambuf::scan:                      Formatting.
  1196. * streambuf::vform:                     Formatting.
  1197. * streambuf::vform:                     Formatting.
  1198. * streambuf::vscan:                     Formatting.
  1199. * streambuffer::seekmark:               Backing Up.
  1200. * streammarker::delta:                  Backing Up.
  1201. * streammarker::delta:                  Backing Up.
  1202. * streammarker::streammarker:           Backing Up.
  1203. * strstream:                            Strings.
  1204. * strstreambase:                        Strings.
  1205. * strstreambase::rdbuf:                 Strings.
  1206. * strstreambuf:                         Strings.
  1207. * ws:                                   Manipulators.
  1208. Tag Table:
  1209. Node: Top
  1210. Node: Introduction
  1211. Node: Copying
  1212. Node: Acknowledgements
  1213. Node: Operators
  1214. Node: Streams
  1215. Node: Ios
  1216. Node: States
  1217. Node: Format Control
  1218. 12064
  1219. Node: Manipulators
  1220. 17225
  1221. Node: Extending
  1222. 19198
  1223. Node: Synchronization
  1224. 20997
  1225. Node: Streambuf from Ios
  1226. 22311
  1227. Node: Ostream
  1228. 22661
  1229. Node: Writing
  1230. 23795
  1231. Node: Output Position
  1232. 25172
  1233. Node: Ostream Housekeeping
  1234. 26330
  1235. Node: Istream
  1236. 27586
  1237. Node: Char Input
  1238. 28963
  1239. Node: String Input
  1240. 29559
  1241. Node: Input Position
  1242. 33067
  1243. Node: Istream Housekeeping
  1244. 34274
  1245. Node: Iostream
  1246. 36579
  1247. Node: Files and Strings
  1248. 37870
  1249. Node: Files
  1250. 38497
  1251. Node: Strings
  1252. 43121
  1253. Node: Streambuf
  1254. 45567
  1255. Node: Areas
  1256. 46405
  1257. Node: Formatting
  1258. 46879
  1259. Node: Stdiobuf
  1260. 48288
  1261. Node: Backing Up
  1262. 49232
  1263. Node: Indirectbuf
  1264. 51501
  1265. Node: Stdio
  1266. 52043
  1267. Node: Index
  1268. 53071
  1269. End Tag Table
  1270.