FileHandle

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



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

       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 section on I/O Operators in
       the perlop manpage.













3rd Berkeley Distribution    perl 5.005, patch 02                FileHandle(3)