---
name: "IO::Handle"
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/IO::Handle/3pm"
---

# IO::Handle(3pm)

supply object methods for I/O handles

## NAME

IO::Handle - supply object methods for I/O handles

## SYNOPSIS

```
    use IO::Handle;
```

```
    $fh = new IO::Handle;
    if ($fh->fdopen(fileno(STDIN),"r")) {
        print $fh->getline;
        $fh->close;
    }
```

```
    $fh = new IO::Handle;
    if ($fh->fdopen(fileno(STDOUT),"w")) {
        $fh->print("Some text\n");
    }
```

```
    use IO::Handle '_IOLBF';
    $fh->setvbuf($buffer_var, _IOLBF, 1024);
```

```
    undef $fh;       # automatically closes the file if it's open
```

```
    autoflush STDOUT 1;
```

## DESCRIPTION

`IO::Handle` is the base class for all other IO handle classes. It is not intended that objects of `IO::Handle` would be created directly, but instead `IO::Handle` is inherited from by several other classes in the IO hierarchy.

If you are reading this documentation, looking for a replacement for the `FileHandle` package, then I suggest you read the documentation for `IO::File`

A `IO::Handle` object is a reference to a symbol (see the `Symbol` package)

## CONSTRUCTOR

- new ()

  Creates a new `IO::Handle` object.\

- new\_from\_fd ( FD, MODE )

  Creates a `IO::Handle` like `new` does. It requires two parameters, which are passed to the method `fdopen`; if the fdopen fails, the object is destroyed. Otherwise, it is returned to the caller.

## METHODS

See the *perlfunc* manpage for complete descriptions of each of the following supported `IO::Handle` methods, which are just front ends for the corresponding built-in functions:

```
    close
    fileno
    getc
    eof
    read
    truncate
    stat
    print
    printf
    sysread
    syswrite
```

See the *perlvar* manpage for complete descriptions of each of the following supported `IO::Handle` 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
    format_write
```

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

- $fh-\>fdopen ( FD, MODE )

  `fdopen` is like an ordinary `open` except that its first parameter is not a filename but rather a file handle name, a IO::Handle object, or a file descriptor number.\

- $fh-\>opened

  Returns true if the object is currently a valid file descriptor.\

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

- $fh-\>ungetc ( ORD )

  Pushes a character with the given ordinal value back onto the given handle's input stream.\

- $fh-\>write ( BUF, LEN \[, OFFSET }\\\] )

  This `write` is like `write` found in C, that is it is the opposite of read. The wrapper for the perl `write` function is called `format_write`.\

- $fh-\>flush

  Flush the given handle's buffer.\

- $fh-\>error

  Returns a true value if the given handle has experienced any errors since it was opened or since the last call to `clearerr`.\

- $fh-\>clearerr

  Clear the given handle's error indicator.

If the C functions *setbuf()* and/or *setvbuf()* are available, then `IO::Handle::setbuf` and `IO::Handle::setvbuf` set the buffering policy for an IO::Handle.  The calling sequences for the Perl functions are the same as their C counterparts--including the constants `_IOFBF`, `_IOLBF`, and `_IONBF` for *setvbuf()*--except that the buffer parameter specifies a scalar variable to use as a buffer.  WARNING: A variable used as a buffer by `setbuf` or `setvbuf` must not be modified in any way until the IO::Handle is closed or `setbuf` or `setvbuf` is called again, or memory corruption may result!  Note that you need to import the constants `_IOFBF`, `_IOLBF`, and `_IONBF` explicitly.

Lastly, there is a special method for working under **-T** and setuid/gid scripts:\

- $fh-\>untaint

  Marks the object as taint-clean, and as such data read from it will also be considered taint-clean. Note that this is a very trusting action to take, and appropriate consideration for the data source and potential vulnerability should be kept in mind.

## NOTE

A `IO::Handle` object is a GLOB reference. Some modules that inherit from `IO::Handle` may want to keep object related variables in the hash table part of the GLOB. In an attempt to prevent modules trampling on each other I propose the that any such module should prefix its variables with its own name separated by \_'s. For example the IO::Socket module keeps a `timeout` variable in 'io\_socket\_timeout'.

## SEE ALSO

the *perlfunc* manpage,  the section on *I/O Operators* in the *perlop* manpage, the *IO::File* manpage

## BUGS

Due to backwards compatibility, all filehandles resemble objects of class `IO::Handle`, or actually classes derived from that class. They actually aren't.  Which means you can't derive your own  class from `IO::Handle` and inherit those methods.

## HISTORY

Derived from FileHandle.pm by Graham Barr \<*bodg@tiuk.ti.com*\>