home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / amiga / programm / language / gcc222.lha / info / iostream.info < prev    next >
Text File  |  1992-07-19  |  12KB  |  359 lines
  1. Info file iostream.info, produced by Makeinfo, -*- Text -*- from input
  2. file iostream.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * iostream: (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
  32. Lu has worked hard to use the library as the default stdio
  33. implementation for Linux, and has provided much stress-testing of the
  34. library.
  35.  
  36.    Some code was derived from parts of BSD 4.4, which is copyright
  37. University of California at Berkeley.
  38.  
  39. 
  40. File: iostream.info,  Node: Using the iostream layer,  Next: Using the streambuf layer,  Prev: Introduction,  Up: Top
  41.  
  42. Using the iostream layer
  43. ************************
  44.  
  45. 
  46. File: iostream.info,  Node: Using the streambuf layer,  Next: stdio - C-style input/output,  Prev: Using the iostream layer,  Up: Top
  47.  
  48. Using the streambuf layer
  49. *************************
  50.  
  51. * Menu:
  52.  
  53. * Backing up::
  54.  
  55. 
  56. File: iostream.info,  Node: Backing up,  Up: Using the streambuf layer
  57.  
  58. Backing up
  59. ==========
  60.  
  61.    The GNU iostream library allows you to ask streambuf to remember
  62. the current position, and then later after you've read further be able
  63. to go back to it.  Your're guaranteed to be able to backup arbitrary
  64. amounts, even on unbuffered files or multiple buffers worth, as long
  65. as you tell the library advance.  This unbounded backup is very useful
  66. for scanning and parsing applications.  This example shows a typical
  67. scenario:
  68.  
  69.      // Read either "dog", "hound", or "hounddog".
  70.      // If "dog" is found, return 1.
  71.      // If "hound" is found, return 2.
  72.      // If "hounddog" is found, return 3.
  73.      // If non of these are found, return -1.
  74.      int my_scan(streambuf* sb)
  75.      {
  76.          streammarker fence(sb);
  77.          char buffer[20];
  78.          // Try reading "hounddog":
  79.          if (sb->sgetn(buffer, 8) == 8 && strncmp(buffer, "hounddog", 8) == 0)
  80.            return 3;
  81.          // No, no "hounddog":  Backup to 'fence' ...
  82.          sb->seekmark(fence); //
  83.          // ... and try reading "dog":
  84.          if (sb->sgetn(buffer, 3) == 3 && strncmp(buffer, "dog", 3) == 0)
  85.            return 1;
  86.          // No, no "dog" either:  Backup to 'fence' ...
  87.          sb->seekmark(fence); //
  88.          // ... and try reading "hound":
  89.          if (sb->sgetn(buffer, 5) == 5 && strncmp(buffer, "hound", 5) == 0)
  90.            return 2;
  91.          // No, no "hound" either:  Backup to 'fence' and signal failure.
  92.          sb->seekmark(fence); // Backup to 'fence'..
  93.          return -1;
  94.      }
  95.  
  96.  * Constructor:  streammarker::streammarker (streambuf* SBUF)
  97.      Create a `streammarker' associated with SBUF that remembers the
  98.      current postion of the get pointer.
  99.  
  100.  * Method: int streammarker::delta (streammarker& MARK2)
  101.      Return the difference between the get positions corresponding to
  102.      `*this' and MARK2 (which must point into the same `streambuffer'
  103.      as `this').
  104.  
  105.  * Method: int streammarker::delta ()
  106.      Return the position relative to the streambuffer's current get
  107.      position.
  108.  
  109.  * Method: int streambuffer::seekmark (streammarker& MARK)
  110.      Move the get pointer to where it (logicly) was when MARK was
  111.      constructed.
  112.  
  113. 
  114. File: iostream.info,  Node: stdio - C-style input/output,  Next: Streambuf internals,  Prev: Using the streambuf layer,  Up: Top
  115.  
  116. stdio: C input/output
  117. *********************
  118.  
  119.    Iostreams is distributed with a complete implementation of the ANSI
  120. C stdio facility.  It is implemented using streambufs.
  121.  
  122.    The stdio package is intended as a replacement for the whatever
  123. stdio is in your C library.  It can co-exist with C libraries that have
  124. alternate implementations of stdio, but there may be some problems. 
  125. Since stdio works best when you build libc to contain it, and that may
  126. be inconvenient, it is not installed by default.
  127.  
  128.    Extensions beyond ANSI:
  129.  
  130.    * A stdio FILE is identical to a streambuf.  Hence there is no need
  131.      to worry about synchronizing C and C++ input/output - they are by
  132.      definition always synchronized.
  133.  
  134.    * If you create a new streambuf sub-class (in C++), you can use it
  135.      as a FILE from C.  Thus the system is extensible using the
  136.      standard streambuf protocol.
  137.  
  138.    * You can arbitrarily mix reading and writing, without having to
  139.      seek in between.
  140.  
  141.    * Unbounded ungetc() buffer.
  142.  
  143. 
  144. File: iostream.info,  Node: Streambuf internals,  Next: Function and Variable Index,  Prev: stdio - C-style input/output,  Up: Top
  145.  
  146. Streambuf internals
  147. *******************
  148.  
  149. * Menu:
  150.  
  151. * Buffer management::
  152. * Filebuf internals::
  153.  
  154. 
  155. File: iostream.info,  Node: Buffer management,  Next: Filebuf internals,  Up: Streambuf internals
  156.  
  157. Buffer management
  158. =================
  159.  
  160. Areas
  161. -----
  162.  
  163.    Streambuf buffer management is fairly sophisticated (this is a nice
  164. way to say "complicated").  The standard protocol has the following
  165. "areas":
  166.  
  167.    * The "put area" contains characters waiting for output.
  168.  
  169.    * The "get area" contains characters available for reading.
  170.  
  171.    * The "reserve area" is available to virtual methods.  Usually, the
  172.      get and/or put areas are part of the reserve area.
  173.  
  174.    The GNU streambuf design extends this by supporting two get areas:
  175.  
  176.    * The "main get area" contains characters that have been read in
  177.      from the character source, but not yet read by the application.
  178.  
  179.    * The "backup area" contains previously read data that is being
  180.      saved because of a user request, or that have been "unread"
  181.      (putback).
  182.  
  183.    The backup and the main get area are logically contiguous:  That is,
  184. the first character of the main get area follows the last character of
  185. the backup area.
  186.  
  187.    The "current get area" is whichever one of the backup or main get
  188. areas that is currently being read from.  The other of the two is the
  189. "non-current get area".
  190.  
  191. Pointers
  192. --------
  193.  
  194.    The following `char*' pointers define the various areas.  (Note
  195. that if a pointer points to the 'end' of an area, it means that it
  196. points to the character after the area.)
  197.  
  198.  * Method: char* streambuffer::base ()
  199.      The start of the reserve area.
  200.  
  201.  * Method: char* streambuffer::ebuf ()
  202.      The end of the reserve area.
  203.  
  204.  * Method: char* streambuffer::pbase ()
  205.      The start of the put area.
  206.  
  207.  * Method: char* streambuffer::pptr ()
  208.      The current put position.  If `pptr() < epptr()', then the next
  209.      write will overwrite `*pptr()', and increment `pptr()'.
  210.  
  211.  * Method: char* streambuffer::epptr ()
  212.      The end of the put area.
  213.  
  214.  * Method: char* streambuffer::eback ()
  215.      The start of the current get area.
  216.  
  217.  * Method: char* streambuffer::gptr ()
  218.      The current get position.  If `gptr() < egptr()', then the next
  219.      read will read `*gptr()', and increment `gptr()'.
  220.  
  221.  * Method: char* streambuffer::egptr ()
  222.      The end of the current get area.
  223.  
  224.  * Method: char* streambuffer::Gbase ()
  225.      The start of the main get area.
  226.  
  227.  * Method: char* streambuffer::eGptr ()
  228.      The end of the main get area.
  229.  
  230.  * Method: char* streambuffer::Bbase ()
  231.      The start of the backup area.
  232.  
  233.  * Method: char* streambuffer::Bptr ()
  234.      The start of the used part of the backup area.  The area
  235.      (`Bptr()' .. `eBptr()') contains data that has been pushed back,
  236.      while (`Bbase()' .. `eBptr()') contains unused space available
  237.      for future putbacks.
  238.  
  239.  * Method: char* streambuffer::eBptr ()
  240.      The end of the backup area.
  241.  
  242.  * Method: char* streambuffer::Nbase ()
  243.      The start of the non-current get area (either `main_gbase' or
  244.      `backup_gbase').
  245.  
  246.  * Method: char* streambuffer::eNptr ()
  247.      The end of the non-current get area.
  248.  
  249. 
  250. File: iostream.info,  Node: Filebuf internals,  Prev: Buffer management,  Up: Streambuf internals
  251.  
  252. Filebuf internals
  253. =================
  254.  
  255.    The `filebuf' is used a lot, so it is importamt that it be
  256. efficient.  It is also supports rather complex semantics.  so let us
  257. examine its implementation.
  258.  
  259. Tied read and write pointers
  260. ----------------------------
  261.  
  262.    The streambuf model allows completely independent read and write
  263. pointers.  However, a `filebuf' has only a single logical pointer used
  264. for both reads and writes.  Since the `streambuf' protocol uses
  265. `gptr()' for reading and `pptr()' for writing, we map the logical file
  266. pointer into either `gptr()' or `pptr()' at different times.
  267.  
  268.    * Reading is allowed when `gptr() < egptr()', which we call get
  269.      mode.
  270.  
  271.    * Writing is allowed when `pptr() < epptr()', which we call put
  272.      mode.
  273.  
  274.    A `filebuf' cannot be in put get mode and put mode at the same time.
  275.  
  276.    We have upto two buffers:
  277.  
  278.    * The backeup area, defined by `Bbase()', `Bptr()', and `eBptr()'. 
  279.      This can be empty.
  280.  
  281.    * The reserve area, which also contains the main get area.  For an
  282.      unbuffered file, the (`shortbuf()'..`shortbuf()+1') is used,
  283.      where `shortbuf()' points to a 1-byte buffer that is part of the
  284.      `filebuf'.
  285.  
  286.    The file system's idea of the current position is `eGptr()'.
  287.  
  288.    Character that have been written into a buffer but not yet written
  289. out (flushed) to the file systems are those between `pbase()' and
  290. `pptr()'.
  291.  
  292.    The end of the valid data bytes is: `pptr() > eGptr() && pptr() <
  293. ebuf() ? pptr() : eGptr()'.
  294.  
  295.    If the `filebuf' is unbuffered or line buffered, the `eptr()' is
  296. `pbase()'.  This forces a call to `overflow()' on each put of a
  297. character.  The logical `epptr()' is `epptr() ? ebuf() : NULL'.  (If
  298. the buffer is read-only, set `pbase()', `pptr()', and `epptr()' to
  299. `NULL'.)
  300.  
  301. 
  302. File: iostream.info,  Node: Function and Variable Index,  Next: Concept Index,  Prev: Streambuf internals,  Up: Top
  303.  
  304. Function and Variable Index,Concept Index,,Top
  305. **********************************************
  306.  
  307. * Menu:
  308.  
  309. * streambuffer::Bbase:                  Buffer management.
  310. * streambuffer::Bptr:                   Buffer management.
  311. * streambuffer::Gbase:                  Buffer management.
  312. * streambuffer::Nbase:                  Buffer management.
  313. * streambuffer::base:                   Buffer management.
  314. * streambuffer::eBptr:                  Buffer management.
  315. * streambuffer::eGptr:                  Buffer management.
  316. * streambuffer::eNptr:                  Buffer management.
  317. * streambuffer::eback:                  Buffer management.
  318. * streambuffer::ebuf:                   Buffer management.
  319. * streambuffer::egptr:                  Buffer management.
  320. * streambuffer::epptr:                  Buffer management.
  321. * streambuffer::gptr:                   Buffer management.
  322. * streambuffer::pbase:                  Buffer management.
  323. * streambuffer::pptr:                   Buffer management.
  324. * streambuffer::seekmark:               Backing up.
  325. * streammarker::delta:                  Backing up.
  326. * streammarker::delta:                  Backing up.
  327. * streammarker::streammarker:           Backing up.
  328.  
  329. 
  330. File: iostream.info,  Node: Concept Index,  Prev: Function and Variable Index,  Up: Top
  331.  
  332. Concept Index,,Function and Variable Index,Top
  333. **********************************************
  334.  
  335. * Menu:
  336.  
  337. * backup area:                          Buffer management.
  338. * get area:                             Buffer management.
  339. * main get area:                        Buffer management.
  340. * put area:                             Buffer management.
  341. * reserve area:                         Buffer management.
  342.  
  343.  
  344. 
  345. Tag Table:
  346. Node: Top201
  347. Node: Introduction486
  348. Node: Using the iostream layer981
  349. Node: Using the streambuf layer1153
  350. Node: Backing up1368
  351. Node: stdio - C-style input/output3599
  352. Node: Streambuf internals4733
  353. Node: Buffer management4962
  354. Node: Filebuf internals7964
  355. Node: Function and Variable Index9825
  356. Node: Concept Index11142
  357. 
  358. End Tag Table
  359.