home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / GCC / GERLIB_DEV08B.LHA / gerlib / libg++ / iostream / iostream.info < prev    next >
Encoding:
GNU Info File  |  1993-12-12  |  16.7 KB  |  472 lines
  1. This is Info file iostream.info, produced by Makeinfo-1.52 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. 
  9. File: iostream.info,  Node: Top,  Next: Introduction,  Prev: (DIR),  Up: (DIR)
  10.  
  11. * Menu:
  12.  
  13. * Introduction::
  14. * Using the iostream layer::
  15. * Using the streambuf layer::
  16. * stdio - C-style input/output::
  17. * Streambuf internals::
  18.  
  19. Indices:
  20. * Function and Variable Index::
  21. * Concept Index::
  22.  
  23. 
  24. File: iostream.info,  Node: Introduction,  Next: Using the iostream layer,  Prev: Top,  Up: Top
  25.  
  26. Introduction
  27. ************
  28.  
  29.    The `iostream' library was written by Per Bothner.
  30.  
  31.    Various people have found bugs or come with suggestions.  Hongjiu Lu
  32. has worked hard to use the library as the default stdio implementation
  33. for Linux, and has provided much stress-testing of the library.
  34.  
  35.    Some code was derived from parts of BSD 4.4, which is copyright
  36. University of California at Berkeley.
  37.  
  38. 
  39. File: iostream.info,  Node: Using the iostream layer,  Next: Using the streambuf layer,  Prev: Introduction,  Up: Top
  40.  
  41. Using the iostream layer
  42. ************************
  43.  
  44. * Menu:
  45.  
  46. * C-style formatting for streams::
  47.  
  48. 
  49. File: iostream.info,  Node: C-style formatting for streams,  Up: Using the iostream layer
  50.  
  51. C-style formatting for streams
  52. ==============================
  53.  
  54.    These methods all return `*this'.
  55.  
  56.  - Method: ostream& ostream::vform(const char *FORMAT, ...)
  57.      Similar to `fprintf(FILE, FORMAT, ...)'.  The FORMAT is a
  58.      `printf'-style format control string, which is used to format the
  59.      (variable number of) arguments, printing the result on the `this'
  60.      stream.
  61.  
  62.  - Method: ostream& ostream::vform(const char *FORMAT, va_list ARGS)
  63.      Similar to `vfprintf(FILE, FORMAT, ARGS)'.  The FORMAT is a
  64.      `printf'-style format control string, which is used to format the
  65.      argument list ARGS, printing the result on the `this' stream.
  66.  
  67.  - Method: istream& istream::scan(const char *FORMAT, ...)
  68.      Similar to `fscanf(FILE, FORMAT, ...)'.  The FORMAT is a
  69.      `scanf'-style format control string, which is used to read the
  70.      (variable number of) arguments from the `this' stream.
  71.  
  72.  - Method: istream& istream::vscan(const char *FORMAT, va_list ARGS)
  73.      Like `istream::scan', but takes a single `va_list' argument.
  74.  
  75. 
  76. File: iostream.info,  Node: Using the streambuf layer,  Next: stdio - C-style input/output,  Prev: Using the iostream layer,  Up: Top
  77.  
  78. Using the streambuf layer
  79. *************************
  80.  
  81. * Menu:
  82.  
  83. * C-style formatting for streambufs::
  84. * stdiobuf::
  85. * indirectbuf::
  86. * Backing up::
  87.  
  88. 
  89. File: iostream.info,  Node: C-style formatting for streambufs,  Next: stdiobuf,  Up: Using the streambuf layer
  90.  
  91. C-style formatting for streambufs
  92. =================================
  93.  
  94.    The GNU streambuf class supports `printf'-like formatting.
  95.  
  96.  - Method: int streambuf::vform(const char *FORMAT, ...)
  97.      Similar to `fprintf(FILE, FORMAT, ...)'.  The FORMAT is a
  98.      `printf'-style format control string, which is used to format the
  99.      (variable number of) arguments, printing the result on the `this'
  100.      streambuf.  The result is the number of characters printed.
  101.  
  102.  - Method: int streambuf::vform(const char *FORMAT, va_list ARGS)
  103.      Similar to `vfprintf(FILE, FORMAT, ARGS)'.  The FORMAT is a
  104.      `printf'-style format control string, which is used to format the
  105.      argument list ARGS, printing the result on the `this' streambuf.
  106.      The result is the number of characters printed.
  107.  
  108.  - Method: int streambuf::scan(const char *FORMAT, ...)
  109.      Similar to `fscanf(FILE, FORMAT, ...)'.  The FORMAT is a
  110.      `scanf'-style format control string, which is used to read the
  111.      (variable number of) arguments from the `this' streambuf.  The
  112.      result is the number of items assigned, or `EOF' in case of input
  113.      failure before any conversion.
  114.  
  115.  - Method: int streambuf::vscan(const char *FORMAT, va_list ARGS)
  116.      Like `streambuf::scan', but takes a single `va_list' argument.
  117.  
  118. 
  119. File: iostream.info,  Node: stdiobuf,  Next: indirectbuf,  Prev: C-style formatting for streambufs,  Up: Using the streambuf layer
  120.  
  121. stdiobuf
  122. ========
  123.  
  124.    A "stdiobuf" is a `streambuf' object that points to a `FILE' object
  125. (as defined by `stdio.h').  All `streambuf' operations on the
  126. `stdiobuf' are forwarded to the `FILE'.  Thus the `stdiobuf' object
  127. provides a wrapper around a `FILE', allowing use of `streambuf'
  128. operations on a `FILE'.  This can be useful when mixing C code with C++
  129. code.
  130.  
  131.    The pre-defined streams `cin', `cout', and `cerr' are normally
  132. implemented as `stdiobuf's that point to respectively `stdin',
  133. `stdout', and `stderr'.  This is convenient, but it does cost some
  134. extra overhead.  (If you have sets things up so that you use the
  135. implementation of stdio provided with this library, then `cin', `cout',
  136. and `cerr' will be set up to ot use `stdiobuf's, since you get their
  137. benefits for free.)
  138.  
  139.    Note that if you use `setbuf' to give a buffer to a `stdiobuf', that
  140. buffer will provide intermediate buffering in addition that whatever is
  141. done by the `FILE'.
  142.  
  143. 
  144. File: iostream.info,  Node: indirectbuf,  Next: Backing up,  Prev: stdiobuf,  Up: Using the streambuf layer
  145.  
  146. indirectbuf
  147. ===========
  148.  
  149.    An "indirectbuf" is one that forwards all of its I/O requests to
  150. another streambuf.  All get-related requests are sent to get_stream().
  151. All put-related requests are sent to put_stream().
  152.  
  153.    An indirectbuf can be used to implement Common Lisp synonym-streams
  154. and two-way-streams:
  155.      class synonymbuf : public indirectbuf {
  156.         Symbol *sym;
  157.         synonymbuf(Symbol *s) { sym = s; }
  158.         virtual streambuf *lookup_stream(int mode) {
  159.             return coerce_to_streambuf(lookup_value(sym)); }
  160.      };
  161.  
  162. 
  163. File: iostream.info,  Node: Backing up,  Prev: indirectbuf,  Up: Using the streambuf layer
  164.  
  165. Backing up
  166. ==========
  167.  
  168.    The GNU iostream library allows you to ask streambuf to remember the
  169. current position, and then later after you've read further be able to
  170. go back to it.  Your're guaranteed to be able to backup arbitrary
  171. amounts, even on unbuffered files or multiple buffers worth, as long as
  172. you tell the library advance.  This unbounded backup is very useful for
  173. scanning and parsing applications.  This example shows a typical
  174. scenario:
  175.  
  176.      // Read either "dog", "hound", or "hounddog".
  177.      // If "dog" is found, return 1.
  178.      // If "hound" is found, return 2.
  179.      // If "hounddog" is found, return 3.
  180.      // If non of these are found, return -1.
  181.      int my_scan(streambuf* sb)
  182.      {
  183.          streammarker fence(sb);
  184.          char buffer[20];
  185.          // Try reading "hounddog":
  186.          if (sb->sgetn(buffer, 8) == 8 && strncmp(buffer, "hounddog", 8) == 0)
  187.            return 3;
  188.          // No, no "hounddog":  Backup to 'fence' ...
  189.          sb->seekmark(fence); //
  190.          // ... and try reading "dog":
  191.          if (sb->sgetn(buffer, 3) == 3 && strncmp(buffer, "dog", 3) == 0)
  192.            return 1;
  193.          // No, no "dog" either:  Backup to 'fence' ...
  194.          sb->seekmark(fence); //
  195.          // ... and try reading "hound":
  196.          if (sb->sgetn(buffer, 5) == 5 && strncmp(buffer, "hound", 5) == 0)
  197.            return 2;
  198.          // No, no "hound" either:  Backup to 'fence' and signal failure.
  199.          sb->seekmark(fence); // Backup to 'fence'..
  200.          return -1;
  201.      }
  202.  
  203.  - Constructor:  streammarker::streammarker (streambuf* SBUF)
  204.      Create a `streammarker' associated with SBUF that remembers the
  205.      current postion of the get pointer.
  206.  
  207.  - Method: int streammarker::delta (streammarker& MARK2)
  208.      Return the difference between the get positions corresponding to
  209.      `*this' and MARK2 (which must point into the same `streambuffer'
  210.      as `this').
  211.  
  212.  - Method: int streammarker::delta ()
  213.      Return the position relative to the streambuffer's current get
  214.      position.
  215.  
  216.  - Method: int streambuffer::seekmark (streammarker& MARK)
  217.      Move the get pointer to where it (logicly) was when MARK was
  218.      constructed.
  219.  
  220. 
  221. File: iostream.info,  Node: stdio - C-style input/output,  Next: Streambuf internals,  Prev: Using the streambuf layer,  Up: Top
  222.  
  223. stdio: C input/output
  224. *********************
  225.  
  226.    Iostreams is distributed with a complete implementation of the ANSI C
  227. stdio facility.  It is implemented using streambufs.
  228.  
  229.    The stdio package is intended as a replacement for the whatever stdio
  230. is in your C library.  It can co-exist with C libraries that have
  231. alternate implementations of stdio, but there may be some problems.
  232. Since stdio works best when you build libc to contain it, and that may
  233. be inconvenient, it is not installed by default.
  234.  
  235.    Extensions beyond ANSI:
  236.    * A stdio FILE is identical to a streambuf.  Hence there is no need
  237.      to worry about synchronizing C and C++ input/output - they are by
  238.      definition always synchronized.
  239.  
  240.    * If you create a new streambuf sub-class (in C++), you can use it
  241.      as a FILE from C.  Thus the system is extensible using the standard
  242.      streambuf protocol.
  243.  
  244.    * You can arbitrarily mix reading and writing, without having to seek
  245.      in between.
  246.  
  247.    * Unbounded ungetc() buffer.
  248.  
  249. 
  250. File: iostream.info,  Node: Streambuf internals,  Next: Function and Variable Index,  Prev: stdio - C-style input/output,  Up: Top
  251.  
  252. Streambuf internals
  253. *******************
  254.  
  255. * Menu:
  256.  
  257. * Buffer management::
  258. * Filebuf internals::
  259.  
  260. 
  261. File: iostream.info,  Node: Buffer management,  Next: Filebuf internals,  Up: Streambuf internals
  262.  
  263. Buffer management
  264. =================
  265.  
  266. Areas
  267. -----
  268.  
  269.    Streambuf buffer management is fairly sophisticated (this is a nice
  270. way to say "complicated").  The standard protocol has the following
  271. "areas":
  272.  
  273.    * The "put area" contains characters waiting for output.
  274.  
  275.    * The "get area" contains characters available for reading.
  276.  
  277.    * The "reserve area" is available to virtual methods.  Usually, the
  278.      get and/or put areas are part of the reserve area.
  279.  
  280.    The GNU streambuf design extends this by supporting two get areas:
  281.    * The "main get area" contains characters that have been read in
  282.      from the character source, but not yet read by the application.
  283.  
  284.    * The "backup area" contains previously read data that is being
  285.      saved because of a user request, or that have been "unread"
  286.      (putback).
  287.  
  288.    The backup and the main get area are logically contiguous:  That is,
  289. the first character of the main get area follows the last character of
  290. the backup area.
  291.  
  292.    The "current get area" is whichever one of the backup or main get
  293. areas that is currently being read from.  The other of the two is the
  294. "non-current get area".
  295.  
  296. Pointers
  297. --------
  298.  
  299.    The following `char*' pointers define the various areas.  (Note that
  300. if a pointer points to the 'end' of an area, it means that it points to
  301. the character after the area.)
  302.  
  303.  - Method: char* streambuffer::base ()
  304.      The start of the reserve area.
  305.  
  306.  - Method: char* streambuffer::ebuf ()
  307.      The end of the reserve area.
  308.  
  309.  - Method: char* streambuffer::pbase ()
  310.      The start of the put area.
  311.  
  312.  - Method: char* streambuffer::pptr ()
  313.      The current put position.  If `pptr() < epptr()', then the next
  314.      write will overwrite `*pptr()', and increment `pptr()'.
  315.  
  316.  - Method: char* streambuffer::epptr ()
  317.      The end of the put area.
  318.  
  319.  - Method: char* streambuffer::eback ()
  320.      The start of the current get area.
  321.  
  322.  - Method: char* streambuffer::gptr ()
  323.      The current get position.  If `gptr() < egptr()', then the next
  324.      read will read `*gptr()', and increment `gptr()'.
  325.  
  326.  - Method: char* streambuffer::egptr ()
  327.      The end of the current get area.
  328.  
  329.  - Method: char* streambuffer::Gbase ()
  330.      The start of the main get area.
  331.  
  332.  - Method: char* streambuffer::eGptr ()
  333.      The end of the main get area.
  334.  
  335.  - Method: char* streambuffer::Bbase ()
  336.      The start of the backup area.
  337.  
  338.  - Method: char* streambuffer::Bptr ()
  339.      The start of the used part of the backup area.  The area (`Bptr()'
  340.      .. `eBptr()') contains data that has been pushed back, while
  341.      (`Bbase()' .. `eBptr()') contains unused space available for
  342.      future putbacks.
  343.  
  344.  - Method: char* streambuffer::eBptr ()
  345.      The end of the backup area.
  346.  
  347.  - Method: char* streambuffer::Nbase ()
  348.      The start of the non-current get area (either `main_gbase' or
  349.      `backup_gbase').
  350.  
  351.  - Method: char* streambuffer::eNptr ()
  352.      The end of the non-current get area.
  353.  
  354. 
  355. File: iostream.info,  Node: Filebuf internals,  Prev: Buffer management,  Up: Streambuf internals
  356.  
  357. Filebuf internals
  358. =================
  359.  
  360.    The `filebuf' is used a lot, so it is importamt that it be
  361. efficient.  It is also supports rather complex semantics.  so let us
  362. examine its implementation.
  363.  
  364. Tied read and write pointers
  365. ----------------------------
  366.  
  367.    The streambuf model allows completely independent read and write
  368. pointers.  However, a `filebuf' has only a single logical pointer used
  369. for both reads and writes.  Since the `streambuf' protocol uses
  370. `gptr()' for reading and `pptr()' for writing, we map the logical file
  371. pointer into either `gptr()' or `pptr()' at different times.
  372.  
  373.    * Reading is allowed when `gptr() < egptr()', which we call get mode.
  374.  
  375.    * Writing is allowed when `pptr() < epptr()', which we call put mode.
  376. A `filebuf' cannot be in get mode and put mode at the same time.
  377.  
  378.    We have upto two buffers:
  379.    * The backup area, defined by `Bbase()', `Bptr()', and `eBptr()'.
  380.      This can be empty.
  381.  
  382.    * The reserve area, which also contains the main get area.  For an
  383.      unbuffered file, the (`shortbuf()'..`shortbuf()+1') is used, where
  384.      `shortbuf()' points to a 1-byte buffer that is part of the
  385.      `filebuf'.
  386.  
  387.    The file system's idea of the current position is `eGptr()'.
  388.  
  389.    Character that have been written into a buffer but not yet written
  390. out (flushed) to the file systems are those between `pbase()' and
  391. `pptr()'.
  392.  
  393.    The end of the valid data bytes is: `pptr() > eGptr() && pptr() <
  394. ebuf() ? pptr() : eGptr()'.
  395.  
  396.    If the `filebuf' is unbuffered or line buffered, the `eptr()' is
  397. `pbase()'.  This forces a call to `overflow()' on each put of a
  398. character.  The logical `epptr()' is `epptr() ? ebuf() : NULL'.  (If
  399. the buffer is read-only, set `pbase()', `pptr()', and `epptr()' to
  400. `NULL'. NOT!)
  401.  
  402. 
  403. File: iostream.info,  Node: Function and Variable Index,  Next: Concept Index,  Prev: Streambuf internals,  Up: Top
  404.  
  405. Function and Variable Index,Concept Index,,Top
  406. **********************************************
  407.  
  408. * Menu:
  409.  
  410. * istream::scan:                        C-style formatting for streams.
  411. * istream::vscan:                       C-style formatting for streams.
  412. * ostream::vform:                       C-style formatting for streams.
  413. * ostream::vform:                       C-style formatting for streams.
  414. * streambuf::scan:                      C-style formatting for streambufs.
  415. * streambuf::vform:                     C-style formatting for streambufs.
  416. * streambuf::vform:                     C-style formatting for streambufs.
  417. * streambuf::vscan:                     C-style formatting for streambufs.
  418. * streambuffer::base:                   Buffer management.
  419. * streambuffer::Bbase:                  Buffer management.
  420. * streambuffer::Bptr:                   Buffer management.
  421. * streambuffer::eback:                  Buffer management.
  422. * streambuffer::eBptr:                  Buffer management.
  423. * streambuffer::ebuf:                   Buffer management.
  424. * streambuffer::eGptr:                  Buffer management.
  425. * streambuffer::egptr:                  Buffer management.
  426. * streambuffer::eNptr:                  Buffer management.
  427. * streambuffer::epptr:                  Buffer management.
  428. * streambuffer::Gbase:                  Buffer management.
  429. * streambuffer::gptr:                   Buffer management.
  430. * streambuffer::Nbase:                  Buffer management.
  431. * streambuffer::pbase:                  Buffer management.
  432. * streambuffer::pptr:                   Buffer management.
  433. * streambuffer::seekmark:               Backing up.
  434. * streammarker::delta:                  Backing up.
  435. * streammarker::delta:                  Backing up.
  436. * streammarker::streammarker:           Backing up.
  437.  
  438. 
  439. File: iostream.info,  Node: Concept Index,  Prev: Function and Variable Index,  Up: Top
  440.  
  441. Concept Index,,Function and Variable Index,Top
  442. **********************************************
  443.  
  444. * Menu:
  445.  
  446. * backup area:                          Buffer management.
  447. * get area:                             Buffer management.
  448. * main get area:                        Buffer management.
  449. * put area:                             Buffer management.
  450. * reserve area:                         Buffer management.
  451.  
  452.  
  453. 
  454. Tag Table:
  455. Node: Top201
  456. Node: Introduction486
  457. Node: Using the iostream layer981
  458. Node: C-style formatting for streams1198
  459. Node: Using the streambuf layer2330
  460. Node: C-style formatting for streambufs2612
  461. Node: stdiobuf4009
  462. Node: indirectbuf5094
  463. Node: Backing up5745
  464. Node: stdio - C-style input/output7996
  465. Node: Streambuf internals9128
  466. Node: Buffer management9357
  467. Node: Filebuf internals12358
  468. Node: Function and Variable Index14203
  469. Node: Concept Index16108
  470. 
  471. End Tag Table
  472.