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