Return to iostream.texi CVS log

Up to [Apple XNU] / GNUtools / libg++ / libio

Annotation of GNUtools/libg++/libio/iostream.texi, revision 1.1

1.1     ! root        1: \input texinfo                                 @c -*-Texinfo-*-
        !             2: @c Copyright (c) 1993 Free Software Foundation, Inc.
        !             3: 
        !             4: @c %**start of header 
        !             5: @setfilename iostream.info
        !             6: @settitle The GNU C++ Iostream Library
        !             7: @setchapternewpage odd
        !             8: @c %**end of header
        !             9: 
        !            10: @ifinfo
        !            11: @format
        !            12: START-INFO-DIR-ENTRY
        !            13: * iostream::                    The C++ input/output facility.
        !            14: END-INFO-DIR-ENTRY
        !            15: @end format
        !            16: 
        !            17: This file describes libio, the GNU library for C++ iostreams and C stdio.
        !            18: 
        !            19: libio includes software developed by the University of California,
        !            20: Berkeley.
        !            21: 
        !            22: Copyright (C) 1993 Free Software Foundation, Inc.
        !            23: 
        !            24: Permission is granted to make and distribute verbatim copies of
        !            25: this manual provided the copyright notice and this permission notice
        !            26: are preserved on all copies.
        !            27: 
        !            28: @ignore
        !            29: Permission is granted to process this file through TeX and print the
        !            30: results, provided the printed document carries copying permission
        !            31: notice identical to this one except for the removal of this paragraph
        !            32: (this paragraph not being relevant to the printed manual).
        !            33: 
        !            34: @end ignore
        !            35: Permission is granted to copy and distribute modified versions of this
        !            36: manual under the conditions for verbatim copying, provided also that the
        !            37: entire resulting derived work is distributed under the terms of a
        !            38: permission notice identical to this one.
        !            39: 
        !            40: Permission is granted to copy and distribute translations of this manual
        !            41: into another language, under the above conditions for modified versions.
        !            42: @end ifinfo
        !            43: 
        !            44: @finalout
        !            45: @syncodeindex fn cp
        !            46: @syncodeindex vr cp
        !            47: 
        !            48: @titlepage
        !            49: @title The GNU C++ Iostream Library
        !            50: @subtitle Reference Manual for @code{libio} Version 0.50
        !            51: @sp 3
        !            52: @author Per Bothner @hfill @code{bothner@@cygnus.com}
        !            53: @author Roland Pesch @hfill @code{pesch@@cygnus.com}
        !            54: @page
        !            55: 
        !            56: @vskip 0pt plus 1filll
        !            57: Copyright @copyright{} 1993 Free Software Foundation, Inc.
        !            58: 
        !            59: @code{libio} includes software developed by the University of
        !            60: California, Berkeley.
        !            61: 
        !            62: @code{libio} uses floating-point software written by David M. Gay, which
        !            63: includes the following notice:
        !            64: 
        !            65: @quotation
        !            66: The author of this software is David M. Gay.
        !            67: 
        !            68: Copyright (c) 1991 by AT&T.
        !            69: 
        !            70: Permission to use, copy, modify, and distribute this software for any
        !            71: purpose without fee is hereby granted, provided that this entire notice
        !            72: is included in all copies of any software which is or includes a copy
        !            73: or modification of this software and in all copies of the supporting
        !            74: documentation for such software.
        !            75: 
        !            76: THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
        !            77: WARRANTY.  IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY
        !            78: REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
        !            79: OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
        !            80: @end quotation
        !            81: 
        !            82: Permission is granted to make and distribute verbatim copies of
        !            83: this manual provided the copyright notice and this permission notice
        !            84: are preserved on all copies.
        !            85: 
        !            86: Permission is granted to copy and distribute modified versions of this
        !            87: manual under the conditions for verbatim copying, provided also that the
        !            88: entire resulting derived work is distributed under the terms of a
        !            89: permission notice identical to this one.
        !            90: 
        !            91: Permission is granted to copy and distribute translations of this manual
        !            92: into another language, under the above conditions for modified versions.
        !            93: @end titlepage
        !            94: 
        !            95: @ifinfo
        !            96: @node Top
        !            97: @top The GNU C++ Iostream Library
        !            98: 
        !            99: This file provides reference information on the GNU C++ iostream library
        !           100: (@code{libio}), version 0.50.
        !           101: 
        !           102: @menu
        !           103: * Introduction::
        !           104: * Operators::                  Operators and default streams.
        !           105: * Streams::                    Stream classes.
        !           106: * Files and Strings::          Classes for files and strings.
        !           107: * Streambuf::                  Using the streambuf layer.
        !           108: * Stdio::                      C input and output.
        !           109: * Index::
        !           110: @end menu
        !           111: @end ifinfo
        !           112: 
        !           113: @node Introduction
        !           114: @chapter Introduction
        !           115: 
        !           116: The iostream classes implement most of the features of AT&T version 2.0
        !           117: iostream library classes, and most of the features of the ANSI X3J16
        !           118: library draft (which is based on the AT&T design).
        !           119: 
        !           120: This manual is meant as a reference; for tutorial material on iostreams,
        !           121: see the corresponding section of any recent popular introduction to C++.
        !           122: 
        !           123: @menu
        !           124: * Copying::            Special GNU licensing terms for libio.
        !           125: * Acknowledgements::   Contributors to GNU iostream.
        !           126: @end menu
        !           127: 
        !           128: @node Copying
        !           129: @section Licensing terms for @code{libio}
        !           130: 
        !           131: Since the @code{iostream} classes are so fundamental to standard C++,
        !           132: the Free Software Foundation has agreed to a special exception to its
        !           133: standard license, when you link programs with @code{libio.a}:
        !           134: 
        !           135: @quotation
        !           136: As a special exception, if you link this library with files
        !           137: compiled with a GNU compiler to produce an executable, this does not cause
        !           138: the resulting executable to be covered by the GNU General Public License.
        !           139: This exception does not however invalidate any other reasons why
        !           140: the executable file might be covered by the GNU General Public License.
        !           141: @end quotation
        !           142: 
        !           143: The code is under the @sc{gnu} General Public License (version 2) for
        !           144: all other purposes than linking with this library; that means that you
        !           145: can modify and redistribute the code as usual, but remember that if you
        !           146: do, your modifications, and anything you link with the modified code,
        !           147: must be available to others on the same terms.
        !           148: 
        !           149: These functions are also available as part of the @code{libg++}
        !           150: library; if you link with that library instead of @code{libio}, the
        !           151: @sc{gnu} Library General Public License applies.
        !           152: 
        !           153: @node Acknowledgements
        !           154: @section Acknowledgements
        !           155: 
        !           156: Per Bothner wrote most of the @code{iostream} library, but some portions
        !           157: have their origins elsewhere in the free software community.  Heinz
        !           158: Seidl wrote the IO manipulators.  The floating-point conversion software
        !           159: is by David M. Gay of AT&T.  Some code was derived from parts of BSD
        !           160: 4.4, which was written at the University of California, Berkeley.
        !           161: 
        !           162: The iostream classes are found in the @code{libio} library.  An early
        !           163: version was originally distributed in @code{libg++}, and they are still
        !           164: included there as well, for convenience if you need other @code{libg++}
        !           165: classes.  Doug Lea was the original author of @code{libg++}, and some of
        !           166: the file-management code still in @code{libio} is his.
        !           167: 
        !           168: Various people found bugs or offered suggestions.  Hongjiu Lu worked
        !           169: hard to use the library as the default stdio implementation for Linux,
        !           170: and has provided much stress-testing of the library.
        !           171: 
        !           172: @node Operators
        !           173: @chapter Operators and Default Streams
        !           174: 
        !           175: The @sc{gnu} iostream library, @file{libio}, implements the standard
        !           176: input and output facilities for C++.  These facilities are roughly
        !           177: analogous (in their purpose and ubiquity, at least) with those defined
        !           178: by the C @file{stdio} functions.
        !           179: 
        !           180: Although these definitions come from a library, rather than being part
        !           181: of the ``core language'', they are sufficiently central to be specified
        !           182: in the latest working papers for C++.
        !           183: 
        !           184: You can use two operators defined in this library for basic input and
        !           185: output operations.  They are familiar from any C++ introductory
        !           186: textbook: @code{<<} for output, and @code{>>} for input.  (Think of data
        !           187: flowing in the direction of the ``arrows''.)
        !           188: 
        !           189: These operators are often used in conjunction with three streams that
        !           190: are open by default: 
        !           191: 
        !           192: @deftypevar ostream cout
        !           193: The standard output stream, analogous to the C @code{stdout}.
        !           194: @end deftypevar
        !           195: 
        !           196: @deftypevar istream cin
        !           197: The standard input stream, analogous to the C @code{stdin}.
        !           198: @end deftypevar
        !           199: 
        !           200: @deftypevar ostream cerr
        !           201: An alternative output stream for errors, analogous to the C
        !           202: @code{stderr}.
        !           203: @end deftypevar
        !           204: 
        !           205: @noindent
        !           206: For example, this bare-bones C++ version of the traditional ``hello''
        !           207: program uses @code{<<} and @code{cout}:
        !           208: 
        !           209: @example
        !           210: #include <iostream.h>
        !           211: 
        !           212: int main(int argc, char **argv)
        !           213: @{
        !           214:   cout << "Well, hi there.\n";
        !           215:   return 0;
        !           216: @}
        !           217: @end example
        !           218: 
        !           219: Casual use of these operators may be seductive, but---other than in
        !           220: writing throwaway code for your own use---it is not necessarily simpler
        !           221: than managing input and output in any other language.  For example,
        !           222: robust code should check the state of the input and output streams
        !           223: between operations (for example, using the method @code{good}).
        !           224: @xref{States,,Checking the state of a stream}.  You may also need to
        !           225: adjust maximum input or output field widths, using manipulators like
        !           226: @code{setw} or @code{setprecision}.
        !           227: 
        !           228: @defop Operator ostream <<
        !           229: Write output to an open output stream of class @code{ostream}.
        !           230: Defined by this library on any @var{object} of a C++ primitive type, and
        !           231: on other classes of the library.  You can overload the definition for any
        !           232: of your own applications' classes.
        !           233: 
        !           234: Returns a reference to the implied argument @code{*this} (the open stream it
        !           235: writes on), permitting statements like
        !           236: @example
        !           237: cout << "The value of i is " << i << "\n";
        !           238: @end example
        !           239: @end defop
        !           240: 
        !           241: @defop Operator istream >>
        !           242: Read input from an open input stream of class @code{istream}.  Defined
        !           243: by this library on primitive numeric, pointer, and string types; you can
        !           244: extend the definition for any of your own applications' classes.
        !           245: 
        !           246: Returns a reference to the implied argument @code{*this} (the open stream
        !           247: it reads), permitting multiple inputs in one statement.
        !           248: @end defop
        !           249: 
        !           250: @node Streams
        !           251: @chapter Stream Classes
        !           252: 
        !           253: The previous chapter referred in passing to the classes @code{ostream}
        !           254: and @code{istream}, for output and input respectively.  These classes
        !           255: share certain properties, captured in their base class @code{ios}.
        !           256: 
        !           257: @menu
        !           258: * Ios::       Shared properties.
        !           259: * Ostream::   Managing output streams.
        !           260: * Istream::   Managing input streams.
        !           261: * Iostream::  Input and output together.
        !           262: @end menu
        !           263: 
        !           264: @node Ios
        !           265: @section Shared properties: class @code{ios}
        !           266: 
        !           267: The base class @code{ios} provides methods to test and manage the state
        !           268: of input or output streams.
        !           269: 
        !           270: @code{ios} delegates the job of actually reading and writing bytes to
        !           271: the abstract class @code{streambuf}, which is designed to provide
        !           272: buffered streams (compatible with C, in the @sc{gnu} implementation).
        !           273: @xref{Streambuf,,Using the @code{streambuf} layer}, for information on
        !           274: the facilities available at the @code{streambuf} level.
        !           275: 
        !           276: @deftypefn Constructor {} ios::ios ([streambuf* @var{sb} @w{[, ostream*} @var{tie}])
        !           277: The @code{ios} constructor by default initializes a new @code{ios}, and
        !           278: if you supply a @code{streambuf} @var{sb} to associate with it, sets the
        !           279: state @code{good} in the new @code{ios} object.  It also sets the
        !           280: default properties of the new object.
        !           281: 
        !           282: @ignore
        !           283: @c FIXME--future: this (a) doesn't work, (b) is controversial at ANSI
        !           284: An @code{ios} without a @code{streambuf} has the state @code{bad} until
        !           285: you supply a @code{streambuf}; you can do that by assigning a new value
        !           286: to the @code{ios} with @samp{=}.
        !           287: @end ignore
        !           288: 
        !           289: You can also supply an optional second argument @var{tie} to the
        !           290: constructor: if present, it is an initial value for @code{ios::tie}, to
        !           291: associate the new @code{ios} object with another stream.
        !           292: @end deftypefn
        !           293: 
        !           294: @deftypefn Destructor {} ios::~ios ()
        !           295: The @code{ios} destructor is virtual, permitting application-specific
        !           296: behavior when a stream is closed---typically, the destructor frees any
        !           297: storage associated with the stream and releases any other associated
        !           298: objects.
        !           299: @end deftypefn
        !           300: 
        !           301: @c FIXME-future:  Is @deftypefn really the best way of displaying these?
        !           302: 
        !           303: @c FIXME-future: Undocumented: ios::_throw_failure, ios::exceptions; things
        !           304: @c controlled by _STREAM_COMPAT; ios::Init; ios::_IO_fix_vtable.
        !           305: 
        !           306: @menu
        !           307: * States::             Checking the state of a stream.
        !           308: * Format Control::     Choices in formatting.
        !           309: * Manipulators::       Convenient ways of changing stream properties.
        !           310: * Extending::          Extended data fields.
        !           311: * Synchronization::    Synchronizing related streams.
        !           312: * Streambuf from Ios:: Reaching the underlying streambuf.
        !           313: @end menu
        !           314: 
        !           315: @node States
        !           316: @subsection Checking the state of a stream
        !           317: 
        !           318: Use this collection of methods to test for (or signal) errors and other
        !           319: exceptional conditions of streams:
        !           320: 
        !           321: @deftypefn Method {ios::operator void*} () const
        !           322: You can do a quick check on the state of the most recent operation on a
        !           323: stream by examining a pointer to the stream itself.  The pointer is
        !           324: arbitrary except for its truth value; it is true if no failures have
        !           325: occurred (@code{ios::fail} is not true).  For example, you might ask for
        !           326: input on @code{cin} only if all prior output operations succeeded:
        !           327: 
        !           328: @example
        !           329: if (cout)
        !           330: @{
        !           331:   // Everything OK so far
        !           332:   cin >> new_value;
        !           333:   @dots{}
        !           334: @}
        !           335: @end example
        !           336: @end deftypefn
        !           337: 
        !           338: @deftypefn Method {ios::operator !} () const
        !           339: In case it is more convenient to check whether something has failed, the
        !           340: operator @code{!} returns true if @code{ios::fail} is true (an operation
        !           341: has failed).  For example,
        !           342: you might issue an error message if input failed:
        !           343: 
        !           344: @example
        !           345: if (!cin)
        !           346: @{
        !           347:   // Oops
        !           348:   cerr << "Eh?\n";
        !           349: @}
        !           350: @end example
        !           351: @end deftypefn
        !           352: 
        !           353: @deftypefn Method iostate ios::rdstate () const
        !           354: Return the state flags for this stream.  The value is from the
        !           355: enumeration @code{iostate}.  You can test for any combination of
        !           356: 
        !           357: @vtable @code
        !           358: @item goodbit
        !           359: There are no indications of exceptional states on this stream.
        !           360: 
        !           361: @item eofbit
        !           362: End of file.
        !           363: 
        !           364: @item failbit
        !           365: An operation has failed on this stream; this usually indicates bad
        !           366: format of input.
        !           367: 
        !           368: @item badbit
        !           369: The stream is unusable.
        !           370: @end vtable
        !           371: @end deftypefn
        !           372: 
        !           373: @deftypefn Method void ios::setstate (iostate @var{state})
        !           374: @findex ios::set
        !           375: Set the state flag for this stream to @var{state} @emph{in addition to}
        !           376: any state flags already set.  Synonym (for upward compatibility):
        !           377: @code{ios::set}.
        !           378: 
        !           379: See @code{ios::clear} to set the stream state without regard to existing
        !           380: state flags.  See @code{ios::good}, @code{ios::eof}, @code{ios::fail},
        !           381: and @code{ios::bad}, to test the state.
        !           382: @end deftypefn
        !           383: 
        !           384: @deftypefn Method int ios::good () const
        !           385: Test the state flags associated with this stream; true if no error
        !           386: indicators are set.
        !           387: @end deftypefn
        !           388: 
        !           389: @deftypefn Method int ios::bad () const
        !           390: Test whether a stream is marked as unusable.  (Whether
        !           391: @code{ios::badbit} is set.)
        !           392: @end deftypefn
        !           393: 
        !           394: @deftypefn Method int ios::eof () const
        !           395: True if end of file was reached on this stream.  (If @code{ios::eofbit}
        !           396: is set.)
        !           397: @end deftypefn
        !           398: 
        !           399: @deftypefn Method int ios::fail () const
        !           400: Test for any kind of failure on this stream: @emph{either} some
        !           401: operation failed, @emph{or} the stream is marked as bad.  (If either
        !           402: @code{ios::failbit} or @code{ios::badbit} is set.)
        !           403: @end deftypefn
        !           404: 
        !           405: @deftypefn Method void ios::clear (iostate @var{state})
        !           406: @c FIXME-future: There is some complication to do with buffering and _throw_failure
        !           407: Set the state indication for this stream to the argument @var{state}.
        !           408: You may call @code{ios::clear} with no argument, in which case the state
        !           409: is set to @code{good} (no errors pending).
        !           410: 
        !           411: See @code{ios::good}, @code{ios::eof}, @code{ios::fail}, and
        !           412: @code{ios::bad}, to test the state; see @code{ios::set} or
        !           413: @code{ios::setstate} for an alternative way of setting the state.
        !           414: @end deftypefn
        !           415: 
        !           416: @node Format Control
        !           417: @subsection Choices in formatting
        !           418: 
        !           419: These methods control (or report on) settings for some details of
        !           420: controlling streams, primarily to do with formatting output:
        !           421: 
        !           422: @deftypefn Method char ios::fill () const
        !           423: Report on the padding character in use.
        !           424: @end deftypefn
        !           425: 
        !           426: @deftypefn Method char ios::fill (char @var{padding})
        !           427: Set the padding character.  You can also use the manipulator
        !           428: @code{setfill}.  @xref{Manipulators,,Changing stream properties in
        !           429: expressions}.
        !           430: 
        !           431: Default: blank.
        !           432: @end deftypefn
        !           433: 
        !           434: @deftypefn Method int ios::precision () const
        !           435: Report the number of significant digits currently in use for output of
        !           436: floating point numbers.
        !           437: 
        !           438: Default: @code{6}.
        !           439: @end deftypefn
        !           440: 
        !           441: @deftypefn Method int ios::precision (int @var{signif})
        !           442: Set the number of significant digits (for input and output numeric
        !           443: conversions) to @var{signif}.
        !           444: 
        !           445: @findex setprecision
        !           446: @cindex setting @code{ios::precision}
        !           447: You can also use the manipulator @code{setprecision} for this purpose.
        !           448: @xref{Manipulators,,Changing stream properties using manipulators}.
        !           449: @end deftypefn
        !           450: 
        !           451: @deftypefn Method int ios::width () const
        !           452: Report the current output field width setting (the number of
        !           453: characters to write on the next @samp{<<} output operation).
        !           454: 
        !           455: Default: @code{0}, which means to use as many characters as necessary.
        !           456: @end deftypefn
        !           457: 
        !           458: @deftypefn Method int ios::width (int @var{num})
        !           459: Set the input field width setting to @var{num}.  Return the
        !           460: @emph{previous} value for this stream.
        !           461: 
        !           462: @findex setw
        !           463: @cindex setting @code{ios::width}
        !           464: This value resets to zero (the default) every time you use @samp{<<}; it is
        !           465: essentially an additional implicit argument to that operator.  You can
        !           466: also use the manipulator @code{setw} for this purpose.
        !           467: @xref{Manipulators,,Changing stream properties using manipulators}.
        !           468: @end deftypefn
        !           469: 
        !           470: @need 2000
        !           471: @deftypefn Method fmtflags ios::flags () const
        !           472: Return the current value of the complete collection of flags controlling
        !           473: the format state.  These are the flags and their meanings when set:
        !           474: 
        !           475: @vtable @code
        !           476: @item ios::dec
        !           477: @itemx ios::oct
        !           478: @itemx ios::hex
        !           479: What numeric base to use in converting integers from internal to display
        !           480: representation, or vice versa: decimal, octal, or hexadecimal,
        !           481: respectively.  (You can change the base using the manipulator
        !           482: @code{setbase}, or any of the manipulators @code{dec}, @code{oct}, or
        !           483: @code{hex}; @pxref{Manipulators,,Changing stream properties in
        !           484: expressions}.)
        !           485: 
        !           486: On input, if none of these flags is set, read numeric constants
        !           487: according to the prefix: decimal if no prefix (or a @samp{.} suffix),
        !           488: octal if a @samp{0} prefix is present, hexadecimal if a @samp{0x} prefix
        !           489: is present.
        !           490: 
        !           491: Default: @code{dec}.
        !           492: 
        !           493: @item ios::fixed
        !           494: Avoid scientific notation, and always show a fixed number of digits after
        !           495: the decimal point, according to the output precision in effect.
        !           496: Use @code{ios::precision} to set precision.
        !           497: 
        !           498: @item ios::left
        !           499: @itemx ios::right
        !           500: @itemx ios::internal
        !           501: Where output is to appear in a fixed-width field; left-justified,
        !           502: right-justified, or with padding in the middle (e.g. between a numeric
        !           503: sign and the associated value), respectively.
        !           504: 
        !           505: @item ios::scientific
        !           506: Use scientific (exponential) notation to display numbers.
        !           507: 
        !           508: @item ios::showbase
        !           509: Display the conventional prefix as a visual indicator of the conversion
        !           510: base: no prefix for decimal, @samp{0} for octal, @samp{0x} for hexadecimal.
        !           511: 
        !           512: @item ios::showpoint
        !           513: Display a decimal point and trailing zeros after it to fill out numeric
        !           514: fields, even when redundant.
        !           515: 
        !           516: @item ios::showpos
        !           517: Display a positive sign on display of positive numbers.
        !           518: 
        !           519: @item ios::skipws
        !           520: Skip white space.  (On by default).
        !           521: 
        !           522: @item ios::stdio
        !           523: Flush the C @code{stdio} streams @code{stdout} and @code{stderr} after
        !           524: each output operation (for programs that mix C and C++ output conventions).
        !           525: 
        !           526: @item ios::unitbuf
        !           527: Flush after each output operation.
        !           528: 
        !           529: @item ios::uppercase
        !           530: Use upper-case characters for the non-numeral elements in numeric
        !           531: displays; for instance, @samp{0X7A} rather than @samp{0x7a}, or
        !           532: @samp{3.14E+09} rather than @samp{3.14e+09}.
        !           533: @end vtable
        !           534: @end deftypefn
        !           535: 
        !           536: @deftypefn Method fmtflags ios::flags (fmtflags @var{value})
        !           537: Set @var{value} as the complete collection of flags controlling the
        !           538: format state.  The flag values are described under @samp{ios::flags ()}.
        !           539: 
        !           540: Use @code{ios::setf} or @code{ios::unsetf} to change one property at a
        !           541: time.
        !           542: @end deftypefn
        !           543: 
        !           544: @deftypefn Method fmtflags ios::setf (fmtflags @var{flag})
        !           545: Set one particular flag (of those described for @samp{ios::flags ()};
        !           546: return the complete collection of flags @emph{previously} in effect.
        !           547: (Use @code{ios::unsetf} to cancel.)
        !           548: @end deftypefn
        !           549: 
        !           550: @deftypefn Method fmtflags ios::setf (fmtflags @var{flag}, fmtflags @var{mask})
        !           551: Clear the flag values indicated by @var{mask}, then set any of them that
        !           552: are also in @var{flag}.  (Flag values are described for @samp{ios::flags
        !           553: ()}.)  Return the complete collection of flags @emph{previously} in
        !           554: effect.  (See @code{ios::unsetf} for another way of clearing flags.)
        !           555: @end deftypefn
        !           556: 
        !           557: @deftypefn Method fmtflags ios::unsetf (fmtflags @var{flag})
        !           558: Make certain @var{flag} (a combination of flag values described for
        !           559: @samp{ios::flags ()}) is not set for this stream; converse of
        !           560: @code{ios::setf}.  Returns the old values of those flags.
        !           561: @c FIXME-future: should probably be fixed to give same result as setf.
        !           562: @end deftypefn
        !           563: 
        !           564: @node Manipulators
        !           565: @subsection Changing stream properties using manipulators
        !           566: 
        !           567: For convenience, @var{manipulators} provide a way to change certain
        !           568: properties of streams, or otherwise affect them, in the middle of
        !           569: expressions involving @samp{<<} or @samp{>>}.  For example, you might
        !           570: write
        !           571: 
        !           572: @example
        !           573: cout << "|" << setfill('*') << setw(5) << 234 << "|";
        !           574: @end example
        !           575: 
        !           576: @noindent
        !           577: to produce @samp{|**234|} as output.
        !           578: 
        !           579: @deftypefn Manipulator {} ws
        !           580: Skip whitespace.
        !           581: @end deftypefn
        !           582: 
        !           583: @deftypefn Manipulator {} flush
        !           584: Flush an output stream.  For example, @samp{cout << @dots{} <<flush;}
        !           585: has the same effect as @samp{cout << @dots{}; cout.flush();}.
        !           586: @end deftypefn
        !           587: 
        !           588: @deftypefn Manipulator {} endl
        !           589: Write an end of line character @samp{\n}, then flushes the output stream.
        !           590: @end deftypefn
        !           591: 
        !           592: @deftypefn Manipulator {} ends
        !           593: Write @samp{\0} (the string terminator character).
        !           594: @end deftypefn
        !           595: 
        !           596: @deftypefn Manipulator {} setprecision (int @var{signif})
        !           597: You can change the value of @code{ios::precision} in @samp{<<}
        !           598: expressions with the manipulator @samp{setprecision(@var{signif})}; for
        !           599: example,
        !           600: 
        !           601: @example
        !           602: cout << setprecision(2) << 4.567;
        !           603: @end example
        !           604: 
        !           605: @noindent
        !           606: prints @samp{4.6}.  Requires @file{#include <iomanip.h>}.
        !           607: @end deftypefn
        !           608: 
        !           609: @deftypefn Manipulator {} setw (int @var{n})
        !           610: You can change the value of @code{ios::width} in @samp{<<} expressions
        !           611: with the manipulator @samp{setw(@var{n})}; for example,
        !           612: 
        !           613: @example
        !           614: cout << setw(5) << 234;
        !           615: @end example
        !           616: 
        !           617: @noindent
        !           618: prints @w{@samp{  234}} with two leading blanks.  Requires @file{#include
        !           619: <iomanip.h>}.
        !           620: @end deftypefn
        !           621: 
        !           622: @deftypefn Manipulator {} setbase (int @var{base})
        !           623: Where @var{base} is one of @code{10} (decimal), @code{8} (octal), or
        !           624: @code{16} (hexadecimal), change the base value for numeric
        !           625: representations.  Requires @file{#include <iomanip.h>}.
        !           626: @end deftypefn
        !           627: 
        !           628: @deftypefn Manipulator {} dec
        !           629: Select decimal base; equivalent to @samp{setbase(10)}.
        !           630: @end deftypefn
        !           631: 
        !           632: @deftypefn Manipulator {} hex
        !           633: Select hexadecimal base; equivalent to @samp{setbase(16)}.
        !           634: @end deftypefn
        !           635: 
        !           636: @deftypefn Manipulator {} oct
        !           637: Select octal base; equivalent to @samp{setbase(8)}.
        !           638: @end deftypefn
        !           639: 
        !           640: @deftypefn Manipulator {} setfill (char @var{padding})
        !           641: Set the padding character, in the same way as @code{ios::fill}.
        !           642: Requires @file{#include <iomanip.h>}.
        !           643: @end deftypefn
        !           644: 
        !           645: @node Extending
        !           646: @subsection Extended data fields
        !           647: 
        !           648: A related collection of methods allows you to extend this collection of
        !           649: flags and parameters for your own applications, without risk of conflict
        !           650: between them:
        !           651: 
        !           652: @deftypefn Method {static fmtflags} ios::bitalloc ()
        !           653: Reserve a bit (the single bit on in the result) to use as a flag.  Using
        !           654: @code{bitalloc} guards against conflict between two packages that use
        !           655: @code{ios} objects for different purposes.
        !           656: 
        !           657: This method is available for upward compatibility, but is not in the
        !           658: @sc{ansi} working paper.  The number of bits available is limited; a
        !           659: return value of @code{0} means no bit is available.
        !           660: @end deftypefn
        !           661: 
        !           662: @deftypefn Method {static int} ios::xalloc ()
        !           663: Reserve space for a long integer or pointer parameter.  The result is a
        !           664: unique nonnegative integer.  You can use it as an index to
        !           665: @code{ios::iword} or @code{ios::pword}.  Use @code{xalloc} to arrange
        !           666: for arbitrary special-purpose data in your @code{ios} objects, without
        !           667: risk of conflict between packages designed for different purposes.
        !           668: @end deftypefn
        !           669: 
        !           670: @deftypefn Method long& ios::iword (int @var{index})
        !           671: Return a reference to arbitrary data, of long integer type, stored in an
        !           672: @code{ios} instance.  @var{index}, conventionally returned from
        !           673: @code{ios::xalloc}, identifies what particular data you need.
        !           674: @end deftypefn
        !           675: 
        !           676: @deftypefn Method long ios::iword (int @var{index}) const
        !           677: Return the actual value of a long integer stored in an @code{ios}.
        !           678: @end deftypefn
        !           679: 
        !           680: @deftypefn Method void*& ios::pword (int @var{index})
        !           681: Return a reference to an arbitrary pointer, stored in an @code{ios}
        !           682: instance.  @var{index}, originally returned from @code{ios::xalloc},
        !           683: identifies what particular pointer you need.
        !           684: @end deftypefn
        !           685: 
        !           686: @deftypefn Method void* ios::pword (int @var{index}) const
        !           687: Return the actual value of a pointer stored in an @code{ios}.
        !           688: @end deftypefn
        !           689: 
        !           690: @node Synchronization
        !           691: @subsection Synchronizing related streams
        !           692: 
        !           693: You can use these methods to synchronize related streams with
        !           694: one another:
        !           695: 
        !           696: @deftypefn Method ostream* ios::tie () const
        !           697: Report on what output stream, if any, is to be flushed before accessing
        !           698: this one.  A pointer value of @code{0} means no stream is tied.
        !           699: @end deftypefn
        !           700: 
        !           701: @deftypefn Method ostream* ios::tie (ostream* @var{assoc})
        !           702: Declare that output stream @var{assoc} must be flushed before accessing
        !           703: this stream.
        !           704: @end deftypefn
        !           705: 
        !           706: @deftypefn Method int ios::sync_with_stdio ([int @var{switch}])
        !           707: Unless iostreams and C @code{stdio} are designed to work together, you
        !           708: may have to choose between efficient C++ streams output and output
        !           709: compatible with C @code{stdio}.  Use @samp{ios::sync_with_stdio()} to
        !           710: select C compatibility.
        !           711: 
        !           712: The argument @var{switch} is a @sc{gnu} extension; use @code{0} as the
        !           713: argument to choose output that is not necessarily compatible with C
        !           714: @code{stdio}.  The default value for @var{switch} is @code{1}.
        !           715: 
        !           716: If you install the @code{stdio} implementation that comes with @sc{gnu}
        !           717: @code{libio}, there are compatible input/output facilities for both C
        !           718: and C++.  In that situation, this method is unnecessary---but you may
        !           719: still want to write programs that call it, for portability.
        !           720: @end deftypefn
        !           721: 
        !           722: @node Streambuf from Ios
        !           723: @subsection Reaching the underlying @code{streambuf}
        !           724: 
        !           725: Finally, you can use this method to access the underlying object:
        !           726: 
        !           727: @deftypefn Method streambuf* ios::rdbuf () const
        !           728: Return a pointer to the @code{streambuf} object that underlies this
        !           729: @code{ios}.
        !           730: @end deftypefn
        !           731: 
        !           732: @node Ostream
        !           733: @section Managing output streams: class @code{ostream}
        !           734: 
        !           735: Objects of class @code{ostream} inherit the generic methods from
        !           736: @code{ios}, and in addition have the following methods available.
        !           737: Declarations for this class come from @file{iostream.h}.
        !           738: 
        !           739: @deftypefn Constructor {} ostream::ostream ()
        !           740: The simplest form of the constructor for an @code{ostream} simply
        !           741: allocates a new @code{ios} object.
        !           742: @end deftypefn
        !           743: 
        !           744: @deftypefn Constructor {} ostream::ostream (streambuf* @var{sb} @w{[, ostream} @var{tie}])
        !           745: This alternative constructor requires a first argument @var{sb} of type
        !           746: @code{streambuf*}, to use an existing open stream for output.  It also
        !           747: accepts an optional second argument @var{tie}, to specify a related
        !           748: @code{ostream*} as the initial value for @code{ios::tie}.
        !           749: 
        !           750: If you give the @code{ostream} a @code{streambuf} explicitly, using
        !           751: this constructor, the @var{sb} is @emph{not} destroyed (or deleted or
        !           752: closed) when the @code{ostream} is destroyed.
        !           753: @end deftypefn
        !           754: 
        !           755: @menu
        !           756: * Writing::            Writing on an ostream.
        !           757: * Output Position::    Repositioning an ostream.
        !           758: * Ostream Housekeeping:: Miscellaneous ostream utilities.
        !           759: @end menu
        !           760: 
        !           761: @node Writing
        !           762: @subsection Writing on an @code{ostream}
        !           763: 
        !           764: These methods write on an @code{ostream} (you may also use the operator
        !           765: @code{<<}; @pxref{Operators,,Operators and Default Streams}).
        !           766: 
        !           767: @deftypefn Method ostream& ostream::put (char @var{c})
        !           768: Write the single character @var{c}.
        !           769: @end deftypefn
        !           770: 
        !           771: @deftypefn Method ostream& ostream::write (@var{string}, int @var{length})
        !           772: Write @var{length} characters of a string to this @code{ostream},
        !           773: beginning at the pointer @var{string}.
        !           774: 
        !           775: @var{string} may have any of these types: @code{char*}, @code{unsigned
        !           776: char*}, @code{signed char*}.
        !           777: @end deftypefn
        !           778: 
        !           779: @deftypefn Method ostream& ostream::form (const char *@var{format}, ...)
        !           780: A @sc{gnu} extension, similar to @code{fprintf(@var{file},
        !           781: @var{format}, ...)}.
        !           782: 
        !           783: @var{format} is a @code{printf}-style format control string, which is used
        !           784: to format the (variable number of) arguments, printing the result on
        !           785: this @code{ostream}.  See @code{ostream::vform} for a version that uses
        !           786: an argument list rather than a variable number of arguments.
        !           787: @end deftypefn
        !           788: 
        !           789: @deftypefn Method ostream& ostream::vform (const char *@var{format}, va_list @var{args})
        !           790: A @sc{gnu} extension, similar to @code{vfprintf(@var{file},
        !           791: @var{format}, @var{args})}.
        !           792: 
        !           793: @var{format} is a @code{printf}-style format control string, which is used
        !           794: to format the argument list @var{args}, printing the result on
        !           795: this @code{ostream}.  See @code{ostream::form} for a version that uses a
        !           796: variable number of arguments rather than an argument list.
        !           797: @end deftypefn
        !           798: 
        !           799: @node Output Position
        !           800: @subsection Repositioning an @code{ostream}
        !           801: 
        !           802: You can control the output position (on output streams that actually
        !           803: support positions, typically files) with these methods:
        !           804: @c FIXME-future: sort out which classes support this and which
        !           805: @c don't; fstream, filebuf?  And what is failure condition when not supported?
        !           806: 
        !           807: @deftypefn Method streampos ostream::tellp ()
        !           808: Return the current write position in the stream.
        !           809: @end deftypefn
        !           810: 
        !           811: @deftypefn Method ostream& ostream::seekp (streampos @var{loc})
        !           812: Reset the output position to @var{loc} (which is usually the result of a
        !           813: previous call to @code{ostream::tellp}).  @var{loc} specifies an
        !           814: absolute position in the output stream.
        !           815: @end deftypefn
        !           816: 
        !           817: @deftypefn Method ostream& ostream::seekp (streamoff @var{loc}, @var{rel})
        !           818: @findex ios::seekdir
        !           819: Reset the output position to @var{loc}, relative to the beginning, end,
        !           820: or current output position in the stream, as indicated by @var{rel} (a
        !           821: value from the enumeration @code{ios::seekdir}):
        !           822: 
        !           823: @vtable @code
        !           824: @item beg
        !           825: Interpret @var{loc} as an absolute offset from the beginning of the
        !           826: file.
        !           827: 
        !           828: @item cur
        !           829: Interpret @var{loc} as an offset relative to the current output
        !           830: position.
        !           831: 
        !           832: @item end
        !           833: Interpret @var{loc} as an offset from the current end of the output
        !           834: stream.
        !           835: @end vtable
        !           836: @end deftypefn
        !           837: 
        !           838: @node Ostream Housekeeping
        !           839: @subsection Miscellaneous @code{ostream} utilities
        !           840: 
        !           841: You may need to use these @code{ostream} methods for housekeeping:
        !           842: 
        !           843: @deftypefn Method ostream& flush ()
        !           844: Deliver any pending buffered output for this @code{ostream}.
        !           845: @end deftypefn
        !           846: 
        !           847: @deftypefn Method int ostream::opfx ()
        !           848: @code{opfx} is a @dfn{prefix} method for operations on @code{ostream}
        !           849: objects; it is designed to be called before any further processing.  See
        !           850: @code{ostream::osfx} for the converse.
        !           851: @c FIXME-future: specify sometime which methods start with opfx.
        !           852: 
        !           853: @code{opfx} tests that the stream is in state @code{good}, and if so
        !           854: flushes any stream tied to this one.
        !           855: 
        !           856: The result is @code{1} when @code{opfx} succeeds; else (if the stream state is
        !           857: not @code{good}), the result is @code{0}.
        !           858: @end deftypefn
        !           859: 
        !           860: @deftypefn Method void ostream::osfx ()
        !           861: @code{osfx} is a @dfn{suffix} method for operations on @code{ostream}
        !           862: objects; it is designed to be called at the conclusion of any processing.  All
        !           863: the @code{ostream} methods end by calling @code{osfx}.  See
        !           864: @code{ostream::opfx} for the converse.
        !           865: 
        !           866: If the @code{unitbuf} flag is set for this stream, @code{osfx} flushes
        !           867: any buffered output for it.
        !           868: 
        !           869: If the @code{stdio} flag is set for this stream, @code{osfx} flushes any
        !           870: output buffered for the C output streams @file{stdout} and @file{stderr}.
        !           871: @end deftypefn
        !           872: 
        !           873: @node Istream
        !           874: @section Managing input streams: class @code{istream}
        !           875: 
        !           876: Class @code{istream} objects are specialized for input; as for
        !           877: @code{ostream}, they are derived from @code{ios}, so you can use any of
        !           878: the general-purpose methods from that base class.  Declarations for this
        !           879: class also come from @file{iostream.h}.
        !           880: 
        !           881: @deftypefn Constructor {} istream::istream ()
        !           882: When used without arguments, the @code{istream} constructor simply
        !           883: allocates a new @code{ios} object and initializes the input counter (the
        !           884: value reported by @code{istream::gcount}) to @code{0}.
        !           885: @end deftypefn
        !           886: 
        !           887: @deftypefn Constructor {} istream::istream (streambuf *@var{sb} @w{[, ostream} @var{tie}])
        !           888: You can also call the constructor with one or two arguments.  The first
        !           889: argument @var{sb} is a @code{streambuf*}; if you supply this pointer,
        !           890: the constructor uses that @code{streambuf} for input.
        !           891: You can use the second optional argument @var{tie} to specify a related
        !           892: output stream as the initial value for @code{ios::tie}.
        !           893: 
        !           894: If you give the @code{istream} a @code{streambuf} explicitly, using
        !           895: this constructor, the @var{sb} is @emph{not} destroyed (or deleted or
        !           896: closed) when the @code{ostream} is destroyed.
        !           897: @end deftypefn
        !           898: 
        !           899: @menu
        !           900: * Char Input::         Reading one character.
        !           901: * String Input::       Reading strings.
        !           902: * Input Position::     Repositioning an istream.
        !           903: * Istream Housekeeping:: Miscellaneous istream utilities.
        !           904: @end menu
        !           905: 
        !           906: @node Char Input
        !           907: @subsection Reading one character
        !           908: 
        !           909: Use these methods to read a single character from the input stream:
        !           910: 
        !           911: @deftypefn Method int istream::get ()
        !           912: Read a single character (or @code{EOF}) from the input stream, returning
        !           913: it (coerced to an unsigned char) as the result.
        !           914: @end deftypefn
        !           915: 
        !           916: @deftypefn Method istream& istream::get (char& @var{c})
        !           917: Read a single character from the input stream, into @code{&@var{c}}.
        !           918: @end deftypefn
        !           919: 
        !           920: @deftypefn Method int istream::peek ()
        !           921: Return the next available input character, but @emph{without} changing
        !           922: the current input position.
        !           923: @end deftypefn
        !           924: 
        !           925: @node String Input
        !           926: @subsection Reading strings
        !           927: 
        !           928: Use these methods to read strings (for example, a line at a time) from
        !           929: the input stream:
        !           930: 
        !           931: @deftypefn Method istream& istream::get (char* @var{c}, int @var{len} @w{[, char} @var{delim}])
        !           932: Read a string from the input stream, into the array at @var{c}.
        !           933: 
        !           934: The remaining arguments limit how much to read: up to @samp{len-1}
        !           935: characters, or up to (but not including) the first occurrence in the
        !           936: input of a particular delimiter character @var{delim}---newline
        !           937: (@code{\n}) by default.  (Naturally, if the stream reaches end of file
        !           938: first, that too will terminate reading.)
        !           939: 
        !           940: If @var{delim} was present in the input, it remains available as if
        !           941: unread; to discard it instead, see @code{iostream::getline}.
        !           942: 
        !           943: @code{get} writes @samp{\0} at the end of the string, regardless
        !           944: of which condition terminates the read.
        !           945: @end deftypefn
        !           946: 
        !           947: @deftypefn Method istream& istream::get (streambuf& @var{sb} @w{[, char} @var{delim}])
        !           948: Read characters from the input stream and copy them on the
        !           949: @code{streambuf} object @var{sb}.  Copying ends either just before the
        !           950: next instance of the delimiter character @var{delim} (newline @code{\n}
        !           951: by default), or when either stream ends.   If @var{delim} was present in
        !           952: the input, it remains available as if unread.
        !           953: @end deftypefn
        !           954: 
        !           955: @deftypefn Method istream& istream::getline (@var{charptr}, int @var{len} @w{[, char} @var{delim}])
        !           956: Read a line from the input stream, into the array at @var{charptr}.
        !           957: @var{charptr} may be any of three kinds of pointer: @code{char*},
        !           958: @code{unsigned char*}, or @code{signed char*}.
        !           959: 
        !           960: The remaining arguments limit how much to read: up to (but not
        !           961: including) the first occurrence in the input of a line delimiter
        !           962: character @var{delim}---newline (@code{\n}) by default, or up to
        !           963: @samp{len-1} characters (or to end of file, if that happens sooner).
        !           964: 
        !           965: If @code{getline} succeeds in reading a ``full line'', it also discards
        !           966: the trailing delimiter character from the input stream.  (To preserve it
        !           967: as available input, see the similar form of @code{iostream::get}.)
        !           968: 
        !           969: If @var{delim} was @emph{not} found before @var{len} characters or end
        !           970: of file, @code{getline} sets the @code{ios::fail} flag, as well as the
        !           971: @code{ios::eof} flag if appropriate.
        !           972: 
        !           973: @code{getline} writes a null character at the end of the string, regardless
        !           974: of which condition terminates the read.
        !           975: @end deftypefn
        !           976: 
        !           977: @deftypefn Method istream& istream::read (@var{pointer}, int @var{len})
        !           978: Read @var{len} bytes into the location at @var{pointer}, unless the
        !           979: input ends first.
        !           980: 
        !           981: @var{pointer} may be of type @code{char*}, @code{void*}, @code{unsigned
        !           982: char*}, or @code{signed char*}.
        !           983: 
        !           984: If the @code{istream} ends before reading @var{len} bytes, @code{read}
        !           985: sets the @code{ios::fail} flag.
        !           986: @end deftypefn
        !           987: 
        !           988: @deftypefn Method istream& istream::gets (char **@var{s} @w{[, char} @var{delim}])
        !           989: A @sc{gnu} extension, to read an arbitrarily long string
        !           990: from the current input position to the next instance of the @var{delim}
        !           991: character (newline @code{\n} by default).
        !           992: 
        !           993: To permit reading a string of arbitrary length, @code{gets} allocates
        !           994: whatever memory is required.  Notice that the first argument @var{s} is
        !           995: an address to record a character pointer, rather than the pointer
        !           996: itself.
        !           997: @end deftypefn
        !           998: 
        !           999: @deftypefn Method istream& istream::scan (const char *format ...)
        !          1000: A @sc{gnu} extension, similar to @code{fscanf(@var{file},
        !          1001: @var{format}, ...)}.  The @var{format} is a @code{scanf}-style format
        !          1002: control string, which is used to read the variables in the remainder of
        !          1003: the argument list from the @code{istream}.
        !          1004: @end deftypefn
        !          1005: 
        !          1006: @deftypefn Method istream& istream::vscan (const char *format, va_list args)
        !          1007: Like @code{istream::scan}, but takes a single @code{va_list} argument.
        !          1008: @end deftypefn
        !          1009: 
        !          1010: @node Input Position
        !          1011: @subsection Repositioning an @code{istream}
        !          1012: 
        !          1013: Use these methods to control the current input position:
        !          1014: 
        !          1015: @deftypefn Method streampos istream::tellg ()
        !          1016: Return the current read position, so that you can save it and return to
        !          1017: it later with @code{istream::seekg}.
        !          1018: @end deftypefn
        !          1019: 
        !          1020: @deftypefn Method istream& istream::seekg (streampos @var{p})
        !          1021: Reset the input pointer (if the input device permits it) to @var{p},
        !          1022: usually the result of an earlier call to @code{istream::tellg}.
        !          1023: @end deftypefn
        !          1024: 
        !          1025: @deftypefn Method istream& istream::seekg (streamoff @var{offset}, ios::seek_dir @var{ref})
        !          1026: Reset the input pointer (if the input device permits it) to @var{offset}
        !          1027: characters from the beginning of the input, the current position, or the
        !          1028: end of input.  Specify how to interpret @var{offset} with one of these
        !          1029: values for the second argument:
        !          1030: 
        !          1031: @vtable @code
        !          1032: @item ios::beg
        !          1033: Interpret @var{loc} as an absolute offset from the beginning of the
        !          1034: file.
        !          1035: 
        !          1036: @item ios::cur
        !          1037: Interpret @var{loc} as an offset relative to the current output
        !          1038: position.
        !          1039: 
        !          1040: @item ios::end
        !          1041: Interpret @var{loc} as an offset from the current end of the output
        !          1042: stream.
        !          1043: @end vtable
        !          1044: @end deftypefn
        !          1045: 
        !          1046: @node Istream Housekeeping
        !          1047: @subsection Miscellaneous @code{istream} utilities
        !          1048: 
        !          1049: Use these methods for housekeeping on @code{istream} objects:
        !          1050: 
        !          1051: @deftypefn Method int istream::gcount ()
        !          1052: Report how many characters were read from this @code{istream} in the
        !          1053: last unformatted input operation.
        !          1054: @c FIXME! Define "unformatted input" somewhere...
        !          1055: @end deftypefn
        !          1056: 
        !          1057: @deftypefn Method int istream::ipfx (int @var{keepwhite})
        !          1058: Ensure that the @code{istream} object is ready for reading; check for
        !          1059: errors and end of file and flush any tied stream.  @code{ipfx} skips
        !          1060: whitespace if you specify @code{0} as the @var{keepwhite}
        !          1061: argument, @emph{and} @code{ios::skipws} is set for this stream.
        !          1062: 
        !          1063: To avoid skipping whitespace (regardless of the @code{skipws} setting on
        !          1064: the stream), use @code{1} as the argument.
        !          1065: 
        !          1066: Call @code{istream::ipfx} to simplify writing your own methods for reading
        !          1067: @code{istream} objects.
        !          1068: @end deftypefn
        !          1069: 
        !          1070: @deftypefn Method void istream::isfx ()
        !          1071: A placeholder for compliance with the draft @sc{ansi} standard; this
        !          1072: method does nothing whatever.
        !          1073: 
        !          1074: If you wish to write portable standard-conforming code on @code{istream}
        !          1075: objects, call @code{isfx} after any operation that reads from an
        !          1076: @code{istream}; if @code{istream::ipfx} has any special effects that
        !          1077: must be cancelled when done, @code{istream::isfx} will cancel them.
        !          1078: @end deftypefn
        !          1079: 
        !          1080: @deftypefn Method istream& istream::ignore ([int @var{n}] @w{[, int} @var{delim}])
        !          1081: Discard some number of characters pending input.  The first optional
        !          1082: argument @var{n} specifies how many characters to skip.  The second
        !          1083: optional argument @var{delim} specifies a ``boundary'' character:
        !          1084: @code{ignore} returns immediately if this character appears in the
        !          1085: input.
        !          1086: 
        !          1087: By default, @var{delim} is @code{EOF}; that is, if you do not specify a
        !          1088: second argument, only the count @var{n} restricts how much to ignore
        !          1089: (while input is still available).
        !          1090: 
        !          1091: If you do not specify how many characters to ignore, @code{ignore}
        !          1092: returns after discarding only one character.
        !          1093: @end deftypefn
        !          1094: 
        !          1095: @deftypefn Method istream& istream::putback (char @var{ch})
        !          1096: Attempts to back up one character, replacing the character backed-up
        !          1097: over by @var{ch}.  Returns @code{EOF} if this is not allowed.  Putting
        !          1098: back the most recently read character is always allowed.  (This method
        !          1099: corresponds to the C function @code{ungetc}.)
        !          1100: @end deftypefn
        !          1101: 
        !          1102: @deftypefn Method istream& istream::unget ()
        !          1103: Attempt to back up one character.
        !          1104: @end deftypefn
        !          1105: 
        !          1106: @node Iostream
        !          1107: @section Input and output together: class @code{iostream}
        !          1108: 
        !          1109: If you need to use the same stream for input and output, you can use an
        !          1110: object of the class @code{iostream}, which is derived from @emph{both}
        !          1111: @code{istream} and @code{ostream}.
        !          1112: 
        !          1113: The constructors for @code{iostream} behave just like the constructors
        !          1114: for @code{istream}.
        !          1115: 
        !          1116: @deftypefn Constructor {} iostream::iostream ()
        !          1117: When used without arguments, the @code{iostream} constructor simply
        !          1118: allocates a new @code{ios} object, and initializes the input counter
        !          1119: (the value reported by @code{istream::gcount}) to @code{0}.
        !          1120: @end deftypefn
        !          1121: 
        !          1122: @deftypefn Constructor {} iostream::iostream (streambuf* @var{sb} @w{[, ostream*} @var{tie}])
        !          1123: You can also call a constructor with one or two arguments.  The first
        !          1124: argument @var{sb} is a @code{streambuf*}; if you supply this pointer,
        !          1125: the constructor uses that @code{streambuf} for input and output.
        !          1126: 
        !          1127: You can use the optional second argument @var{tie} (an @code{ostream*})
        !          1128: to specify a related output stream as the initial value for
        !          1129: @code{ios::tie}.
        !          1130: @end deftypefn
        !          1131: 
        !          1132: @cindex @code{iostream} destructor
        !          1133: @cindex destructor for @code{iostream}
        !          1134: As for @code{ostream} and @code{istream}, @code{iostream} simply uses
        !          1135: the @code{ios} destructor.  However, an @code{iostream} is not deleted by
        !          1136: its destructor.
        !          1137: 
        !          1138: You can use all the @code{istream}, @code{ostream}, and @code{ios}
        !          1139: methods with an @code{iostream} object.
        !          1140: 
        !          1141: @node Files and Strings
        !          1142: @chapter Classes for Files and Strings
        !          1143: 
        !          1144: There are two very common special cases of input and output: using files,
        !          1145: and using strings in memory.
        !          1146: 
        !          1147: @code{libio} defines four specialized classes for these cases:
        !          1148: 
        !          1149: @ftable @code
        !          1150: @item ifstream
        !          1151: Methods for reading files.
        !          1152: 
        !          1153: @item ofstream
        !          1154: Methods for writing files.
        !          1155: 
        !          1156: @item istrstream
        !          1157: Methods for reading strings from memory.
        !          1158: 
        !          1159: @item ostrstream
        !          1160: Methods for writing strings in memory.
        !          1161: @end ftable
        !          1162: 
        !          1163: @menu
        !          1164: * Files::      Reading and writing files.
        !          1165: * Strings::    Reading and writing strings in memory.
        !          1166: @end menu
        !          1167: 
        !          1168: @node Files
        !          1169: @section Reading and writing files
        !          1170: 
        !          1171: These methods are declared in @file{fstream.h}.
        !          1172: 
        !          1173: @findex ifstream
        !          1174: @cindex class @code{ifstream}
        !          1175: You can read data from class @code{ifstream} with any operation from class
        !          1176: @code{istream}.  There are also a few specialized facilities:
        !          1177: 
        !          1178: @deftypefn Constructor {} ifstream::ifstream ()
        !          1179: Make an @code{ifstream} associated with a new file for input.  (If you
        !          1180: use this version of the constructor, you need to call
        !          1181: @code{ifstream::open} before actually reading anything)
        !          1182: @end deftypefn
        !          1183: 
        !          1184: @deftypefn Constructor {} ifstream::ifstream (int @var{fd})
        !          1185: Make an @code{ifstream} for reading from a file that was already open,
        !          1186: using file descriptor @var{fd}.  (This constructor is compatible with
        !          1187: other versions of iostreams for @sc{posix} systems, but is not part of
        !          1188: the @sc{ansi} working paper.)
        !          1189: @end deftypefn
        !          1190: 
        !          1191: @deftypefn Constructor {} ifstream::ifstream (const char* @var{fname} @w{[, int} @var{mode} @w{[, int} @var{prot}]])
        !          1192: Open a file @code{*@var{fname}} for this @code{ifstream} object.
        !          1193: 
        !          1194: By default, the file is opened for input (with @code{ios::in} as
        !          1195: @var{mode}).  If you use this constructor, the file will be closed when
        !          1196: the @code{ifstream} is destroyed.
        !          1197: 
        !          1198: You can use the optional argument @var{mode} to specify how to open the
        !          1199: file, by combining these enumerated values (with @samp{|} bitwise or).
        !          1200: (These values are actually defined in class @code{ios}, so that all
        !          1201: file-related streams may inherit them.)  Only some of these modes are
        !          1202: defined in the latest draft @sc{ansi} specification; if portability is
        !          1203: important, you may wish to avoid the others.
        !          1204: 
        !          1205: @vtable @code
        !          1206: @item ios::in
        !          1207: Open for input.  (Included in @sc{ansi} draft.)
        !          1208: 
        !          1209: @item ios::out
        !          1210: Open for output.  (Included in @sc{ansi} draft.)
        !          1211: 
        !          1212: @item ios::ate
        !          1213: Set the initial input (or output) position to the end of the file.
        !          1214: 
        !          1215: @item ios::app
        !          1216: Seek to end of file before each write.  (Included in @sc{ansi} draft.)
        !          1217: 
        !          1218: @item ios::trunc
        !          1219: Guarantee a fresh file; discard any contents that were previously
        !          1220: associated with it.
        !          1221: 
        !          1222: @item ios::nocreate
        !          1223: Guarantee an existing file; fail if the specified file did not already
        !          1224: exist.
        !          1225: 
        !          1226: @item ios::noreplace
        !          1227: Guarantee a new file; fail if the specified file already existed.
        !          1228: 
        !          1229: @item ios::bin
        !          1230: Open as a binary file (on systems where binary and text files have different
        !          1231: properties, typically how @samp{\n} is mapped; included in @sc{ansi} draft).
        !          1232: @end vtable
        !          1233: 
        !          1234: @noindent
        !          1235: The last optional argument @var{prot} is specific to Unix-like systems;
        !          1236: it specifies the file protection (by default @samp{644}).
        !          1237: @end deftypefn
        !          1238: 
        !          1239: @deftypefn Method void ifstream::open (const char* @var{fname} @w{[, int} @var{mode} @w{[, int} @var{prot}]])
        !          1240: Open a file explicitly after the associated @code{ifstream} object
        !          1241: already exists (for instance, after using the default constructor).  The
        !          1242: arguments, options and defaults all have the same meanings as in the
        !          1243: fully specified @code{ifstream} constructor.
        !          1244: @end deftypefn
        !          1245: 
        !          1246: @findex ostream
        !          1247: @cindex class @code{ostream}
        !          1248: You can write data to class @code{ofstream} with any operation from class
        !          1249: @code{ostream}.  There are also a few specialized facilities:
        !          1250: 
        !          1251: @deftypefn Constructor {} ofstream::ofstream ()
        !          1252: Make an @code{ofstream} associated with a new file for output.
        !          1253: @end deftypefn
        !          1254: 
        !          1255: @deftypefn Constructor {} ofstream::ofstream (int @var{fd})
        !          1256: Make an @code{ofstream} for writing to a file that was already open,
        !          1257: using file descriptor @var{fd}.
        !          1258: @end deftypefn
        !          1259: 
        !          1260: @deftypefn Constructor {} ofstream::ofstream (const char* @var{fname} @w{[, int} @var{mode} @w{[, int} @var{prot}]])
        !          1261: Open a file @code{*@var{fname}} for this @code{ofstream} object.
        !          1262: 
        !          1263: By default, the file is opened for output (with @code{ios::out} as @var{mode}).
        !          1264: You can use the optional argument @var{mode} to specify how to open the
        !          1265: file, just as described for @code{ifstream::ifstream}.
        !          1266: 
        !          1267: The last optional argument @var{prot} specifies the file protection (by
        !          1268: default @samp{644}).
        !          1269: @end deftypefn
        !          1270: 
        !          1271: @deftypefn Destructor {} ofstream::~ofstream ()
        !          1272: The files associated with @code{ofstream} objects are closed when the
        !          1273: corresponding object is destroyed.
        !          1274: @end deftypefn
        !          1275: 
        !          1276: @deftypefn Method void ofstream::open (const char* @var{fname} @w{[, int} @var{mode} @w{[, int} @var{prot}]])
        !          1277: Open a file explicitly after the associated @code{ofstream} object
        !          1278: already exists (for instance, after using the default constructor).  The
        !          1279: arguments, options and defaults all have the same meanings as in the
        !          1280: fully specified @code{ofstream} constructor.
        !          1281: @end deftypefn
        !          1282: 
        !          1283: @findex fstream
        !          1284: @cindex class @code{fstream}
        !          1285: The class @code{fstream} combines the facilities of @code{ifstream} and
        !          1286: @code{ofstream}, just as @code{iostream} combines @code{istream} and
        !          1287: @code{ostream}.
        !          1288: 
        !          1289: @c FIXME-future: say something about fstream constructor, maybe.
        !          1290: 
        !          1291: @findex fstreambase
        !          1292: @cindex class @code{fstreambase}
        !          1293: The class @code{fstreambase} underlies both @code{ifstream} and
        !          1294: @code{ofstream}.  They both inherit this additional method:
        !          1295: 
        !          1296: @deftypefn Method void fstreambase::close ()
        !          1297: Close the file associated with this object, and set @code{ios::fail} in
        !          1298: this object to mark the event.
        !          1299: @end deftypefn
        !          1300: 
        !          1301: @node Strings
        !          1302: @section Reading and writing in memory
        !          1303: 
        !          1304: @c FIXME!! Per, there's a lot of guesswork here---please check carefully!
        !          1305: 
        !          1306: @findex istrstream
        !          1307: @cindex class @code{istrstream}
        !          1308: @findex ostrstream
        !          1309: @cindex class @code{ostrstream}
        !          1310: @findex strstream
        !          1311: @cindex class @code{strstream}
        !          1312: @findex strstreambase
        !          1313: @cindex class @code{strstreambase}
        !          1314: @findex strstreambuf
        !          1315: @cindex class @code{strstreambuf}
        !          1316: The classes @code{istrstream}, @code{ostrstream}, and @code{strstream}
        !          1317: provide some additional features for reading and writing strings in
        !          1318: memory---both static strings, and dynamically allocated strings.  The
        !          1319: underlying class @code{strstreambase} provides some features common to
        !          1320: all three; @code{strstreambuf} underlies that in turn.
        !          1321: 
        !          1322: @c FIXME-future:  Document strstreambuf methods one day, when we document
        !          1323: @c streambuf more fully.
        !          1324: 
        !          1325: @deftypefn Constructor {} istrstream::istrstream (const char* @var{str} @w{[, int} @var{size}])
        !          1326: Associate the new input string class @code{istrstream} with an existing
        !          1327: static string starting at @var{str}, of size @var{size}.  If you do not
        !          1328: specify @var{size}, the string is treated as a @code{NUL} terminated string.
        !          1329: @end deftypefn
        !          1330: 
        !          1331: @deftypefn Constructor {} ostrstream::ostrstream ()
        !          1332: Create a new stream for output to a dynamically managed string, which
        !          1333: will grow as needed.
        !          1334: @end deftypefn
        !          1335: 
        !          1336: @deftypefn Constructor {} ostrstream::ostrstream (char* @var{str}, int @var{size} [,int @var{mode}])
        !          1337: A new stream for output to a statically defined string of length
        !          1338: @var{size}, starting at @var{str}.  You may optionally specify one of
        !          1339: the modes described for @code{ifstream::ifstream}; if you do not specify
        !          1340: one, the new stream is simply open for output, with mode @code{ios::out}.
        !          1341: @end deftypefn
        !          1342: 
        !          1343: @deftypefn Method int ostrstream::pcount ()
        !          1344: Report the current length of the string associated with this @code{ostrstream}.
        !          1345: @end deftypefn
        !          1346: 
        !          1347: @deftypefn Method char* ostrstream::str ()
        !          1348: A pointer to the string managed by this @code{ostrstream}.  Implies
        !          1349: @samp{ostrstream::freeze()}.
        !          1350: @end deftypefn
        !          1351: 
        !          1352: @deftypefn Method void ostrstream::freeze ([int @var{n}])
        !          1353: If @var{n} is nonzero (the default), declare that the string associated
        !          1354: with this @code{ostrstream} is not to change dynamically; while frozen,
        !          1355: it will not be reallocated if it needs more space, and it will not be
        !          1356: deallocated when the @code{ostrstream} is destroyed.  Use
        !          1357: @samp{freeze(1)} if you refer to the string as a pointer after creating
        !          1358: it via @code{ostrstream} facilities.
        !          1359: 
        !          1360: @samp{freeze(0)} cancels this declaration, allowing a dynamically
        !          1361: allocated string to be freed when its @code{ostrstream} is destroyed.
        !          1362: 
        !          1363: If this @code{ostrstream} is already static---that is, if it was created
        !          1364: to manage an existing statically allocated string---@code{freeze} is
        !          1365: unnecessary, and has no effect.
        !          1366: @end deftypefn
        !          1367: 
        !          1368: @deftypefn Method int ostrstream::frozen ()
        !          1369: Test whether @code{freeze(1)} is in effect for this string.
        !          1370: @end deftypefn
        !          1371: 
        !          1372: @deftypefn Method strstreambuf* strstreambase::rdbuf ()
        !          1373: A pointer to the underlying @code{strstreambuf}.
        !          1374: @end deftypefn
        !          1375: 
        !          1376: @node Streambuf
        !          1377: @chapter Using the @code{streambuf} Layer
        !          1378: 
        !          1379: The @code{istream} and @code{ostream} classes are meant to handle
        !          1380: conversion between objects in your program and their textual representation.
        !          1381: 
        !          1382: By contrast, the underlying @code{streambuf} class is for transferring
        !          1383: raw bytes between your program, and input sources or output sinks.
        !          1384: Different @code{streambuf} subclasses connect to different kinds of
        !          1385: sources and sinks.
        !          1386: 
        !          1387: The @sc{gnu} implementation of @code{streambuf} is still evolving; we
        !          1388: describe only some of the highlights.
        !          1389: 
        !          1390: @menu
        !          1391: * Areas::              Areas in a streambuf.
        !          1392: * Formatting::         C-style formatting for streambuf objects.
        !          1393: * Stdiobuf::           Wrappers for C stdio.
        !          1394: * Backing Up::         Marking and returning to a position.
        !          1395: * Indirectbuf::                Forwarding I/O activity.
        !          1396: @end menu
        !          1397: 
        !          1398: @node Areas
        !          1399: @section Areas of a @code{streambuf}
        !          1400: 
        !          1401: Streambuf buffer management is fairly sophisticated (this is a
        !          1402: nice way to say ``complicated'').  The standard protocol
        !          1403: has the following ``areas'':
        !          1404: 
        !          1405: @itemize @bullet
        !          1406: @item
        !          1407: @cindex put area
        !          1408: The @dfn{put area} contains characters waiting for output.
        !          1409: 
        !          1410: @item
        !          1411: @cindex get area
        !          1412: The @dfn{get area} contains characters available for reading.
        !          1413: @end itemize
        !          1414: 
        !          1415: The @sc{gnu} @code{streambuf} design extends this, but the details are
        !          1416: still evolving.
        !          1417: 
        !          1418: @node Formatting
        !          1419: @section C-style formatting for @code{streambuf} objects
        !          1420: 
        !          1421: The @sc{gnu} @code{streambuf} class supports @code{printf}-like
        !          1422: formatting and scanning.
        !          1423: 
        !          1424: @deftypefn Method int streambuf::vform (const char *@var{format}, ...)
        !          1425: Similar to @code{fprintf(@var{file}, @var{format}, ...)}.
        !          1426: The @var{format} is a @code{printf}-style format control string, which is used
        !          1427: to format the (variable number of) arguments, printing the result on
        !          1428: the @code{this} streambuf.  The result is the number of characters printed.
        !          1429: @end deftypefn
        !          1430: 
        !          1431: @deftypefn Method int streambuf::vform (const char *@var{format}, va_list @var{args})
        !          1432: Similar to @code{vfprintf(@var{file}, @var{format}, @var{args})}.
        !          1433: The @var{format} is a @code{printf}-style format control string, which is used
        !          1434: to format the argument list @var{args}, printing the result on
        !          1435: the @code{this} streambuf.  The result is the number of characters printed.
        !          1436: @end deftypefn
        !          1437: 
        !          1438: @deftypefn Method int streambuf::scan (const char *@var{format}, ...)
        !          1439: Similar to @code{fscanf(@var{file}, @var{format}, ...)}.
        !          1440: The @var{format} is a @code{scanf}-style format control string, which is used
        !          1441: to read the (variable number of) arguments from the @code{this} streambuf.
        !          1442: The result is the number of items assigned, or @code{EOF} in case of
        !          1443: input failure before any conversion.
        !          1444: @end deftypefn
        !          1445: 
        !          1446: @deftypefn Method int streambuf::vscan (const char *@var{format}, va_list @var{args})
        !          1447: Like @code{streambuf::scan}, but takes a single @code{va_list} argument.
        !          1448: @end deftypefn
        !          1449: 
        !          1450: @node Stdiobuf
        !          1451: @section Wrappers for C @code{stdio}
        !          1452: 
        !          1453: A @dfn{stdiobuf} is a @code{streambuf} object that points to
        !          1454: a @code{FILE} object (as defined by @code{stdio.h}).
        !          1455: All @code{streambuf} operations on the @code{stdiobuf} are forwarded
        !          1456: to the @code{FILE}.  Thus the @code{stdiobuf} object provides a
        !          1457: wrapper around a @code{FILE}, allowing use of @code{streambuf}
        !          1458: operations on a @code{FILE}.  This can be useful when mixing
        !          1459: C code with C++ code.
        !          1460: 
        !          1461: The pre-defined streams @code{cin}, @code{cout}, and @code{cerr} are
        !          1462: normally implemented as @code{stdiobuf} objects that point to
        !          1463: respectively @code{stdin}, @code{stdout}, and @code{stderr}.  This is
        !          1464: convenient, but it does cost some extra overhead.
        !          1465: 
        !          1466: If you set things up to use the implementation of @code{stdio} provided
        !          1467: with this library, then @code{cin}, @code{cout}, and @code{cerr} will be
        !          1468: set up to to use @code{stdiobuf} objects, since you get their benefits
        !          1469: for free.  @xref{Stdio,,C Input and Output}.
        !          1470: 
        !          1471: @ignore
        !          1472: @c FIXME-future: setbuf is not yet documented, hence this para is not useful.
        !          1473: Note that if you use @code{setbuf} to give a buffer to a @code{stdiobuf},
        !          1474: that buffer will provide intermediate buffering in addition that
        !          1475: whatever is done by the @code{FILE}.
        !          1476: @end ignore
        !          1477: 
        !          1478: @node Backing Up
        !          1479: @section Backing up
        !          1480: 
        !          1481: The @sc{gnu} iostream library allows you to ask a @code{streambuf} to
        !          1482: remember the current position.  This allows you to go back to this
        !          1483: position later, after reading further.  You can back up arbitrary
        !          1484: amounts, even on unbuffered files or multiple buffers' worth, as long as
        !          1485: you tell the library in advance.  This unbounded backup is very useful
        !          1486: for scanning and parsing applications.  This example shows a typical
        !          1487: scenario:
        !          1488: 
        !          1489: @cartouche
        !          1490: @smallexample
        !          1491: // Read either "dog", "hound", or "hounddog".
        !          1492: // If "dog" is found, return 1.
        !          1493: // If "hound" is found, return 2.
        !          1494: // If "hounddog" is found, return 3.
        !          1495: // If none of these are found, return -1.
        !          1496: int my_scan(streambuf* sb)
        !          1497: @{
        !          1498:     streammarker fence(sb);
        !          1499:     char buffer[20];
        !          1500:     // Try reading "hounddog":
        !          1501:     if (sb->sgetn(buffer, 8) == 8
        !          1502:         && strncmp(buffer, "hounddog", 8) == 0)
        !          1503:       return 3;
        !          1504:     // No, no "hounddog":  Back up to 'fence'
        !          1505:     sb->seekmark(fence); // 
        !          1506:     // ... and try reading "dog":
        !          1507:     if (sb->sgetn(buffer, 3) == 3
        !          1508:         && strncmp(buffer, "dog", 3) == 0)
        !          1509:       return 1;
        !          1510:     // No, no "dog" either:  Back up to 'fence'
        !          1511:     sb->seekmark(fence); // 
        !          1512:     // ... and try reading "hound":
        !          1513:     if (sb->sgetn(buffer, 5) == 5
        !          1514:         && strncmp(buffer, "hound", 5) == 0)
        !          1515:       return 2;
        !          1516:     // No, no "hound" either:  Back up and signal failure.
        !          1517:     sb->seekmark(fence); // Backup to 'fence'
        !          1518:     return -1;
        !          1519: @}
        !          1520: @end smallexample
        !          1521: @end cartouche
        !          1522: 
        !          1523: @deftypefn Constructor {} streammarker::streammarker (streambuf* @var{sbuf})
        !          1524: Create a @code{streammarker} associated with @var{sbuf}
        !          1525: that remembers the current position of the get pointer.
        !          1526: @end deftypefn
        !          1527: 
        !          1528: @deftypefn Method int streammarker::delta (streammarker& @var{mark2})
        !          1529: Return the difference between the get positions corresponding
        !          1530: to @code{*this} and @var{mark2} (which must point into the same
        !          1531: @code{streambuffer} as @code{this}).
        !          1532: @end deftypefn
        !          1533: 
        !          1534: @deftypefn Method int streammarker::delta ()
        !          1535: Return the position relative to the streambuffer's current get position.
        !          1536: @end deftypefn
        !          1537: 
        !          1538: @deftypefn Method int streambuffer::seekmark (streammarker& @var{mark})
        !          1539: Move the get pointer to where it (logically) was when @var{mark}
        !          1540: was constructed.
        !          1541: @end deftypefn
        !          1542: 
        !          1543: @node Indirectbuf
        !          1544: @section Forwarding I/O activity
        !          1545: 
        !          1546: An @dfn{indirectbuf} is one that forwards all of its I/O requests
        !          1547: to another streambuf.
        !          1548: 
        !          1549: @ignore
        !          1550: @c FIXME-future: get_stream and put_stream are so far undocumented.
        !          1551: All get-related requests are sent to get_stream().
        !          1552: All put-related requests are sent to put_stream().
        !          1553: @end ignore
        !          1554: 
        !          1555: An @code{indirectbuf} can be used to implement Common Lisp
        !          1556: synonym-streams and two-way-streams:
        !          1557: 
        !          1558: @example
        !          1559: class synonymbuf : public indirectbuf @{
        !          1560:    Symbol *sym;
        !          1561:    synonymbuf(Symbol *s) @{ sym = s; @}
        !          1562:    virtual streambuf *lookup_stream(int mode) @{
        !          1563:        return coerce_to_streambuf(lookup_value(sym)); @}
        !          1564: @};
        !          1565: @end example
        !          1566: 
        !          1567: @node Stdio
        !          1568: @chapter C Input and Output
        !          1569: 
        !          1570: @code{libio} is distributed with a complete implementation of the ANSI C
        !          1571: @code{stdio} facility.  It is implemented using @code{streambuf}
        !          1572: objects.  @xref{Stdiobuf,,Wrappers for C @code{stdio}}.
        !          1573: 
        !          1574: The @code{stdio} package is intended as a replacement for the whatever
        !          1575: @code{stdio} is in your C library.
        !          1576: @ignore
        !          1577: @c FIXME-future:  This is not useful unless we specify what problems.
        !          1578: It can co-exist with C libraries that have alternate implementations of
        !          1579: stdio, but there may be some problems.
        !          1580: @end ignore
        !          1581: Since @code{stdio} works best when you build @code{libc} to contain it, and
        !          1582: that may be inconvenient, it is not installed by default.
        !          1583: 
        !          1584: Extensions beyond @sc{ansi}:
        !          1585: 
        !          1586: @itemize @bullet
        !          1587: @item
        !          1588: A stdio @code{FILE} is identical to a streambuf.
        !          1589: Hence there is no need to worry about synchronizing C and C++
        !          1590: input/output---they are by definition always synchronized.
        !          1591: 
        !          1592: @item
        !          1593: If you create a new streambuf sub-class (in C++), you can use it as a
        !          1594: @code{FILE} from C.  Thus the system is extensible using the standard
        !          1595: @code{streambuf} protocol.
        !          1596: 
        !          1597: @item
        !          1598: You can arbitrarily mix reading and writing, without having to seek
        !          1599: in between.
        !          1600: 
        !          1601: @item
        !          1602: Unbounded @code{ungetc()} buffer.
        !          1603: @end itemize
        !          1604: 
        !          1605: @ignore
        !          1606: @c FIXME-future: Per says this is not ready to go public at v0.5
        !          1607: @node Libio buffer management
        !          1608: @chapter Libio buffer management
        !          1609: 
        !          1610: The libio user functions present an abstract sequence of characters,
        !          1611: that they read and write from.  A number of buffers are used to go
        !          1612: between the user program and the abstract sequence.  These buffers are
        !          1613: concrete arrays of characters that contain some sub-sequence of the
        !          1614: abstract sequence.
        !          1615: 
        !          1616: The libio buffer management protocol is fairly complex.  Its design is
        !          1617: based on the C++ @code{streambuf} protocol, so that the C++
        !          1618: @code{streambuf} classes can be trivially implemented on top of the
        !          1619: libio protocol.
        !          1620: 
        !          1621: The @dfn{write area} contains characters waiting for output.
        !          1622: 
        !          1623: The @dfn{read area} contains characters available for reading.
        !          1624: 
        !          1625: The @dfn{reserve area} is available to virtual methods.
        !          1626: Usually, the get and/or put areas are part of the reserve area.
        !          1627: 
        !          1628: The @dfn{main get area} contains characters that have
        !          1629: been read in from the character source, but not yet
        !          1630: read by the application.
        !          1631: 
        !          1632: The @dfn{backup area} contains previously read data that is being saved
        !          1633: because of a user request, or that have been "unread" (put back).
        !          1634: @end ignore
        !          1635: 
        !          1636: @ignore
        !          1637: @c Per says this design is not finished
        !          1638: @node Streambuf internals
        !          1639: @chapter Streambuf internals
        !          1640: 
        !          1641: @menu
        !          1642: * Buffer management::
        !          1643: * Filebuf internals::
        !          1644: @end menu
        !          1645: 
        !          1646: @node Buffer management
        !          1647: @section Buffer management
        !          1648: 
        !          1649: @subsection Areas
        !          1650: 
        !          1651: NOTE:  This chapter is due for an update.
        !          1652: 
        !          1653: Streambuf buffer management is fairly sophisticated (this is a
        !          1654: nice way to say "complicated").  The standard protocol
        !          1655: has the following "areas":
        !          1656: 
        !          1657: @itemize @bullet
        !          1658: @cindex put area
        !          1659: @item
        !          1660: The @dfn{put area} contains characters waiting for output.
        !          1661: @cindex get area
        !          1662: @item
        !          1663: The @dfn{get area} contains characters available for reading.
        !          1664: @cindex reserve area
        !          1665: @item
        !          1666: The @dfn{reserve area} is available to virtual methods.
        !          1667: Usually, the get and/or put areas are part of the reserve area.
        !          1668: @end itemize
        !          1669: 
        !          1670: The @sc{gnu} @code{streambuf} design extends this by supporting two
        !          1671: get areas:
        !          1672: @itemize @bullet
        !          1673: @cindex main get area
        !          1674: @item
        !          1675: The @dfn{main get area} contains characters that have
        !          1676: been read in from the character source, but not yet
        !          1677: read by the application.
        !          1678: @cindex backup area
        !          1679: @item
        !          1680: The @dfn{backup area} contains previously read data that is being
        !          1681: saved because of a user request, or that have been "unread" (putback).
        !          1682: @end itemize
        !          1683: 
        !          1684: The backup and the main get area are logically contiguous:  That is,
        !          1685: the first character of the main get area follows the last character
        !          1686: of the backup area.
        !          1687: 
        !          1688: The @dfn{current get area} is whichever one of the backup or
        !          1689: main get areas that is currently being read from.
        !          1690: The other of the two is the @dfn{non-current get area}.
        !          1691: 
        !          1692: @subsection Pointers
        !          1693: 
        !          1694: The following @code{char*} pointers define the various areas.
        !          1695: (Note that if a pointer points to the 'end' of an area,
        !          1696: it means that it points to the character after the area.)
        !          1697: 
        !          1698: @deftypefn Method char* streambuffer::base ()
        !          1699: The start of the reserve area.
        !          1700: @end deftypefn
        !          1701: 
        !          1702: @deftypefn Method char* streambuffer::ebuf ()
        !          1703: The end of the reserve area.
        !          1704: @end deftypefn
        !          1705: 
        !          1706: @deftypefn Method char* streambuffer::pbase ()
        !          1707: The start of the put area.
        !          1708: @end deftypefn
        !          1709: 
        !          1710: @deftypefn Method char* streambuffer::pptr ()
        !          1711: The current put position.
        !          1712: If @code{pptr() < epptr()}, then the next write will
        !          1713: overwrite @code{*pptr()}, and increment @code{pptr()}.
        !          1714: @end deftypefn
        !          1715: 
        !          1716: @deftypefn Method char* streambuffer::epptr ()
        !          1717: The end of the put area.
        !          1718: @end deftypefn
        !          1719: 
        !          1720: @deftypefn Method char* streambuffer::eback ()
        !          1721: The start of the current get area.
        !          1722: @end deftypefn
        !          1723: 
        !          1724: @deftypefn Method char* streambuffer::gptr ()
        !          1725: The current get position.
        !          1726: If @code{gptr() < egptr()}, then the next read will
        !          1727: read @code{*gptr()}, and increment @code{gptr()}.
        !          1728: @end deftypefn
        !          1729: 
        !          1730: @deftypefn Method char* streambuffer::egptr ()
        !          1731: The end of the current get area.
        !          1732: @end deftypefn
        !          1733: 
        !          1734: @deftypefn Method char* streambuffer::Gbase ()
        !          1735: The start of the main get area.
        !          1736: @end deftypefn
        !          1737: 
        !          1738: @deftypefn Method char* streambuffer::eGptr ()
        !          1739: The end of the main get area.
        !          1740: @end deftypefn
        !          1741: 
        !          1742: @deftypefn Method char* streambuffer::Bbase ()
        !          1743: The start of the backup area.
        !          1744: @end deftypefn
        !          1745: 
        !          1746: @deftypefn Method char* streambuffer::Bptr ()
        !          1747: The start of the used part of the backup area.
        !          1748: The area (@code{Bptr()} .. @code{eBptr()}) contains data that has been
        !          1749: pushed back, while (@code{Bbase()} .. @code{eBptr()}) contains unused
        !          1750: space available for future putbacks.
        !          1751: @end deftypefn
        !          1752: 
        !          1753: @deftypefn Method char* streambuffer::eBptr ()
        !          1754: The end of the backup area.
        !          1755: @end deftypefn
        !          1756: 
        !          1757: @deftypefn Method char* streambuffer::Nbase ()
        !          1758: The start of the non-current get area (either @code{main_gbase} or @code{backup_gbase}).
        !          1759: @end deftypefn
        !          1760: 
        !          1761: @deftypefn Method char* streambuffer::eNptr ()
        !          1762: The end of the non-current get area.
        !          1763: @end deftypefn
        !          1764: 
        !          1765: @node Filebuf internals
        !          1766: @section Filebuf internals
        !          1767: 
        !          1768: The @code{filebuf} is used a lot, so it is importamt that it be
        !          1769: efficient.  It is also supports rather complex semantics.
        !          1770: so let us examine its implementation.
        !          1771: 
        !          1772: @subsection Tied read and write pointers
        !          1773: 
        !          1774: The streambuf model allows completely independent read and write pointers.
        !          1775: However, a @code{filebuf} has only a single logical pointer used
        !          1776: for both reads and writes.  Since the @code{streambuf} protocol
        !          1777: uses @code{gptr()} for reading and @code{pptr()} for writing,
        !          1778: we map the logical file pointer into either @code{gptr()} or @code{pptr()}
        !          1779: at different times.
        !          1780: 
        !          1781: @itemize @bullet
        !          1782: @item
        !          1783: Reading is allowed when @code{gptr() < egptr()}, which we call get mode.
        !          1784: 
        !          1785: @item
        !          1786: Writing is allowed when @code{pptr() < epptr()}, which we call put mode.
        !          1787: @end itemize
        !          1788: 
        !          1789: @noindent
        !          1790: A @code{filebuf} cannot be in get mode and put mode at the same time.
        !          1791: 
        !          1792: We have up to two buffers:
        !          1793: 
        !          1794: @itemize @bullet
        !          1795: @item
        !          1796: The backup area, defined by @code{Bbase()}, @code{Bptr()}, and @code{eBptr()}.
        !          1797: This can be empty.
        !          1798: 
        !          1799: @item
        !          1800: The reserve area, which also contains the main get area.
        !          1801: For an unbuffered file, the (@code{shortbuf()}..@code{shortbuf()+1}) is used,
        !          1802: where @code{shortbuf()} points to a 1-byte buffer that is part of
        !          1803: the @code{filebuf}.
        !          1804: @end itemize
        !          1805: 
        !          1806: @noindent
        !          1807: The file system's idea of the current position is @code{eGptr()}.
        !          1808: 
        !          1809: Characters that have been written into a buffer but not yet written
        !          1810: out (flushed) to the file systems are those between @code{pbase()}
        !          1811: and @code{pptr()}.
        !          1812: 
        !          1813: The end of the valid data bytes is:
        !          1814: @code{pptr() > eGptr() && pptr() < ebuf() ? pptr() : eGptr()}.
        !          1815: 
        !          1816: If the @code{filebuf} is unbuffered or line buffered,
        !          1817: the @code{eptr()} is @code{pbase()}.  This forces a call
        !          1818: to @code{overflow()} on each put of a character.
        !          1819: The logical @code{epptr()} is @code{epptr() ? ebuf() : NULL}.
        !          1820: (If the buffer is read-only, set @code{pbase()}, @code{pptr()},
        !          1821: and @code{epptr()} to @code{NULL}. NOT!)
        !          1822: @end ignore
        !          1823: 
        !          1824: @node Index
        !          1825: @unnumbered Index
        !          1826: @printindex cp
        !          1827: 
        !          1828: @contents
        !          1829: @bye

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.