FileHandle(3)

NNAAMMEE
       FileHandle - supply object methods for filehandles

SSYYNNOOPPSSIISS
           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;

DDEESSCCRRIIPPTTIIOONN
       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.

       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:

           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.

SSEEEE AALLSSOO
       The IIOO extension, the perlfunc manpage, the section on I/O
       Operators in the perlop manpage.