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