IO::Handle(3)							 IO::Handle(3)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

	 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    [Toc]    [Back]

     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    [Toc]    [Back]

     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    [Toc]    [Back]

     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:





									Page 1






IO::Handle(3)							 IO::Handle(3)



	 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.



									Page 2






IO::Handle(3)							 IO::Handle(3)



     $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    [Toc]    [Back]

     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    [Toc]    [Back]

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

BUGS    [Toc]    [Back]

     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.



									Page 3






IO::Handle(3)							 IO::Handle(3)

HISTORY    [Toc]    [Back]

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


									PPPPaaaaggggeeee 4444