man FileHandle () - supply object methods for filehandles


FileHandle - supply object methods for filehandles


    use FileHandle;

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

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

    $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->setvbuf($buffer_var, _IOLBF, 1024);

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

    autoflush STDOUT 1;


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

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

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

CWFileHandle::open accepts one parameter or two. With one parameter, it is just a front end for the built-in CWopen 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 CWFileHandle::open receives a Perl mode string (>, +<, etc.) or a POSIX fopen() mode string (w, r+, etc.), it uses the basic Perl CWopen operator.

If CWFileHandle::open is given a numeric mode, it passes that mode and the optional permissions value to the Perl CWsysopen operator. For convenience, CWFileHandle::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.

CWFileHandle::fdopen is like CWopen 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 CWFileHandle::getpos returns an opaque value that represents the current position of the FileHandle, and CWFileHandle::setpos uses that value to return to a previously visited position.

If the C function setvbuf() is available, then CWFileHandle::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 CW_IOFBF, CW_IOLBF, and CW_IONBF, except that the buffer parameter specifies a scalar variable to use as a buffer. WARNING: A variable used as a buffer by CWFileHandle::setvbuf must not be modified in any way until the FileHandle is closed or until CWFileHandle::setvbuf is called again, or memory corruption may result!

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


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


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

See print in perlfunc.
See printf in perlfunc.
This works like <$fh> described in I/O Operators in perlop except that it's more readable and can be safely called in a list context but still returns just one line.
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 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.


The IO extension, perlfunc, I/O Operators in perlop.