Initial revision

git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@14877 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 1971 insertions, 0 deletions

diff --git a/libio/iostream.texi b/libio/iostream.texi
new file mode 100644
index 00000000000..54ccced6e71
--- /dev/null
+++ b/libio/iostream.texi
@@ -0,0 +1,1971 @@
+\input texinfo                                 @c -*-Texinfo-*-
+@c Copyright (c) 1993 Free Software Foundation, Inc.
+
+@c %**start of header 
+@setfilename iostream.info
+@settitle The GNU C++ Iostream Library
+@setchapternewpage odd
+@c %**end of header
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* iostream: (iostream).                    The C++ input/output facility.
+END-INFO-DIR-ENTRY
+@end format
+
+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.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+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.
+@end ifinfo
+
+@finalout
+@syncodeindex fn cp
+@syncodeindex vr cp
+
+@titlepage
+@title The GNU C++ Iostream Library
+@subtitle Reference Manual for @code{libio} Version 0.64
+@sp 3
+@author Per Bothner @hfill @code{bothner@@cygnus.com}
+@author Cygnus Support @hfill @code{doc@@cygnus.com}
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1993 Free Software Foundation, Inc.
+
+@code{libio} includes software developed by the University of
+California, Berkeley.
+
+@code{libio} uses floating-point software written by David M. Gay, which
+includes the following notice:
+
+@quotation
+The author of this software is David M. Gay.
+
+Copyright (c) 1991 by AT&T.
+
+Permission to use, copy, modify, and distribute this software for any
+purpose without fee is hereby granted, provided that this entire notice
+is included in all copies of any software which is or includes a copy
+or modification of this software and in all copies of the supporting
+documentation for such software.
+
+THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTY.  IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY
+REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
+OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
+@end quotation
+
+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.
+@end titlepage
+
+@ifinfo
+@node Top
+@top The GNU C++ Iostream Library
+
+This file provides reference information on the GNU C++ iostream library
+(@code{libio}), version 0.64.
+
+@menu
+* Introduction::
+* Operators::			Operators and default streams.
+* Streams::			Stream classes.
+* Files and Strings::		Classes for files and strings.
+* Streambuf::			Using the streambuf layer.
+* Stdio::			C input and output.
+* Index::
+@end menu
+@end ifinfo
+
+@node Introduction
+@chapter Introduction
+
+The iostream classes implement most of the features of AT&T version 2.0
+iostream library classes, and most of the features of the ANSI X3J16
+library draft (which is based on the AT&T design).
+
+This manual is meant as a reference; for tutorial material on iostreams,
+see the corresponding section of any recent popular introduction to C++.
+
+@menu
+* Copying::		Special GNU licensing terms for libio.
+* Acknowledgements::	Contributors to GNU iostream.
+@end menu
+
+@node Copying
+@section Licensing terms for @code{libio}
+
+Since the @code{iostream} classes are so fundamental to standard C++,
+the Free Software Foundation has agreed to a special exception to its
+standard license, when you link programs with @code{libio.a}:
+
+@quotation
+As a special exception, if you link this library with files
+compiled with a GNU compiler to produce an executable, this does not cause
+the resulting executable to be covered by the GNU General Public License.
+This exception does not however invalidate any other reasons why
+the executable file might be covered by the GNU General Public License.
+@end quotation
+
+The code is under the @sc{gnu} General Public License (version 2) for
+all other purposes than linking with this library; that means that you
+can modify and redistribute the code as usual, but remember that if you
+do, your modifications, and anything you link with the modified code,
+must be available to others on the same terms.
+
+These functions are also available as part of the @code{libg++}
+library; if you link with that library instead of @code{libio}, the
+@sc{gnu} Library General Public License applies.
+
+@node Acknowledgements
+@section Acknowledgements
+
+Per Bothner wrote most of the @code{iostream} library, but some portions
+have their origins elsewhere in the free software community.  Heinz
+Seidl wrote the IO manipulators.  The floating-point conversion software
+is by David M. Gay of AT&T.  Some code was derived from parts of BSD
+4.4, which was written at the University of California, Berkeley.
+
+The iostream classes are found in the @code{libio} library.  An early
+version was originally distributed in @code{libg++}, and they are still
+included there as well, for convenience if you need other @code{libg++}
+classes.  Doug Lea was the original author of @code{libg++}, and some of
+the file-management code still in @code{libio} is his.
+
+Various people found bugs or offered suggestions.  Hongjiu Lu worked
+hard to use the library as the default stdio implementation for Linux,
+and has provided much stress-testing of the library.
+
+@node Operators
+@chapter Operators and Default Streams
+
+The @sc{gnu} iostream library, @file{libio}, implements the standard
+input and output facilities for C++.  These facilities are roughly
+analogous (in their purpose and ubiquity, at least) with those defined
+by the C @file{stdio} functions.
+
+Although these definitions come from a library, rather than being part
+of the ``core language'', they are sufficiently central to be specified
+in the latest working papers for C++.
+
+You can use two operators defined in this library for basic input and
+output operations.  They are familiar from any C++ introductory
+textbook: @code{<<} for output, and @code{>>} for input.  (Think of data
+flowing in the direction of the ``arrows''.)
+
+These operators are often used in conjunction with three streams that
+are open by default: 
+
+@deftypevar ostream cout
+The standard output stream, analogous to the C @code{stdout}.
+@end deftypevar
+
+@deftypevar istream cin
+The standard input stream, analogous to the C @code{stdin}.
+@end deftypevar
+
+@deftypevar ostream cerr
+An alternative output stream for errors, analogous to the C
+@code{stderr}.
+@end deftypevar
+
+@noindent
+For example, this bare-bones C++ version of the traditional ``hello''
+program uses @code{<<} and @code{cout}:
+
+@example
+#include <iostream.h>
+
+int main(int argc, char **argv)
+@{
+  cout << "Well, hi there.\n";
+  return 0;
+@}
+@end example
+
+Casual use of these operators may be seductive, but---other than in
+writing throwaway code for your own use---it is not necessarily simpler
+than managing input and output in any other language.  For example,
+robust code should check the state of the input and output streams
+between operations (for example, using the method @code{good}).
+@xref{States,,Checking the state of a stream}.  You may also need to
+adjust maximum input or output field widths, using manipulators like
+@code{setw} or @code{setprecision}.
+
+@defop Operator ostream <<
+Write output to an open output stream of class @code{ostream}.
+Defined by this library on any @var{object} of a C++ primitive type, and
+on other classes of the library.  You can overload the definition for any
+of your own applications' classes.
+
+Returns a reference to the implied argument @code{*this} (the open stream it
+writes on), permitting statements like
+@example
+cout << "The value of i is " << i << "\n";
+@end example
+@end defop
+
+@defop Operator istream >>
+Read input from an open input stream of class @code{istream}.  Defined
+by this library on primitive numeric, pointer, and string types; you can
+extend the definition for any of your own applications' classes.
+
+Returns a reference to the implied argument @code{*this} (the open stream
+it reads), permitting multiple inputs in one statement.
+@end defop
+
+@node Streams
+@chapter Stream Classes
+
+The previous chapter referred in passing to the classes @code{ostream}
+and @code{istream}, for output and input respectively.  These classes
+share certain properties, captured in their base class @code{ios}.
+
+@menu
+* Ios::       Shared properties.
+* Ostream::   Managing output streams.
+* Istream::   Managing input streams.
+* Iostream::  Input and output together.
+@end menu
+
+@node Ios
+@section Shared properties: class @code{ios}
+
+The base class @code{ios} provides methods to test and manage the state
+of input or output streams.
+
+@code{ios} delegates the job of actually reading and writing bytes to
+the abstract class @code{streambuf}, which is designed to provide
+buffered streams (compatible with C, in the @sc{gnu} implementation).
+@xref{Streambuf,,Using the @code{streambuf} layer}, for information on
+the facilities available at the @code{streambuf} level.
+
+@deftypefn Constructor {} ios::ios ([streambuf* @var{sb} @w{[, ostream*} @var{tie}])
+The @code{ios} constructor by default initializes a new @code{ios}, and
+if you supply a @code{streambuf} @var{sb} to associate with it, sets the
+state @code{good} in the new @code{ios} object.  It also sets the
+default properties of the new object.
+
+@ignore
+@c FIXME--future: this (a) doesn't work, (b) is controversial at ANSI
+An @code{ios} without a @code{streambuf} has the state @code{bad} until
+you supply a @code{streambuf}; you can do that by assigning a new value
+to the @code{ios} with @samp{=}.
+@end ignore
+
+You can also supply an optional second argument @var{tie} to the
+constructor: if present, it is an initial value for @code{ios::tie}, to
+associate the new @code{ios} object with another stream.
+@end deftypefn
+
+@deftypefn Destructor {} ios::~ios ()
+The @code{ios} destructor is virtual, permitting application-specific
+behavior when a stream is closed---typically, the destructor frees any
+storage associated with the stream and releases any other associated
+objects.
+@end deftypefn
+
+@c FIXME-future:  Is @deftypefn really the best way of displaying these?
+
+@c FIXME-future: Undocumented: ios::_throw_failure, ios::exceptions; things
+@c controlled by _STREAM_COMPAT; ios::Init; ios::_IO_fix_vtable.
+
+@menu
+* States::		Checking the state of a stream.
+* Format Control::	Choices in formatting.
+* Manipulators::	Convenient ways of changing stream properties.
+* Extending::		Extended data fields.
+* Synchronization::	Synchronizing related streams.
+* Streambuf from Ios::	Reaching the underlying streambuf.
+@end menu
+
+@node States
+@subsection Checking the state of a stream
+
+Use this collection of methods to test for (or signal) errors and other
+exceptional conditions of streams:
+
+@deftypefn Method {ios::operator void*} () const
+You can do a quick check on the state of the most recent operation on a
+stream by examining a pointer to the stream itself.  The pointer is
+arbitrary except for its truth value; it is true if no failures have
+occurred (@code{ios::fail} is not true).  For example, you might ask for
+input on @code{cin} only if all prior output operations succeeded:
+
+@example
+if (cout)
+@{
+  // Everything OK so far
+  cin >> new_value;
+  @dots{}
+@}
+@end example
+@end deftypefn
+
+@deftypefn Method {ios::operator !} () const
+In case it is more convenient to check whether something has failed, the
+operator @code{!} returns true if @code{ios::fail} is true (an operation
+has failed).  For example,
+you might issue an error message if input failed:
+
+@example
+if (!cin)
+@{
+  // Oops
+  cerr << "Eh?\n";
+@}
+@end example
+@end deftypefn
+
+@deftypefn Method iostate ios::rdstate () const
+Return the state flags for this stream.  The value is from the
+enumeration @code{iostate}.  You can test for any combination of
+
+@vtable @code
+@item goodbit
+There are no indications of exceptional states on this stream.
+
+@item eofbit
+End of file.
+
+@item failbit
+An operation has failed on this stream; this usually indicates bad
+format of input.
+
+@item badbit
+The stream is unusable.
+@end vtable
+@end deftypefn
+
+@deftypefn Method void ios::setstate (iostate @var{state})
+@findex ios::set
+Set the state flag for this stream to @var{state} @emph{in addition to}
+any state flags already set.  Synonym (for upward compatibility):
+@code{ios::set}.
+
+See @code{ios::clear} to set the stream state without regard to existing
+state flags.  See @code{ios::good}, @code{ios::eof}, @code{ios::fail},
+and @code{ios::bad}, to test the state.
+@end deftypefn
+
+@deftypefn Method int ios::good () const
+Test the state flags associated with this stream; true if no error
+indicators are set.
+@end deftypefn
+
+@deftypefn Method int ios::bad () const
+Test whether a stream is marked as unusable.  (Whether
+@code{ios::badbit} is set.)
+@end deftypefn
+
+@deftypefn Method int ios::eof () const
+True if end of file was reached on this stream.  (If @code{ios::eofbit}
+is set.)
+@end deftypefn
+
+@deftypefn Method int ios::fail () const
+Test for any kind of failure on this stream: @emph{either} some
+operation failed, @emph{or} the stream is marked as bad.  (If either
+@code{ios::failbit} or @code{ios::badbit} is set.)
+@end deftypefn
+
+@deftypefn Method void ios::clear (iostate @var{state})
+@c FIXME-future: There is some complication to do with buffering and _throw_failure
+Set the state indication for this stream to the argument @var{state}.
+You may call @code{ios::clear} with no argument, in which case the state
+is set to @code{good} (no errors pending).
+
+See @code{ios::good}, @code{ios::eof}, @code{ios::fail}, and
+@code{ios::bad}, to test the state; see @code{ios::set} or
+@code{ios::setstate} for an alternative way of setting the state.
+@end deftypefn
+
+@node Format Control
+@subsection Choices in formatting
+
+These methods control (or report on) settings for some details of
+controlling streams, primarily to do with formatting output:
+
+@deftypefn Method char ios::fill () const
+Report on the padding character in use.
+@end deftypefn
+
+@deftypefn Method char ios::fill (char @var{padding})
+Set the padding character.  You can also use the manipulator
+@code{setfill}.  @xref{Manipulators,,Changing stream properties in
+expressions}.
+
+Default: blank.
+@end deftypefn
+
+@deftypefn Method int ios::precision () const
+Report the number of significant digits currently in use for output of
+floating point numbers.
+
+Default: @code{6}.
+@end deftypefn
+
+@deftypefn Method int ios::precision (int @var{signif})
+Set the number of significant digits (for input and output numeric
+conversions) to @var{signif}.
+
+@findex setprecision
+@cindex setting @code{ios::precision}
+You can also use the manipulator @code{setprecision} for this purpose.
+@xref{Manipulators,,Changing stream properties using manipulators}.
+@end deftypefn
+
+@deftypefn Method int ios::width () const
+Report the current output field width setting (the number of
+characters to write on the next @samp{<<} output operation).
+
+Default: @code{0}, which means to use as many characters as necessary.
+@end deftypefn
+
+@deftypefn Method int ios::width (int @var{num})
+Set the input field width setting to @var{num}.  Return the
+@emph{previous} value for this stream.
+
+@findex setw
+@cindex setting @code{ios::width}
+This value resets to zero (the default) every time you use @samp{<<}; it is
+essentially an additional implicit argument to that operator.  You can
+also use the manipulator @code{setw} for this purpose.
+@xref{Manipulators,,Changing stream properties using manipulators}.
+@end deftypefn
+
+@need 2000
+@deftypefn Method fmtflags ios::flags () const
+Return the current value of the complete collection of flags controlling
+the format state.  These are the flags and their meanings when set:
+
+@vtable @code
+@item ios::dec
+@itemx ios::oct
+@itemx ios::hex
+What numeric base to use in converting integers from internal to display
+representation, or vice versa: decimal, octal, or hexadecimal,
+respectively.  (You can change the base using the manipulator
+@code{setbase}, or any of the manipulators @code{dec}, @code{oct}, or
+@code{hex}; @pxref{Manipulators,,Changing stream properties in
+expressions}.)
+
+On input, if none of these flags is set, read numeric constants
+according to the prefix: decimal if no prefix (or a @samp{.} suffix),
+octal if a @samp{0} prefix is present, hexadecimal if a @samp{0x} prefix
+is present.
+
+Default: @code{dec}.
+
+@item ios::fixed
+Avoid scientific notation, and always show a fixed number of digits after
+the decimal point, according to the output precision in effect.
+Use @code{ios::precision} to set precision.
+
+@item ios::left
+@itemx ios::right
+@itemx ios::internal
+Where output is to appear in a fixed-width field; left-justified,
+right-justified, or with padding in the middle (e.g. between a numeric
+sign and the associated value), respectively.
+
+@item ios::scientific
+Use scientific (exponential) notation to display numbers.
+
+@item ios::showbase
+Display the conventional prefix as a visual indicator of the conversion
+base: no prefix for decimal, @samp{0} for octal, @samp{0x} for hexadecimal.
+
+@item ios::showpoint
+Display a decimal point and trailing zeros after it to fill out numeric
+fields, even when redundant.
+
+@item ios::showpos
+Display a positive sign on display of positive numbers.
+
+@item ios::skipws
+Skip white space.  (On by default).
+
+@item ios::stdio
+Flush the C @code{stdio} streams @code{stdout} and @code{stderr} after
+each output operation (for programs that mix C and C++ output conventions).
+
+@item ios::unitbuf
+Flush after each output operation.
+
+@item ios::uppercase
+Use upper-case characters for the non-numeral elements in numeric
+displays; for instance, @samp{0X7A} rather than @samp{0x7a}, or
+@samp{3.14E+09} rather than @samp{3.14e+09}.
+@end vtable
+@end deftypefn
+
+@deftypefn Method fmtflags ios::flags (fmtflags @var{value})
+Set @var{value} as the complete collection of flags controlling the
+format state.  The flag values are described under @samp{ios::flags ()}.
+
+Use @code{ios::setf} or @code{ios::unsetf} to change one property at a
+time.
+@end deftypefn
+
+@deftypefn Method fmtflags ios::setf (fmtflags @var{flag})
+Set one particular flag (of those described for @samp{ios::flags ()};
+return the complete collection of flags @emph{previously} in effect.
+(Use @code{ios::unsetf} to cancel.)
+@end deftypefn
+
+@deftypefn Method fmtflags ios::setf (fmtflags @var{flag}, fmtflags @var{mask})
+Clear the flag values indicated by @var{mask}, then set any of them that
+are also in @var{flag}.  (Flag values are described for @samp{ios::flags
+()}.)  Return the complete collection of flags @emph{previously} in
+effect.  (See @code{ios::unsetf} for another way of clearing flags.)
+@end deftypefn
+
+@deftypefn Method fmtflags ios::unsetf (fmtflags @var{flag})
+Make certain @var{flag} (a combination of flag values described for
+@samp{ios::flags ()}) is not set for this stream; converse of
+@code{ios::setf}.  Returns the old values of those flags.
+@c FIXME-future: should probably be fixed to give same result as setf.
+@end deftypefn
+
+@node Manipulators
+@subsection Changing stream properties using manipulators
+
+For convenience, @var{manipulators} provide a way to change certain
+properties of streams, or otherwise affect them, in the middle of
+expressions involving @samp{<<} or @samp{>>}.  For example, you might
+write
+
+@example
+cout << "|" << setfill('*') << setw(5) << 234 << "|";
+@end example
+
+@noindent
+to produce @samp{|**234|} as output.
+
+@deftypefn Manipulator {} ws
+Skip whitespace.
+@end deftypefn
+
+@deftypefn Manipulator {} flush
+Flush an output stream.  For example, @samp{cout << @dots{} <<flush;}
+has the same effect as @samp{cout << @dots{}; cout.flush();}.
+@end deftypefn
+
+@deftypefn Manipulator {} endl
+Write an end of line character @samp{\n}, then flushes the output stream.
+@end deftypefn
+
+@deftypefn Manipulator {} ends
+Write @samp{\0} (the string terminator character).
+@end deftypefn
+
+@deftypefn Manipulator {} setprecision (int @var{signif})
+You can change the value of @code{ios::precision} in @samp{<<}
+expressions with the manipulator @samp{setprecision(@var{signif})}; for
+example,
+
+@example
+cout << setprecision(2) << 4.567;
+@end example
+
+@noindent
+prints @samp{4.6}.  Requires @file{#include <iomanip.h>}.
+@end deftypefn
+
+@deftypefn Manipulator {} setw (int @var{n})
+You can change the value of @code{ios::width} in @samp{<<} expressions
+with the manipulator @samp{setw(@var{n})}; for example,
+
+@example
+cout << setw(5) << 234;
+@end example
+
+@noindent
+prints @w{@samp{  234}} with two leading blanks.  Requires @file{#include
+<iomanip.h>}.
+@end deftypefn
+
+@deftypefn Manipulator {} setbase (int @var{base})
+Where @var{base} is one of @code{10} (decimal), @code{8} (octal), or
+@code{16} (hexadecimal), change the base value for numeric
+representations.  Requires @file{#include <iomanip.h>}.
+@end deftypefn
+
+@deftypefn Manipulator {} dec
+Select decimal base; equivalent to @samp{setbase(10)}.
+@end deftypefn
+
+@deftypefn Manipulator {} hex
+Select hexadecimal base; equivalent to @samp{setbase(16)}.
+@end deftypefn
+
+@deftypefn Manipulator {} oct
+Select octal base; equivalent to @samp{setbase(8)}.
+@end deftypefn
+
+@deftypefn Manipulator {} setfill (char @var{padding})
+Set the padding character, in the same way as @code{ios::fill}.
+Requires @file{#include <iomanip.h>}.
+@end deftypefn
+
+@node Extending
+@subsection Extended data fields
+
+A related collection of methods allows you to extend this collection of
+flags and parameters for your own applications, without risk of conflict
+between them:
+
+@deftypefn Method {static fmtflags} ios::bitalloc ()
+Reserve a bit (the single bit on in the result) to use as a flag.  Using
+@code{bitalloc} guards against conflict between two packages that use
+@code{ios} objects for different purposes.
+
+This method is available for upward compatibility, but is not in the
+@sc{ansi} working paper.  The number of bits available is limited; a
+return value of @code{0} means no bit is available.
+@end deftypefn
+
+@deftypefn Method {static int} ios::xalloc ()
+Reserve space for a long integer or pointer parameter.  The result is a
+unique nonnegative integer.  You can use it as an index to
+@code{ios::iword} or @code{ios::pword}.  Use @code{xalloc} to arrange
+for arbitrary special-purpose data in your @code{ios} objects, without
+risk of conflict between packages designed for different purposes.
+@end deftypefn
+
+@deftypefn Method long& ios::iword (int @var{index})
+Return a reference to arbitrary data, of long integer type, stored in an
+@code{ios} instance.  @var{index}, conventionally returned from
+@code{ios::xalloc}, identifies what particular data you need.
+@end deftypefn
+
+@deftypefn Method long ios::iword (int @var{index}) const
+Return the actual value of a long integer stored in an @code{ios}.
+@end deftypefn
+
+@deftypefn Method void*& ios::pword (int @var{index})
+Return a reference to an arbitrary pointer, stored in an @code{ios}
+instance.  @var{index}, originally returned from @code{ios::xalloc},
+identifies what particular pointer you need.
+@end deftypefn
+
+@deftypefn Method void* ios::pword (int @var{index}) const
+Return the actual value of a pointer stored in an @code{ios}.
+@end deftypefn
+
+@node Synchronization
+@subsection Synchronizing related streams
+
+You can use these methods to synchronize related streams with
+one another:
+
+@deftypefn Method ostream* ios::tie () const
+Report on what output stream, if any, is to be flushed before accessing
+this one.  A pointer value of @code{0} means no stream is tied.
+@end deftypefn
+
+@deftypefn Method ostream* ios::tie (ostream* @var{assoc})
+Declare that output stream @var{assoc} must be flushed before accessing
+this stream.
+@end deftypefn
+
+@deftypefn Method int ios::sync_with_stdio ([int @var{switch}])
+Unless iostreams and C @code{stdio} are designed to work together, you
+may have to choose between efficient C++ streams output and output
+compatible with C @code{stdio}.  Use @samp{ios::sync_with_stdio()} to
+select C compatibility.
+
+The argument @var{switch} is a @sc{gnu} extension; use @code{0} as the
+argument to choose output that is not necessarily compatible with C
+@code{stdio}.  The default value for @var{switch} is @code{1}.
+
+If you install the @code{stdio} implementation that comes with @sc{gnu}
+@code{libio}, there are compatible input/output facilities for both C
+and C++.  In that situation, this method is unnecessary---but you may
+still want to write programs that call it, for portability.
+@end deftypefn
+
+@node Streambuf from Ios
+@subsection Reaching the underlying @code{streambuf}
+
+Finally, you can use this method to access the underlying object:
+
+@deftypefn Method streambuf* ios::rdbuf () const
+Return a pointer to the @code{streambuf} object that underlies this
+@code{ios}.
+@end deftypefn
+
+@node Ostream
+@section Managing output streams: class @code{ostream}
+
+Objects of class @code{ostream} inherit the generic methods from
+@code{ios}, and in addition have the following methods available.
+Declarations for this class come from @file{iostream.h}.
+
+@deftypefn Constructor {} ostream::ostream ()
+The simplest form of the constructor for an @code{ostream} simply
+allocates a new @code{ios} object.
+@end deftypefn
+
+@deftypefn Constructor {} ostream::ostream (streambuf* @var{sb} @w{[, ostream} @var{tie}])
+This alternative constructor requires a first argument @var{sb} of type
+@code{streambuf*}, to use an existing open stream for output.  It also
+accepts an optional second argument @var{tie}, to specify a related
+@code{ostream*} as the initial value for @code{ios::tie}.
+
+If you give the @code{ostream} a @code{streambuf} explicitly, using
+this constructor, the @var{sb} is @emph{not} destroyed (or deleted or
+closed) when the @code{ostream} is destroyed.
+@end deftypefn
+
+@menu
+* Writing::		Writing on an ostream.
+* Output Position::	Repositioning an ostream.
+* Ostream Housekeeping:: Miscellaneous ostream utilities.
+@end menu
+
+@node Writing
+@subsection Writing on an @code{ostream}
+
+These methods write on an @code{ostream} (you may also use the operator
+@code{<<}; @pxref{Operators,,Operators and Default Streams}).
+
+@deftypefn Method ostream& ostream::put (char @var{c})
+Write the single character @var{c}.
+@end deftypefn
+
+@deftypefn Method ostream& ostream::write (@var{string}, int @var{length})
+Write @var{length} characters of a string to this @code{ostream},
+beginning at the pointer @var{string}.
+
+@var{string} may have any of these types: @code{char*}, @code{unsigned
+char*}, @code{signed char*}.
+@end deftypefn
+
+@deftypefn Method ostream& ostream::form (const char *@var{format}, ...)
+A @sc{gnu} extension, similar to @code{fprintf(@var{file},
+@var{format}, ...)}.
+
+@var{format} is a @code{printf}-style format control string, which is used
+to format the (variable number of) arguments, printing the result on
+this @code{ostream}.  See @code{ostream::vform} for a version that uses
+an argument list rather than a variable number of arguments.
+@end deftypefn
+
+@deftypefn Method ostream& ostream::vform (const char *@var{format}, va_list @var{args})
+A @sc{gnu} extension, similar to @code{vfprintf(@var{file},
+@var{format}, @var{args})}.
+
+@var{format} is a @code{printf}-style format control string, which is used
+to format the argument list @var{args}, printing the result on
+this @code{ostream}.  See @code{ostream::form} for a version that uses a
+variable number of arguments rather than an argument list.
+@end deftypefn
+
+@node Output Position
+@subsection Repositioning an @code{ostream}
+
+You can control the output position (on output streams that actually
+support positions, typically files) with these methods:
+@c FIXME-future: sort out which classes support this and which
+@c don't; fstream, filebuf?  And what is failure condition when not supported?
+
+@deftypefn Method streampos ostream::tellp ()
+Return the current write position in the stream.
+@end deftypefn
+
+@deftypefn Method ostream& ostream::seekp (streampos @var{loc})
+Reset the output position to @var{loc} (which is usually the result of a
+previous call to @code{ostream::tellp}).  @var{loc} specifies an
+absolute position in the output stream.
+@end deftypefn
+
+@deftypefn Method ostream& ostream::seekp (streamoff @var{loc}, @var{rel})
+@findex ios::seekdir
+Reset the output position to @var{loc}, relative to the beginning, end,
+or current output position in the stream, as indicated by @var{rel} (a
+value from the enumeration @code{ios::seekdir}):
+
+@vtable @code
+@item beg
+Interpret @var{loc} as an absolute offset from the beginning of the
+file.
+
+@item cur
+Interpret @var{loc} as an offset relative to the current output
+position.
+
+@item end
+Interpret @var{loc} as an offset from the current end of the output
+stream.
+@end vtable
+@end deftypefn
+
+@node Ostream Housekeeping
+@subsection Miscellaneous @code{ostream} utilities
+
+You may need to use these @code{ostream} methods for housekeeping:
+
+@deftypefn Method ostream& flush ()
+Deliver any pending buffered output for this @code{ostream}.
+@end deftypefn
+
+@deftypefn Method int ostream::opfx ()
+@code{opfx} is a @dfn{prefix} method for operations on @code{ostream}
+objects; it is designed to be called before any further processing.  See
+@code{ostream::osfx} for the converse.
+@c FIXME-future: specify sometime which methods start with opfx.
+
+@code{opfx} tests that the stream is in state @code{good}, and if so
+flushes any stream tied to this one.
+
+The result is @code{1} when @code{opfx} succeeds; else (if the stream state is
+not @code{good}), the result is @code{0}.
+@end deftypefn
+
+@deftypefn Method void ostream::osfx ()
+@code{osfx} is a @dfn{suffix} method for operations on @code{ostream}
+objects; it is designed to be called at the conclusion of any processing.  All
+the @code{ostream} methods end by calling @code{osfx}.  See
+@code{ostream::opfx} for the converse.
+
+If the @code{unitbuf} flag is set for this stream, @code{osfx} flushes
+any buffered output for it.
+
+If the @code{stdio} flag is set for this stream, @code{osfx} flushes any
+output buffered for the C output streams @file{stdout} and @file{stderr}.
+@end deftypefn
+
+@node Istream
+@section Managing input streams: class @code{istream}
+
+Class @code{istream} objects are specialized for input; as for
+@code{ostream}, they are derived from @code{ios}, so you can use any of
+the general-purpose methods from that base class.  Declarations for this
+class also come from @file{iostream.h}.
+
+@deftypefn Constructor {} istream::istream ()
+When used without arguments, the @code{istream} constructor simply
+allocates a new @code{ios} object and initializes the input counter (the
+value reported by @code{istream::gcount}) to @code{0}.
+@end deftypefn
+
+@deftypefn Constructor {} istream::istream (streambuf *@var{sb} @w{[, ostream} @var{tie}])
+You can also call the constructor with one or two arguments.  The first
+argument @var{sb} is a @code{streambuf*}; if you supply this pointer,
+the constructor uses that @code{streambuf} for input.
+You can use the second optional argument @var{tie} to specify a related
+output stream as the initial value for @code{ios::tie}.
+
+If you give the @code{istream} a @code{streambuf} explicitly, using
+this constructor, the @var{sb} is @emph{not} destroyed (or deleted or
+closed) when the @code{ostream} is destroyed.
+@end deftypefn
+
+@menu
+* Char Input::		Reading one character.
+* String Input::	Reading strings.
+* Input Position::	Repositioning an istream.
+* Istream Housekeeping:: Miscellaneous istream utilities.
+@end menu
+
+@node Char Input
+@subsection Reading one character
+
+Use these methods to read a single character from the input stream:
+
+@deftypefn Method int istream::get ()
+Read a single character (or @code{EOF}) from the input stream, returning
+it (coerced to an unsigned char) as the result.
+@end deftypefn
+
+@deftypefn Method istream& istream::get (char& @var{c})
+Read a single character from the input stream, into @code{&@var{c}}.
+@end deftypefn
+
+@deftypefn Method int istream::peek ()
+Return the next available input character, but @emph{without} changing
+the current input position.
+@end deftypefn
+
+@node String Input
+@subsection Reading strings
+
+Use these methods to read strings (for example, a line at a time) from
+the input stream:
+
+@deftypefn Method istream& istream::get (char* @var{c}, int @var{len} @w{[, char} @var{delim}])
+Read a string from the input stream, into the array at @var{c}.
+
+The remaining arguments limit how much to read: up to @samp{len-1}
+characters, or up to (but not including) the first occurrence in the
+input of a particular delimiter character @var{delim}---newline
+(@code{\n}) by default.  (Naturally, if the stream reaches end of file
+first, that too will terminate reading.)
+
+If @var{delim} was present in the input, it remains available as if
+unread; to discard it instead, see @code{iostream::getline}.
+
+@code{get} writes @samp{\0} at the end of the string, regardless
+of which condition terminates the read.
+@end deftypefn
+
+@deftypefn Method istream& istream::get (streambuf& @var{sb} @w{[, char} @var{delim}])
+Read characters from the input stream and copy them on the
+@code{streambuf} object @var{sb}.  Copying ends either just before the
+next instance of the delimiter character @var{delim} (newline @code{\n}
+by default), or when either stream ends.   If @var{delim} was present in
+the input, it remains available as if unread.
+@end deftypefn
+
+@deftypefn Method istream& istream::getline (@var{charptr}, int @var{len} @w{[, char} @var{delim}])
+Read a line from the input stream, into the array at @var{charptr}.
+@var{charptr} may be any of three kinds of pointer: @code{char*},
+@code{unsigned char*}, or @code{signed char*}.
+
+The remaining arguments limit how much to read: up to (but not
+including) the first occurrence in the input of a line delimiter
+character @var{delim}---newline (@code{\n}) by default, or up to
+@samp{len-1} characters (or to end of file, if that happens sooner).
+
+If @code{getline} succeeds in reading a ``full line'', it also discards
+the trailing delimiter character from the input stream.  (To preserve it
+as available input, see the similar form of @code{iostream::get}.)
+
+If @var{delim} was @emph{not} found before @var{len} characters or end
+of file, @code{getline} sets the @code{ios::fail} flag, as well as the
+@code{ios::eof} flag if appropriate.
+
+@code{getline} writes a null character at the end of the string, regardless
+of which condition terminates the read.
+@end deftypefn
+
+@deftypefn Method istream& istream::read (@var{pointer}, int @var{len})
+Read @var{len} bytes into the location at @var{pointer}, unless the
+input ends first.
+
+@var{pointer} may be of type @code{char*}, @code{void*}, @code{unsigned
+char*}, or @code{signed char*}.
+
+If the @code{istream} ends before reading @var{len} bytes, @code{read}
+sets the @code{ios::fail} flag.
+@end deftypefn
+
+@deftypefn Method istream& istream::gets (char **@var{s} @w{[, char} @var{delim}])
+A @sc{gnu} extension, to read an arbitrarily long string
+from the current input position to the next instance of the @var{delim}
+character (newline @code{\n} by default).
+
+To permit reading a string of arbitrary length, @code{gets} allocates
+whatever memory is required.  Notice that the first argument @var{s} is
+an address to record a character pointer, rather than the pointer
+itself.
+@end deftypefn
+
+@deftypefn Method istream& istream::scan (const char *format ...)
+A @sc{gnu} extension, similar to @code{fscanf(@var{file},
+@var{format}, ...)}.  The @var{format} is a @code{scanf}-style format
+control string, which is used to read the variables in the remainder of
+the argument list from the @code{istream}.
+@end deftypefn
+
+@deftypefn Method istream& istream::vscan (const char *format, va_list args)
+Like @code{istream::scan}, but takes a single @code{va_list} argument.
+@end deftypefn
+
+@node Input Position
+@subsection Repositioning an @code{istream}
+
+Use these methods to control the current input position:
+
+@deftypefn Method streampos istream::tellg ()
+Return the current read position, so that you can save it and return to
+it later with @code{istream::seekg}.
+@end deftypefn
+
+@deftypefn Method istream& istream::seekg (streampos @var{p})
+Reset the input pointer (if the input device permits it) to @var{p},
+usually the result of an earlier call to @code{istream::tellg}.
+@end deftypefn
+
+@deftypefn Method istream& istream::seekg (streamoff @var{offset}, ios::seek_dir @var{ref})
+Reset the input pointer (if the input device permits it) to @var{offset}
+characters from the beginning of the input, the current position, or the
+end of input.  Specify how to interpret @var{offset} with one of these
+values for the second argument:
+
+@vtable @code
+@item ios::beg
+Interpret @var{loc} as an absolute offset from the beginning of the
+file.
+
+@item ios::cur
+Interpret @var{loc} as an offset relative to the current output
+position.
+
+@item ios::end
+Interpret @var{loc} as an offset from the current end of the output
+stream.
+@end vtable
+@end deftypefn
+
+@node Istream Housekeeping
+@subsection Miscellaneous @code{istream} utilities
+
+Use these methods for housekeeping on @code{istream} objects:
+
+@deftypefn Method int istream::gcount ()
+Report how many characters were read from this @code{istream} in the
+last unformatted input operation.
+@c FIXME! Define "unformatted input" somewhere...
+@end deftypefn
+
+@deftypefn Method int istream::ipfx (int @var{keepwhite})
+Ensure that the @code{istream} object is ready for reading; check for
+errors and end of file and flush any tied stream.  @code{ipfx} skips
+whitespace if you specify @code{0} as the @var{keepwhite}
+argument, @emph{and} @code{ios::skipws} is set for this stream.
+
+To avoid skipping whitespace (regardless of the @code{skipws} setting on
+the stream), use @code{1} as the argument.
+
+Call @code{istream::ipfx} to simplify writing your own methods for reading
+@code{istream} objects.
+@end deftypefn
+
+@deftypefn Method void istream::isfx ()
+A placeholder for compliance with the draft @sc{ansi} standard; this
+method does nothing whatever.
+
+If you wish to write portable standard-conforming code on @code{istream}
+objects, call @code{isfx} after any operation that reads from an
+@code{istream}; if @code{istream::ipfx} has any special effects that
+must be cancelled when done, @code{istream::isfx} will cancel them.
+@end deftypefn
+
+@deftypefn Method istream& istream::ignore ([int @var{n}] @w{[, int} @var{delim}])
+Discard some number of characters pending input.  The first optional
+argument @var{n} specifies how many characters to skip.  The second
+optional argument @var{delim} specifies a ``boundary'' character:
+@code{ignore} returns immediately if this character appears in the
+input.
+
+By default, @var{delim} is @code{EOF}; that is, if you do not specify a
+second argument, only the count @var{n} restricts how much to ignore
+(while input is still available).
+
+If you do not specify how many characters to ignore, @code{ignore}
+returns after discarding only one character.
+@end deftypefn
+
+@deftypefn Method istream& istream::putback (char @var{ch})
+Attempts to back up one character, replacing the character backed-up
+over by @var{ch}.  Returns @code{EOF} if this is not allowed.  Putting
+back the most recently read character is always allowed.  (This method
+corresponds to the C function @code{ungetc}.)
+@end deftypefn
+
+@deftypefn Method istream& istream::unget ()
+Attempt to back up one character.
+@end deftypefn
+
+@node Iostream
+@section Input and output together: class @code{iostream}
+
+If you need to use the same stream for input and output, you can use an
+object of the class @code{iostream}, which is derived from @emph{both}
+@code{istream} and @code{ostream}.
+
+The constructors for @code{iostream} behave just like the constructors
+for @code{istream}.
+
+@deftypefn Constructor {} iostream::iostream ()
+When used without arguments, the @code{iostream} constructor simply
+allocates a new @code{ios} object, and initializes the input counter
+(the value reported by @code{istream::gcount}) to @code{0}.
+@end deftypefn
+
+@deftypefn Constructor {} iostream::iostream (streambuf* @var{sb} @w{[, ostream*} @var{tie}])
+You can also call a constructor with one or two arguments.  The first
+argument @var{sb} is a @code{streambuf*}; if you supply this pointer,
+the constructor uses that @code{streambuf} for input and output.
+
+You can use the optional second argument @var{tie} (an @code{ostream*})
+to specify a related output stream as the initial value for
+@code{ios::tie}.
+@end deftypefn
+
+@cindex @code{iostream} destructor
+@cindex destructor for @code{iostream}
+As for @code{ostream} and @code{istream}, @code{iostream} simply uses
+the @code{ios} destructor.  However, an @code{iostream} is not deleted by
+its destructor.
+
+You can use all the @code{istream}, @code{ostream}, and @code{ios}
+methods with an @code{iostream} object.
+
+@node Files and Strings
+@chapter Classes for Files and Strings
+
+There are two very common special cases of input and output: using files,
+and using strings in memory.
+
+@code{libio} defines four specialized classes for these cases:
+
+@ftable @code
+@item ifstream
+Methods for reading files.
+
+@item ofstream
+Methods for writing files.
+
+@item istrstream
+Methods for reading strings from memory.
+
+@item ostrstream
+Methods for writing strings in memory.
+@end ftable
+
+@menu
+* Files::	Reading and writing files.
+* Strings::	Reading and writing strings in memory.
+@end menu
+
+@node Files
+@section Reading and writing files
+
+These methods are declared in @file{fstream.h}.
+
+@findex ifstream
+@cindex class @code{ifstream}
+You can read data from class @code{ifstream} with any operation from class
+@code{istream}.  There are also a few specialized facilities:
+
+@deftypefn Constructor {} ifstream::ifstream ()
+Make an @code{ifstream} associated with a new file for input.  (If you
+use this version of the constructor, you need to call
+@code{ifstream::open} before actually reading anything)
+@end deftypefn
+
+@deftypefn Constructor {} ifstream::ifstream (int @var{fd})
+Make an @code{ifstream} for reading from a file that was already open,
+using file descriptor @var{fd}.  (This constructor is compatible with
+other versions of iostreams for @sc{posix} systems, but is not part of
+the @sc{ansi} working paper.)
+@end deftypefn
+
+@deftypefn Constructor {} ifstream::ifstream (const char* @var{fname} @w{[, int} @var{mode} @w{[, int} @var{prot}]])
+Open a file @code{*@var{fname}} for this @code{ifstream} object.
+
+By default, the file is opened for input (with @code{ios::in} as
+@var{mode}).  If you use this constructor, the file will be closed when
+the @code{ifstream} is destroyed.
+
+You can use the optional argument @var{mode} to specify how to open the
+file, by combining these enumerated values (with @samp{|} bitwise or).
+(These values are actually defined in class @code{ios}, so that all
+file-related streams may inherit them.)  Only some of these modes are
+defined in the latest draft @sc{ansi} specification; if portability is
+important, you may wish to avoid the others.
+
+@vtable @code
+@item ios::in
+Open for input.  (Included in @sc{ansi} draft.)
+
+@item ios::out
+Open for output.  (Included in @sc{ansi} draft.)
+
+@item ios::ate
+Set the initial input (or output) position to the end of the file.
+
+@item ios::app
+Seek to end of file before each write.  (Included in @sc{ansi} draft.)
+
+@item ios::trunc
+Guarantee a fresh file; discard any contents that were previously
+associated with it.
+
+@item ios::nocreate
+Guarantee an existing file; fail if the specified file did not already
+exist.
+
+@item ios::noreplace
+Guarantee a new file; fail if the specified file already existed.
+
+@item ios::bin
+Open as a binary file (on systems where binary and text files have different
+properties, typically how @samp{\n} is mapped; included in @sc{ansi} draft).
+@end vtable
+
+@noindent
+The last optional argument @var{prot} is specific to Unix-like systems;
+it specifies the file protection (by default @samp{644}).
+@end deftypefn
+
+@deftypefn Method void ifstream::open (const char* @var{fname} @w{[, int} @var{mode} @w{[, int} @var{prot}]])
+Open a file explicitly after the associated @code{ifstream} object
+already exists (for instance, after using the default constructor).  The
+arguments, options and defaults all have the same meanings as in the
+fully specified @code{ifstream} constructor.
+@end deftypefn
+
+@findex ostream
+@cindex class @code{ostream}
+You can write data to class @code{ofstream} with any operation from class
+@code{ostream}.  There are also a few specialized facilities:
+
+@deftypefn Constructor {} ofstream::ofstream ()
+Make an @code{ofstream} associated with a new file for output.
+@end deftypefn
+
+@deftypefn Constructor {} ofstream::ofstream (int @var{fd})
+Make an @code{ofstream} for writing to a file that was already open,
+using file descriptor @var{fd}.
+@end deftypefn
+
+@deftypefn Constructor {} ofstream::ofstream (const char* @var{fname} @w{[, int} @var{mode} @w{[, int} @var{prot}]])
+Open a file @code{*@var{fname}} for this @code{ofstream} object.
+
+By default, the file is opened for output (with @code{ios::out} as @var{mode}).
+You can use the optional argument @var{mode} to specify how to open the
+file, just as described for @code{ifstream::ifstream}.
+
+The last optional argument @var{prot} specifies the file protection (by
+default @samp{644}).
+@end deftypefn
+
+@deftypefn Destructor {} ofstream::~ofstream ()
+The files associated with @code{ofstream} objects are closed when the
+corresponding object is destroyed.
+@end deftypefn
+
+@deftypefn Method void ofstream::open (const char* @var{fname} @w{[, int} @var{mode} @w{[, int} @var{prot}]])
+Open a file explicitly after the associated @code{ofstream} object
+already exists (for instance, after using the default constructor).  The
+arguments, options and defaults all have the same meanings as in the
+fully specified @code{ofstream} constructor.
+@end deftypefn
+
+@findex fstream
+@cindex class @code{fstream}
+The class @code{fstream} combines the facilities of @code{ifstream} and
+@code{ofstream}, just as @code{iostream} combines @code{istream} and
+@code{ostream}.
+
+@c FIXME-future: say something about fstream constructor, maybe.
+
+@findex fstreambase
+@cindex class @code{fstreambase}
+The class @code{fstreambase} underlies both @code{ifstream} and
+@code{ofstream}.  They both inherit this additional method:
+
+@deftypefn Method void fstreambase::close ()
+Close the file associated with this object, and set @code{ios::fail} in
+this object to mark the event.
+@end deftypefn
+
+@node Strings
+@section Reading and writing in memory
+
+@c FIXME!! Per, there's a lot of guesswork here---please check carefully!
+
+@findex istrstream
+@cindex class @code{istrstream}
+@findex ostrstream
+@cindex class @code{ostrstream}
+@findex strstream
+@cindex class @code{strstream}
+@findex strstreambase
+@cindex class @code{strstreambase}
+@findex strstreambuf
+@cindex class @code{strstreambuf}
+The classes @code{istrstream}, @code{ostrstream}, and @code{strstream}
+provide some additional features for reading and writing strings in
+memory---both static strings, and dynamically allocated strings.  The
+underlying class @code{strstreambase} provides some features common to
+all three; @code{strstreambuf} underlies that in turn.
+
+@c FIXME-future:  Document strstreambuf methods one day, when we document
+@c streambuf more fully.
+
+@deftypefn Constructor {} istrstream::istrstream (const char* @var{str} @w{[, int} @var{size}])
+Associate the new input string class @code{istrstream} with an existing
+static string starting at @var{str}, of size @var{size}.  If you do not
+specify @var{size}, the string is treated as a @code{NUL} terminated string.
+@end deftypefn
+
+@deftypefn Constructor {} ostrstream::ostrstream ()
+Create a new stream for output to a dynamically managed string, which
+will grow as needed.
+@end deftypefn
+
+@deftypefn Constructor {} ostrstream::ostrstream (char* @var{str}, int @var{size} [,int @var{mode}])
+A new stream for output to a statically defined string of length
+@var{size}, starting at @var{str}.  You may optionally specify one of
+the modes described for @code{ifstream::ifstream}; if you do not specify
+one, the new stream is simply open for output, with mode @code{ios::out}.
+@end deftypefn
+
+@deftypefn Method int ostrstream::pcount ()
+Report the current length of the string associated with this @code{ostrstream}.
+@end deftypefn
+
+@deftypefn Method char* ostrstream::str ()
+A pointer to the string managed by this @code{ostrstream}.  Implies
+@samp{ostrstream::freeze()}.
+
+Note that if you want the string to be nul-terminated,
+you must do that yourself (perhaps by writing ends to the stream).
+@end deftypefn
+
+@deftypefn Method void ostrstream::freeze ([int @var{n}])
+If @var{n} is nonzero (the default), declare that the string associated
+with this @code{ostrstream} is not to change dynamically; while frozen,
+it will not be reallocated if it needs more space, and it will not be
+deallocated when the @code{ostrstream} is destroyed.  Use
+@samp{freeze(1)} if you refer to the string as a pointer after creating
+it via @code{ostrstream} facilities.
+
+@samp{freeze(0)} cancels this declaration, allowing a dynamically
+allocated string to be freed when its @code{ostrstream} is destroyed.
+
+If this @code{ostrstream} is already static---that is, if it was created
+to manage an existing statically allocated string---@code{freeze} is
+unnecessary, and has no effect.
+@end deftypefn
+
+@deftypefn Method int ostrstream::frozen ()
+Test whether @code{freeze(1)} is in effect for this string.
+@end deftypefn
+
+@deftypefn Method strstreambuf* strstreambase::rdbuf ()
+A pointer to the underlying @code{strstreambuf}.
+@end deftypefn
+
+@node Streambuf
+@chapter Using the @code{streambuf} Layer
+
+The @code{istream} and @code{ostream} classes are meant to handle
+conversion between objects in your program and their textual representation.
+
+By contrast, the underlying @code{streambuf} class is for transferring
+raw bytes between your program, and input sources or output sinks.
+Different @code{streambuf} subclasses connect to different kinds of
+sources and sinks.
+
+The @sc{gnu} implementation of @code{streambuf} is still evolving; we
+describe only some of the highlights.
+
+@menu
+* Areas::		Areas in a streambuf.
+* Overflow::		Simple output re-direction
+* Formatting::		C-style formatting for streambuf objects.
+* Stdiobuf::		Wrappers for C stdio.
+* Procbuf::             Reading/writing from/to a pipe
+* Backing Up::		Marking and returning to a position.
+* Indirectbuf::		Forwarding I/O activity.
+@end menu
+
+@node Areas
+@section Areas of a @code{streambuf}
+
+Streambuf buffer management is fairly sophisticated (this is a
+nice way to say ``complicated'').  The standard protocol
+has the following ``areas'':
+
+@itemize @bullet
+@item
+@cindex put area
+The @dfn{put area} contains characters waiting for output.
+
+@item
+@cindex get area
+The @dfn{get area} contains characters available for reading.
+@end itemize
+
+The @sc{gnu} @code{streambuf} design extends this, but the details are
+still evolving.
+
+The following methods are used to manipulate these areas.
+These are all protected methods, which are intended to be
+used by virtual function in classes derived from @code{streambuf}.
+They are also all ANSI/ISO-standard, and the ugly names
+are traditional.
+(Note that if a pointer points to the 'end' of an area,
+it means that it points to the character after the area.)
+
+@deftypefn Method char* streambuf::pbase () const
+Returns a pointer to the start of the put area.
+@end deftypefn
+
+@deftypefn Method char* streambuf::epptr () const
+Returns a pointer to the end of the put area.
+@end deftypefn
+
+@deftypefn Method char* streambuf::pptr () const
+If @code{pptr() < epptr ()}, the @code{pptr()}
+returns a pointer to the current put position.
+(In that case, the next write will
+overwrite @code{*pptr()}, and increment @code{pptr()}.)
+Otherwise, there is no put position available
+(and the next character written will cause @code{streambuf::overflow}
+to be called).
+@end deftypefn
+
+@deftypefn Method void streambuf::pbump (int @var{N})
+Add @var{N} to the current put pointer.
+No error checking is done.
+@end deftypefn
+
+@deftypefn Method void streambuf::setp (char* @var{P}, char* @var{E})
+Sets the start of the put area to @var{P}, the end of the put area to @var{E},
+and the current put pointer to @var{P} (also).
+@end deftypefn
+
+@deftypefn Method char* streambuf::eback () const
+Returns a pointer to the start of the get area.
+@end deftypefn
+
+@deftypefn Method char* streambuf::egptr () const
+Returns a pointer to the end of the get area.
+@end deftypefn
+
+@deftypefn Method char* streambuf::gptr () const
+If @code{gptr() < egptr ()}, then @code{gptr()}
+returns a pointer to the current get position.
+(In that case the next read will read @code{*gptr()},
+and possibly increment @code{gptr()}.)
+Otherwise, there is no read position available
+(and the next read will cause @code{streambuf::underflow}
+to be called).
+@end deftypefn
+
+@deftypefn Method void streambuf:gbump (int @var{N})
+Add @var{N} to the current get pointer.
+No error checking is done.
+@end deftypefn
+
+@deftypefn Method void streambuf::setg (char* @var{B}, char* @var{P}, char* @var{E})
+Sets the start of the get area to @var{B}, the end of the get area to @var{E},
+and the current put pointer to @var{P}.
+@end deftypefn
+
+@node Overflow
+@section Simple output re-direction by redefining @code{overflow}
+
+Suppose you have a function @code{write_to_window} that
+writes characters to a @code{window} object.  If you want to use the
+ostream function to write to it, here is one (portable) way to do it.
+This depends on the default buffering (if any).
+
+@cartouche
+@smallexample
+#include <iostream.h>
+/* Returns number of characters successfully written to @var{win}. */
+extern int write_to_window (window* win, char* text, int length);
+
+class windowbuf : public streambuf @{
+    window* win;
+  public:
+    windowbuf (window* w) @{ win = w; @}
+    int sync ();
+    int overflow (int ch);
+    // Defining xsputn is an optional optimization.
+    // (streamsize was recently added to ANSI C++, not portable yet.)
+    streamsize xsputn (char* text, streamsize n);
+@};
+
+int windowbuf::sync ()
+@{ streamsize n = pptr () - pbase ();
+  return (n && write_to_window (win, pbase (), n) != n) ? EOF : 0;
+@}
+
+int windowbuf::overflow (int ch)
+@{ streamsize n = pptr () - pbase ();
+  if (n && sync ())
+    return EOF;
+  if (ch != EOF)
+    @{
+      char cbuf[1];
+      cbuf[0] = ch;
+      if (write_to_window (win, cbuf, 1) != 1)
+        return EOF;
+    @}
+  pbump (-n);  // Reset pptr().
+  return 0;
+@}
+
+streamsize windowbuf::xsputn (char* text, streamsize n)
+@{ return sync () == EOF ? 0 : write_to_window (win, text, n); @}
+
+int
+main (int argc, char**argv)
+@{
+  window *win = ...;
+  windowbuf wbuf(win);
+  ostream wstr(&wbuf);
+  wstr << "Hello world!\n";
+@}
+@end smallexample
+@end cartouche
+
+
+
+@node Formatting
+@section C-style formatting for @code{streambuf} objects
+
+The @sc{gnu} @code{streambuf} class supports @code{printf}-like
+formatting and scanning.
+
+@deftypefn Method int streambuf::form (const char *@var{format}, ...)
+Similar to @code{fprintf(@var{file}, @var{format}, ...)}.
+The @var{format} is a @code{printf}-style format control string, which is used
+to format the (variable number of) arguments, printing the result on
+the @code{this} streambuf.  The result is the number of characters printed.
+@end deftypefn
+
+@deftypefn Method int streambuf::vform (const char *@var{format}, va_list @var{args})
+Similar to @code{vfprintf(@var{file}, @var{format}, @var{args})}.
+The @var{format} is a @code{printf}-style format control string, which is used
+to format the argument list @var{args}, printing the result on
+the @code{this} streambuf.  The result is the number of characters printed.
+@end deftypefn
+
+@deftypefn Method int streambuf::scan (const char *@var{format}, ...)
+Similar to @code{fscanf(@var{file}, @var{format}, ...)}.
+The @var{format} is a @code{scanf}-style format control string, which is used
+to read the (variable number of) arguments from the @code{this} streambuf.
+The result is the number of items assigned, or @code{EOF} in case of
+input failure before any conversion.
+@end deftypefn
+
+@deftypefn Method int streambuf::vscan (const char *@var{format}, va_list @var{args})
+Like @code{streambuf::scan}, but takes a single @code{va_list} argument.
+@end deftypefn
+
+@node Stdiobuf
+@section Wrappers for C @code{stdio}
+
+A @dfn{stdiobuf} is a @code{streambuf} object that points to
+a @code{FILE} object (as defined by @code{stdio.h}).
+All @code{streambuf} operations on the @code{stdiobuf} are forwarded
+to the @code{FILE}.  Thus the @code{stdiobuf} object provides a
+wrapper around a @code{FILE}, allowing use of @code{streambuf}
+operations on a @code{FILE}.  This can be useful when mixing
+C code with C++ code.
+
+The pre-defined streams @code{cin}, @code{cout}, and @code{cerr} are
+normally implemented as @code{stdiobuf} objects that point to
+respectively @code{stdin}, @code{stdout}, and @code{stderr}.  This is
+convenient, but it does cost some extra overhead.
+
+If you set things up to use the implementation of @code{stdio} provided
+with this library, then @code{cin}, @code{cout}, and @code{cerr} will be
+set up to to use @code{stdiobuf} objects, since you get their benefits
+for free.  @xref{Stdio,,C Input and Output}.
+
+@ignore
+@c FIXME-future: setbuf is not yet documented, hence this para is not useful.
+Note that if you use @code{setbuf} to give a buffer to a @code{stdiobuf},
+that buffer will provide intermediate buffering in addition that
+whatever is done by the @code{FILE}.
+@end ignore
+
+@node Procbuf
+@section Reading/writing from/to a pipe
+
+The @dfn{procbuf} class is a @sc{gnu} extension.  It is derived from
+@code{streambuf}.  A @code{procbuf} can be @dfn{closed} (in which case
+it does nothing), or @dfn{open} (in which case it allows communicating
+through a pipe with some other program).
+
+@deftypefn Constructor {} procbuf::procbuf ()
+Creates a @code{procbuf} in a @dfn{closed} state.
+@end deftypefn
+
+@deftypefn Method procbuf* procbuf::open (const char *@var{command}, int @var{mode})
+Uses the shell (@file{/bin/sh}) to run a program specified by @var{command}.
+
+If @var{mode} is @samp{ios::in}, standard output from the program is sent
+to a pipe; you can read from the pipe by reading from the
+@code{procbuf}.  (This is similar to @w{@samp{popen(@var{command}, "r")}}.)
+
+If @var{mode} is @samp{ios::out}, output written written to the
+@code{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
+@w{@samp{popen(@var{command}, "w")}}.)
+
+The @code{procbuf} must start out in the @dfn{closed} state.
+Returns @samp{*this} on success, and @samp{NULL} on failure.
+@end deftypefn
+
+@deftypefn Constructor {} procbuf::procbuf (const char *@var{command}, int @var{mode})
+Calls @samp{procbuf::open (@var{command}, @var{mode})}.
+@end deftypefn
+
+@deftypefn Method procbuf* procbuf::close ()
+Waits for the program to finish executing,
+and then cleans up the resources used.
+Returns @samp{*this} on success, and @samp{NULL} on failure.
+@end deftypefn
+
+@deftypefn Destructor {} procbuf::~procbuf ()
+Calls @samp{procbuf::close}.
+@end deftypefn
+
+@node Backing Up
+@section Backing up
+
+The @sc{gnu} iostream library allows you to ask a @code{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:
+
+@cartouche
+@smallexample
+// 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;
+@}
+@end smallexample
+@end cartouche
+
+@deftypefn Constructor {} streammarker::streammarker (streambuf* @var{sbuf})
+Create a @code{streammarker} associated with @var{sbuf}
+that remembers the current position of the get pointer.
+@end deftypefn
+
+@deftypefn Method int streammarker::delta (streammarker& @var{mark2})
+Return the difference between the get positions corresponding
+to @code{*this} and @var{mark2} (which must point into the same
+@code{streambuffer} as @code{this}).
+@end deftypefn
+
+@deftypefn Method int streammarker::delta ()
+Return the position relative to the streambuffer's current get position.
+@end deftypefn
+
+@deftypefn Method int streambuf::seekmark (streammarker& @var{mark})
+Move the get pointer to where it (logically) was when @var{mark}
+was constructed.
+@end deftypefn
+
+@node Indirectbuf
+@section Forwarding I/O activity
+
+An @dfn{indirectbuf} is one that forwards all of its I/O requests
+to another streambuf.
+
+@ignore
+@c FIXME-future: get_stream and put_stream are so far undocumented.
+All get-related requests are sent to get_stream().
+All put-related requests are sent to put_stream().
+@end ignore
+
+An @code{indirectbuf} can be used to implement Common Lisp
+synonym-streams and two-way-streams:
+
+@example
+class synonymbuf : public indirectbuf @{
+   Symbol *sym;
+   synonymbuf(Symbol *s) @{ sym = s; @}
+   virtual streambuf *lookup_stream(int mode) @{
+       return coerce_to_streambuf(lookup_value(sym)); @}
+@};
+@end example
+
+@node Stdio
+@chapter C Input and Output
+
+@code{libio} is distributed with a complete implementation of the ANSI C
+@code{stdio} facility.  It is implemented using @code{streambuf}
+objects.  @xref{Stdiobuf,,Wrappers for C @code{stdio}}.
+
+The @code{stdio} package is intended as a replacement for the whatever
+@code{stdio} is in your C library.
+@ignore
+@c FIXME-future:  This is not useful unless we specify what problems.
+It can co-exist with C libraries that have alternate implementations of
+stdio, but there may be some problems.
+@end ignore
+Since @code{stdio} works best when you build @code{libc} to contain it, and
+that may be inconvenient, it is not installed by default.
+
+Extensions beyond @sc{ansi}:
+
+@itemize @bullet
+@item
+A stdio @code{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.
+
+@item
+If you create a new streambuf sub-class (in C++), you can use it as a
+@code{FILE} from C.  Thus the system is extensible using the standard
+@code{streambuf} protocol.
+
+@item
+You can arbitrarily mix reading and writing, without having to seek
+in between.
+
+@item
+Unbounded @code{ungetc()} buffer.
+@end itemize
+
+@ignore
+@c FIXME-future: Per says this is not ready to go public at v0.5
+@node Libio buffer management
+@chapter Libio buffer management
+
+The libio user functions present an abstract sequence of characters,
+that they read and write from.  A number of buffers are used to go
+between the user program and the abstract sequence.  These buffers are
+concrete arrays of characters that contain some sub-sequence of the
+abstract sequence.
+
+The libio buffer management protocol is fairly complex.  Its design is
+based on the C++ @code{streambuf} protocol, so that the C++
+@code{streambuf} classes can be trivially implemented on top of the
+libio protocol.
+
+The @dfn{write area} contains characters waiting for output.
+
+The @dfn{read area} contains characters available for reading.
+
+The @dfn{reserve area} is available to virtual methods.
+Usually, the get and/or put areas are part of the reserve area.
+
+The @dfn{main get area} contains characters that have
+been read in from the character source, but not yet
+read by the application.
+
+The @dfn{backup area} contains previously read data that is being saved
+because of a user request, or that have been "unread" (put back).
+@end ignore
+
+@ignore
+@c Per says this design is not finished
+@node Streambuf internals
+@chapter Streambuf internals
+
+@menu
+* Buffer management::
+* Filebuf internals::
+@end menu
+
+@node Buffer management
+@section Buffer management
+
+@subsection Areas
+
+NOTE:  This chapter is due for an update.
+
+Streambuf buffer management is fairly sophisticated (this is a
+nice way to say "complicated").  The standard protocol
+has the following "areas":
+
+@itemize @bullet
+@cindex put area
+@item
+The @dfn{put area} contains characters waiting for output.
+@cindex get area
+@item
+The @dfn{get area} contains characters available for reading.
+@cindex reserve area
+@item
+The @dfn{reserve area} is available to virtual methods.
+Usually, the get and/or put areas are part of the reserve area.
+@end itemize
+
+The @sc{gnu} @code{streambuf} design extends this by supporting two
+get areas:
+@itemize @bullet
+@cindex main get area
+@item
+The @dfn{main get area} contains characters that have
+been read in from the character source, but not yet
+read by the application.
+@cindex backup area
+@item
+The @dfn{backup area} contains previously read data that is being
+saved because of a user request, or that have been "unread" (putback).
+@end itemize
+
+The backup and the main get area are logically contiguous:  That is,
+the first character of the main get area follows the last character
+of the backup area.
+
+The @dfn{current get area} is whichever one of the backup or
+main get areas that is currently being read from.
+The other of the two is the @dfn{non-current get area}.
+
+@subsection Pointers
+
+The following @code{char*} pointers define the various areas.
+
+@deftypefn Method char* streambuf::base ()
+The start of the reserve area.
+@end deftypefn
+
+@deftypefn Method char* streambuf::ebuf ()
+The end of the reserve area.
+@end deftypefn
+
+@deftypefn Method char* streambuf::Gbase ()
+The start of the main get area.
+@end deftypefn
+
+@deftypefn Method char* streambuf::eGptr ()
+The end of the main get area.
+@end deftypefn
+
+@deftypefn Method char* streambuf::Bbase ()
+The start of the backup area.
+@end deftypefn
+
+@deftypefn Method char* streambuf::Bptr ()
+The start of the used part of the backup area.
+The area (@code{Bptr()} .. @code{eBptr()}) contains data that has been
+pushed back, while (@code{Bbase()} .. @code{eBptr()}) contains unused
+space available for future putbacks.
+@end deftypefn
+
+@deftypefn Method char* streambuf::eBptr ()
+The end of the backup area.
+@end deftypefn
+
+@deftypefn Method char* streambuf::Nbase ()
+The start of the non-current get area (either @code{main_gbase} or @code{backup_gbase}).
+@end deftypefn
+
+@deftypefn Method char* streambuf::eNptr ()
+The end of the non-current get area.
+@end deftypefn
+
+@node Filebuf internals
+@section Filebuf internals
+
+The @code{filebuf} is used a lot, so it is importamt that it be
+efficient.  It is also supports rather complex semantics.
+so let us examine its implementation.
+
+@subsection Tied read and write pointers
+
+The streambuf model allows completely independent read and write pointers.
+However, a @code{filebuf} has only a single logical pointer used
+for both reads and writes.  Since the @code{streambuf} protocol
+uses @code{gptr()} for reading and @code{pptr()} for writing,
+we map the logical file pointer into either @code{gptr()} or @code{pptr()}
+at different times.
+
+@itemize @bullet
+@item
+Reading is allowed when @code{gptr() < egptr()}, which we call get mode.
+
+@item
+Writing is allowed when @code{pptr() < epptr()}, which we call put mode.
+@end itemize
+
+@noindent
+A @code{filebuf} cannot be in get mode and put mode at the same time.
+
+We have up to two buffers:
+
+@itemize @bullet
+@item
+The backup area, defined by @code{Bbase()}, @code{Bptr()}, and @code{eBptr()}.
+This can be empty.
+
+@item
+The reserve area, which also contains the main get area.
+For an unbuffered file, the (@code{shortbuf()}..@code{shortbuf()+1}) is used,
+where @code{shortbuf()} points to a 1-byte buffer that is part of
+the @code{filebuf}.
+@end itemize
+
+@noindent
+The file system's idea of the current position is @code{eGptr()}.
+
+Characters that have been written into a buffer but not yet written
+out (flushed) to the file systems are those between @code{pbase()}
+and @code{pptr()}.
+
+The end of the valid data bytes is:
+@code{pptr() > eGptr() && pptr() < ebuf() ? pptr() : eGptr()}.
+
+If the @code{filebuf} is unbuffered or line buffered,
+the @code{eptr()} is @code{pbase()}.  This forces a call
+to @code{overflow()} on each put of a character.
+The logical @code{epptr()} is @code{epptr() ? ebuf() : NULL}.
+(If the buffer is read-only, set @code{pbase()}, @code{pptr()},
+and @code{epptr()} to @code{NULL}. NOT!)
+@end ignore
+
+@node Index
+@unnumbered Index
+@printindex cp
+
+@contents
+@bye