FileHandle(3)							 FileHandle(3)

NAME    [Toc]    [Back]

     FileHandle	- supply object	methods	for filehandles

SYNOPSIS    [Toc]    [Back]

	 use FileHandle;

	 $fh = new FileHandle;
	 if ($fh->open "< file") {
	     print <$fh>;
	     $fh->close;
	 }

	 $fh = new FileHandle "> FOO";
	 if (defined $fh) {
	     print $fh "bar\n";
	     $fh->close;
	 }

	 $fh = new FileHandle "file", "r";
	 if (defined $fh) {
	     print <$fh>;
	     undef $fh;	      #	automatically closes the file
	 }

	 $fh = new FileHandle "file", O_WRONLY|O_APPEND;
	 if (defined $fh) {
	     print $fh "corge\n";
	     undef $fh;	      #	automatically closes the file
	 }

	 $pos =	$fh->getpos;
	 $fh->setpos($pos);

	 $fh->setvbuf($buffer_var, _IOLBF, 1024);

	 ($readfh, $writefh) = FileHandle::pipe;

	 autoflush STDOUT 1;

DESCRIPTION    [Toc]    [Back]

     NOTE: This	class is now a front-end to the	IO::* classes.

     FileHandle::new creates a FileHandle, which is a reference	to a newly
     created symbol (see the Symbol package).  If it receives any parameters,
     they are passed to	FileHandle::open; if the open fails, the FileHandle
     object is destroyed.  Otherwise, it is returned to	the caller.

     FileHandle::new_from_fd creates a FileHandle like new does.  It requires
     two parameters, which are passed to FileHandle::fdopen; if	the fdopen
     fails, the	FileHandle object is destroyed.	 Otherwise, it is returned to
     the caller.



									Page 1






FileHandle(3)							 FileHandle(3)



     FileHandle::open accepts one parameter or two.  With one parameter, it is
     just a front end for the built-in open function.  With two	parameters,
     the first parameter is a filename that may	include	whitespace or other
     special characters, and the second	parameter is the open mode, optionally
     followed by a file	permission value.

     If	FileHandle::open receives a Perl mode string (">", "+<", etc.)	or a
     POSIX fopen() mode	string ("w", "r+", etc.), it uses the basic Perl open
     operator.

     If	FileHandle::open is given a numeric mode, it passes that mode and the
     optional permissions value	to the Perl sysopen operator.  For
     convenience, FileHandle::import tries to import the O_XXX constants from
     the Fcntl module.	If dynamic loading is not available, this may fail,
     but the rest of FileHandle	will still work.

     FileHandle::fdopen	is like	open except that its first parameter is	not a
     filename but rather a file	handle name, a FileHandle object, or a file
     descriptor	number.

     If	the C functions	fgetpos() and fsetpos()	are available, then
     FileHandle::getpos	returns	an opaque value	that represents	the current
     position of the FileHandle, and FileHandle::setpos	uses that value	to
     return to a previously visited position.

     If	the C function setvbuf() is available, then FileHandle::setvbuf	sets
     the buffering policy for the FileHandle.  The calling sequence for	the
     Perl function is the same as its C	counterpart, including the macros
     _IOFBF, _IOLBF, and _IONBF, except	that the buffer	parameter specifies a
     scalar variable to	use as a buffer.  WARNING: A variable used as a	buffer
     by	FileHandle::setvbuf must not be	modified in any	way until the
     FileHandle	is closed or until FileHandle::setvbuf is called again,	or
     memory corruption may result!

     See the perlfunc manpage for complete descriptions	of each	of the
     following supported FileHandle methods, which are just front ends for the
     corresponding built-in functions:

	 close
	 fileno
	 getc
	 gets
	 eof
	 clearerr
	 seek
	 tell

     See the perlvar manpage for complete descriptions of each of the
     following supported FileHandle methods:






									Page 2






FileHandle(3)							 FileHandle(3)



	 autoflush
	 output_field_separator
	 output_record_separator
	 input_record_separator
	 input_line_number
	 format_page_number
	 format_lines_per_page
	 format_lines_left
	 format_name
	 format_top_name
	 format_line_break_characters
	 format_formfeed

     Furthermore, for doing normal I/O you might need these:

     $fh->print
	  See the print	entry in the perlfunc manpage.

     $fh->printf
	  See the printf entry in the perlfunc manpage.

     $fh->getline
	  This works like <$fh>	described in the section on I/O	Operators in
	  the perlop manpage except that it's more readable and	can be safely
	  called in an array context but still returns just one	line.

     $fh->getlines
	  This works like <$fh>	when called in an array	context	to read	all
	  the remaining	lines in a file, except	that it's more readable.  It
	  will also croak() if accidentally called in a	scalar context.

SEE ALSO    [Toc]    [Back]

     The IO extension, the perlfunc manpage, the section on I/O	Operators in
     the perlop	manpage.


									PPPPaaaaggggeeee 3333