


FileHandle(3p)   Perl Programmers Reference Guide  FileHandle(3p)


NAME
       FileHandle - supply object methods for filehandles

SYNOPSIS
           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
       NOTE: This class is now a front-end to the IO::* classes.

       "FileHandle::new" creates a "FileHandle", which is a ref-
       erence to a newly created symbol (see the "Symbol" pack-
       age).  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 "File-
       Handle" object is destroyed.  Otherwise, it is returned to



2001-05-24                 perl v5.6.1                          1





FileHandle(3p)   Perl Programmers Reference Guide  FileHandle(3p)


       the caller.

       "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 previ-
       ously visited position.

       If the C function setvbuf() is available, then "FileHan-
       dle::setvbuf" sets the buffering policy for the FileHan-
       dle.  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




2001-05-24                 perl v5.6.1                          2





FileHandle(3p)   Perl Programmers Reference Guide  FileHandle(3p)


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

           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 I/O Operators
           entry in the perlop manpage except that it's more
           readable and can be safely called in a list context
           but still returns just one line.

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

       There are many other functions available since FileHandle
       is descended from IO::File, IO::Seekable, and IO::Handle.
       Please see those respective pages for documentation on
       more functions.

SEE ALSO
       The IO extension, the perlfunc manpage, the I/O Operators
       entry in the perlop manpage.













2001-05-24                 perl v5.6.1                          3


