IO::Handle

IO::Handle(3)          Perl Programmers Reference Guide          IO::Handle(3)



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>


























3rd Berkeley Distribution    perl 5.005, patch 02                IO::Handle(3)