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

- NAME
- SYNOPSIS
- DESCRIPTION
- CONSTRUCTOR
- METHODS
- NOTE
- SEE ALSO
- BUGS
- HISTORY

# 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 I/O Operators 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, I/O Operators, File

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