home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / perl5 / FileHandle.z / FileHandle
Encoding:
Text File  |  1998-10-30  |  6.3 KB  |  199 lines
  1.  
  2.  
  3.  
  4. FFFFiiiilllleeeeHHHHaaaannnnddddlllleeee((((3333))))                                                    FFFFiiiilllleeeeHHHHaaaannnnddddlllleeee((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      FileHandle - supply object methods for filehandles
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.          use FileHandle;
  13.  
  14.          $fh = new FileHandle;
  15.          if ($fh->open "< file") {
  16.              print <$fh>;
  17.              $fh->close;
  18.          }
  19.  
  20.          $fh = new FileHandle "> FOO";
  21.          if (defined $fh) {
  22.              print $fh "bar\n";
  23.              $fh->close;
  24.          }
  25.  
  26.          $fh = new FileHandle "file", "r";
  27.          if (defined $fh) {
  28.              print <$fh>;
  29.              undef $fh;       # automatically closes the file
  30.          }
  31.  
  32.          $fh = new FileHandle "file", O_WRONLY|O_APPEND;
  33.          if (defined $fh) {
  34.              print $fh "corge\n";
  35.              undef $fh;       # automatically closes the file
  36.          }
  37.  
  38.          $pos = $fh->getpos;
  39.          $fh->setpos($pos);
  40.  
  41.          $fh->setvbuf($buffer_var, _IOLBF, 1024);
  42.  
  43.          ($readfh, $writefh) = FileHandle::pipe;
  44.  
  45.          autoflush STDOUT 1;
  46.  
  47.  
  48. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  49.      NOTE: This class is now a front-end to the IO::* classes.
  50.  
  51.      FileHandle::new creates a FileHandle, which is a reference to a newly
  52.      created symbol (see the Symbol package).  If it receives any parameters,
  53.      they are passed to FileHandle::open; if the open fails, the FileHandle
  54.      object is destroyed.  Otherwise, it is returned to the caller.
  55.  
  56.      FileHandle::new_from_fd creates a FileHandle like new does.  It requires
  57.      two parameters, which are passed to FileHandle::fdopen; if the fdopen
  58.      fails, the FileHandle object is destroyed.  Otherwise, it is returned to
  59.      the caller.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. FFFFiiiilllleeeeHHHHaaaannnnddddlllleeee((((3333))))                                                    FFFFiiiilllleeeeHHHHaaaannnnddddlllleeee((((3333))))
  71.  
  72.  
  73.  
  74.      FileHandle::open accepts one parameter or two.  With one parameter, it is
  75.      just a front end for the built-in open function.  With two parameters,
  76.      the first parameter is a filename that may include whitespace or other
  77.      special characters, and the second parameter is the open mode, optionally
  78.      followed by a file permission value.
  79.  
  80.      If FileHandle::open receives a Perl mode string (">", "+<", etc.)  or a
  81.      POSIX _f_o_p_e_n() mode string ("w", "r+", etc.), it uses the basic Perl open
  82.      operator.
  83.  
  84.      If FileHandle::open is given a numeric mode, it passes that mode and the
  85.      optional permissions value to the Perl sysopen operator.  For
  86.      convenience, FileHandle::import tries to import the O_XXX constants from
  87.      the Fcntl module.  If dynamic loading is not available, this may fail,
  88.      but the rest of FileHandle will still work.
  89.  
  90.      FileHandle::fdopen is like open except that its first parameter is not a
  91.      filename but rather a file handle name, a FileHandle object, or a file
  92.      descriptor number.
  93.  
  94.      If the C functions _f_g_e_t_p_o_s() and _f_s_e_t_p_o_s() are available, then
  95.      FileHandle::getpos returns an opaque value that represents the current
  96.      position of the FileHandle, and FileHandle::setpos uses that value to
  97.      return to a previously visited position.
  98.  
  99.      If the C function _s_e_t_v_b_u_f() is available, then FileHandle::setvbuf sets
  100.      the buffering policy for the FileHandle.  The calling sequence for the
  101.      Perl function is the same as its C counterpart, including the macros
  102.      _IOFBF, _IOLBF, and _IONBF, except that the buffer parameter specifies a
  103.      scalar variable to use as a buffer.  WARNING: A variable used as a buffer
  104.      by FileHandle::setvbuf must not be modified in any way until the
  105.      FileHandle is closed or until FileHandle::setvbuf is called again, or
  106.      memory corruption may result!
  107.  
  108.      See the _p_e_r_l_f_u_n_c manpage for complete descriptions of each of the
  109.      following supported FileHandle methods, which are just front ends for the
  110.      corresponding built-in functions:
  111.  
  112.          close
  113.          fileno
  114.          getc
  115.          gets
  116.          eof
  117.          clearerr
  118.          seek
  119.          tell
  120.  
  121.      See the _p_e_r_l_v_a_r manpage for complete descriptions of each of the
  122.      following supported FileHandle methods:
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. FFFFiiiilllleeeeHHHHaaaannnnddddlllleeee((((3333))))                                                    FFFFiiiilllleeeeHHHHaaaannnnddddlllleeee((((3333))))
  137.  
  138.  
  139.  
  140.          autoflush
  141.          output_field_separator
  142.          output_record_separator
  143.          input_record_separator
  144.          input_line_number
  145.          format_page_number
  146.          format_lines_per_page
  147.          format_lines_left
  148.          format_name
  149.          format_top_name
  150.          format_line_break_characters
  151.          format_formfeed
  152.  
  153.      Furthermore, for doing normal I/O you might need these:
  154.  
  155.      $fh->print
  156.           See the print entry in the _p_e_r_l_f_u_n_c manpage.
  157.  
  158.      $fh->printf
  159.           See the printf entry in the _p_e_r_l_f_u_n_c manpage.
  160.  
  161.      $fh->getline
  162.           This works like <$fh> described in the section on _I/_O _O_p_e_r_a_t_o_r_s in
  163.           the _p_e_r_l_o_p manpage except that it's more readable and can be safely
  164.           called in an array context but still returns just one line.
  165.  
  166.      $fh->getlines
  167.           This works like <$fh> when called in an array context to read all
  168.           the remaining lines in a file, except that it's more readable.  It
  169.           will also _c_r_o_a_k() if accidentally called in a scalar context.
  170.  
  171. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  172.      The IIIIOOOO extension, the _p_e_r_l_f_u_n_c manpage, the section on _I/_O _O_p_e_r_a_t_o_r_s in
  173.      the _p_e_r_l_o_p manpage.
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.