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>