IO::Handle

See the current Perl documentation for IO::Handle.

Here is our local, out-dated (pre-5.6) version:

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

    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(fil
    

    

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 perlfunc 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 perlvar 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 perlop
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

perlfunc, 
perlop,
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>