---
name: "FileHandle"
section: "3pm"
platform: "linux"
package: "perl-5.004-doc"
version: "5.004.05-6"
release: "Debian 2.2 (Potato)"
platforms: ["linux"]
url: "https://new.carta.tech/FileHandle/3pm"
---

# FileHandle(3pm)

supply object methods for filehandles

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