home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _2602ee824fed47d3a51b2272d4df67a6 < prev    next >
Text File  |  2000-03-23  |  8KB  |  187 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>FileHandle - supply object methods for filehandles</TITLE>
  5. <LINK REL="stylesheet" HREF="../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> FileHandle - supply object methods for filehandles</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  26. </UL>
  27. <!-- INDEX END -->
  28.  
  29. <HR>
  30. <P>
  31. <H1><A NAME="name">NAME</A></H1>
  32. <P>FileHandle - supply object methods for filehandles</P>
  33. <P>
  34. <HR>
  35. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  36. <UL>
  37. <LI>Linux</LI>
  38. <LI>Solaris</LI>
  39. <LI>Windows</LI>
  40. </UL>
  41. <HR>
  42. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  43. <PRE>
  44.     use FileHandle;</PRE>
  45. <PRE>
  46.     $fh = new FileHandle;
  47.     if ($fh->open("< file")) {
  48.         print <$fh>;
  49.         $fh->close;
  50.     }</PRE>
  51. <PRE>
  52.     $fh = new FileHandle "> FOO";
  53.     if (defined $fh) {
  54.         print $fh "bar\n";
  55.         $fh->close;
  56.     }</PRE>
  57. <PRE>
  58.     $fh = new FileHandle "file", "r";
  59.     if (defined $fh) {
  60.         print <$fh>;
  61.         undef $fh;       # automatically closes the file
  62.     }</PRE>
  63. <PRE>
  64.     $fh = new FileHandle "file", O_WRONLY|O_APPEND;
  65.     if (defined $fh) {
  66.         print $fh "corge\n";
  67.         undef $fh;       # automatically closes the file
  68.     }</PRE>
  69. <PRE>
  70.     $pos = $fh->getpos;
  71.     $fh->setpos($pos);</PRE>
  72. <PRE>
  73.     $fh->setvbuf($buffer_var, _IOLBF, 1024);</PRE>
  74. <PRE>
  75.     ($readfh, $writefh) = FileHandle::pipe;</PRE>
  76. <PRE>
  77.     autoflush STDOUT 1;</PRE>
  78. <P>
  79. <HR>
  80. <H1><A NAME="description">DESCRIPTION</A></H1>
  81. <P>NOTE: This class is now a front-end to the IO::* classes.</P>
  82. <P><CODE>FileHandle::new</CODE> creates a <CODE>FileHandle</CODE>, which is a reference to a
  83. newly created symbol (see the <CODE>Symbol</CODE> package).  If it receives any
  84. parameters, they are passed to <CODE>FileHandle::open</CODE>; if the open fails,
  85. the <CODE>FileHandle</CODE> object is destroyed.  Otherwise, it is returned to
  86. the caller.</P>
  87. <P><CODE>FileHandle::new_from_fd</CODE> creates a <CODE>FileHandle</CODE> like <CODE>new</CODE> does.
  88. It requires two parameters, which are passed to <CODE>FileHandle::fdopen</CODE>;
  89. if the fdopen fails, the <CODE>FileHandle</CODE> object is destroyed.
  90. Otherwise, it is returned to the caller.</P>
  91. <P><CODE>FileHandle::open</CODE> accepts one parameter or two.  With one parameter,
  92. it is just a front end for the built-in <A HREF="../lib/Pod/perlfunc.html#item_open"><CODE>open</CODE></A> function.  With two
  93. parameters, the first parameter is a filename that may include
  94. whitespace or other special characters, and the second parameter is
  95. the open mode, optionally followed by a file permission value.</P>
  96. <P>If <CODE>FileHandle::open</CODE> receives a Perl mode string (``>'', ``+<'', etc.)
  97. or a POSIX <CODE>fopen()</CODE> mode string (``w'', ``r+'', etc.), it uses the basic
  98. Perl <A HREF="../lib/Pod/perlfunc.html#item_open"><CODE>open</CODE></A> operator.</P>
  99. <P>If <CODE>FileHandle::open</CODE> is given a numeric mode, it passes that mode
  100. and the optional permissions value to the Perl <A HREF="../lib/Pod/perlfunc.html#item_sysopen"><CODE>sysopen</CODE></A> operator.
  101. For convenience, <CODE>FileHandle::import</CODE> tries to import the O_XXX
  102. constants from the Fcntl module.  If dynamic loading is not available,
  103. this may fail, but the rest of FileHandle will still work.</P>
  104. <P><CODE>FileHandle::fdopen</CODE> is like <A HREF="../lib/Pod/perlfunc.html#item_open"><CODE>open</CODE></A> except that its first parameter
  105. is not a filename but rather a file handle name, a FileHandle object,
  106. or a file descriptor number.</P>
  107. <P>If the C functions <CODE>fgetpos()</CODE> and <CODE>fsetpos()</CODE> are available, then
  108. <CODE>FileHandle::getpos</CODE> returns an opaque value that represents the
  109. current position of the FileHandle, and <CODE>FileHandle::setpos</CODE> uses
  110. that value to return to a previously visited position.</P>
  111. <P>If the C function <CODE>setvbuf()</CODE> is available, then <CODE>FileHandle::setvbuf</CODE>
  112. sets the buffering policy for the FileHandle.  The calling sequence
  113. for the Perl function is the same as its C counterpart, including the
  114. macros <CODE>_IOFBF</CODE>, <CODE>_IOLBF</CODE>, and <CODE>_IONBF</CODE>, except that the buffer
  115. parameter specifies a scalar variable to use as a buffer.  WARNING: A
  116. variable used as a buffer by <CODE>FileHandle::setvbuf</CODE> must not be
  117. modified in any way until the FileHandle is closed or until
  118. <CODE>FileHandle::setvbuf</CODE> is called again, or memory corruption may
  119. result!</P>
  120. <P>See <A HREF="../lib/Pod/perlfunc.html">the perlfunc manpage</A> for complete descriptions of each of the following
  121. supported <CODE>FileHandle</CODE> methods, which are just front ends for the
  122. corresponding built-in functions:</P>
  123. <PRE>
  124.     close
  125.     fileno
  126.     getc
  127.     gets
  128.     eof
  129.     clearerr
  130.     seek
  131.     tell</PRE>
  132. <P>See <A HREF="../lib/Pod/perlvar.html">the perlvar manpage</A> for complete descriptions of each of the following
  133. supported <CODE>FileHandle</CODE> methods:</P>
  134. <PRE>
  135.     autoflush
  136.     output_field_separator
  137.     output_record_separator
  138.     input_record_separator
  139.     input_line_number
  140.     format_page_number
  141.     format_lines_per_page
  142.     format_lines_left
  143.     format_name
  144.     format_top_name
  145.     format_line_break_characters
  146.     format_formfeed</PRE>
  147. <P>Furthermore, for doing normal I/O you might need these:</P>
  148. <DL>
  149. <DT><STRONG><A NAME="item_print">$fh->print</A></STRONG><BR>
  150. <DD>
  151. See <A HREF="../lib/Pod/perlfunc.html#print">print in the perlfunc manpage</A>.
  152. <P></P>
  153. <DT><STRONG><A NAME="item_printf">$fh->printf</A></STRONG><BR>
  154. <DD>
  155. See <A HREF="../lib/Pod/perlfunc.html#printf">printf in the perlfunc manpage</A>.
  156. <P></P>
  157. <DT><STRONG><A NAME="item_getline">$fh->getline</A></STRONG><BR>
  158. <DD>
  159. This works like <$fh> described in <A HREF="../lib/Pod/perlop.html#i/o operators">I/O Operators in the perlop manpage</A>
  160. except that it's more readable and can be safely called in an
  161. array context but still returns just one line.
  162. <P></P>
  163. <DT><STRONG><A NAME="item_getlines">$fh->getlines</A></STRONG><BR>
  164. <DD>
  165. This works like <$fh> when called in an array context to
  166. read all the remaining lines in a file, except that it's more readable.
  167. It will also <CODE>croak()</CODE> if accidentally called in a scalar context.
  168. <P></P></DL>
  169. <P>There are many other functions available since FileHandle is descended
  170. from IO::File, IO::Seekable, and IO::Handle.  Please see those
  171. respective pages for documentation on more functions.</P>
  172. <P>
  173. <HR>
  174. <H1><A NAME="see also">SEE ALSO</A></H1>
  175. <P>The <STRONG>IO</STRONG> extension,
  176. <A HREF="../lib/Pod/perlfunc.html">the perlfunc manpage</A>, 
  177. <A HREF="../lib/Pod/perlop.html#i/o operators">I/O Operators in the perlop manpage</A>.</P>
  178. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  179. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  180. <STRONG><P CLASS=block> FileHandle - supply object methods for filehandles</P></STRONG>
  181. </TD></TR>
  182. </TABLE>
  183.  
  184. </BODY>
  185.  
  186. </HTML>
  187.