1N/AIO::Handle - supply object methods for I/O handles 1N/A $io = new IO::Handle; 1N/A if ($io->fdopen(fileno(STDIN),"r")) { 1N/A $io = new IO::Handle; 1N/A if ($io->fdopen(fileno(STDOUT),"w")) { 1N/A $io->print("Some text\n"); 1N/A # setvbuf is not available by default on Perls 5.8.0 and later. 1N/A use IO::Handle '_IOLBF'; 1N/A $io->setvbuf($buffer_var, _IOLBF, 1024); 1N/A undef $io; # automatically closes the file if it's open 1N/AC<IO::Handle> is the base class for all other IO handle classes. It is 1N/Anot intended that objects of C<IO::Handle> would be created directly, 1N/Abut instead C<IO::Handle> is inherited from by several other classes 1N/AIf you are reading this documentation, looking for a replacement for 1N/Athe C<FileHandle> package, then I suggest you read the documentation 1N/ACreates a new C<IO::Handle> object. 1N/A=item new_from_fd ( FD, MODE ) 1N/ACreates an C<IO::Handle> like C<new> does. 1N/AIt requires two parameters, which are passed to the method C<fdopen>; 1N/Aif the fdopen fails, the object is destroyed. Otherwise, it is returned 1N/ASee L<perlfunc> for complete descriptions of each of the following 1N/Asupported C<IO::Handle> methods, which are just front ends for the 1N/Acorresponding built-in functions: 1N/A $io->format_write( [FORMAT_NAME] ) 1N/A $io->read ( BUF, LEN, [OFFSET] ) 1N/A $io->printf ( FMT, [ARGS] ) 1N/A $io->sysread ( BUF, LEN, [OFFSET] ) 1N/A $io->syswrite ( BUF, [LEN, [OFFSET]] ) 1N/A $io->truncate ( LEN ) 1N/ASee L<perlvar> for complete descriptions of each of the following 1N/Asupported C<IO::Handle> methods. All of them return the previous 1N/Avalue of the attribute and takes an optional single argument that when 1N/Agiven will set the value. If no argument is given the previous value 1N/Ais unchanged (except for $io->autoflush will actually turn ON 1N/Aautoflush by default). 1N/A $io->autoflush ( [BOOL] ) $| 1N/A $io->format_page_number( [NUM] ) $% 1N/A $io->format_lines_per_page( [NUM] ) $= 1N/A $io->format_lines_left( [NUM] ) $- 1N/A $io->format_name( [STR] ) $~ 1N/A $io->format_top_name( [STR] ) $^ 1N/A $io->input_line_number( [NUM]) $. 1N/AThe following methods are not supported on a per-filehandle basis. 1N/A IO::Handle->format_line_break_characters( [STR] ) $: 1N/A IO::Handle->format_formfeed( [STR]) $^L 1N/A IO::Handle->output_field_separator( [STR] ) $, 1N/A IO::Handle->output_record_separator( [STR] ) $\ 1N/A IO::Handle->input_record_separator( [STR] ) $/ 1N/AFurthermore, for doing normal I/O you might need these: 1N/A=item $io->fdopen ( FD, MODE ) 1N/AC<fdopen> is like an ordinary C<open> except that its first parameter 1N/Ais not a filename but rather a file handle name, an IO::Handle object, 1N/Aor a file descriptor number. 1N/AReturns true if the object is currently a valid file descriptor, false 1N/AThis works like <$io> described in L<perlop/"I/O Operators"> 1N/Aexcept that it's more readable and can be safely called in a 1N/Alist context but still returns just one line. 1N/AThis works like <$io> when called in a list context to read all 1N/Athe remaining lines in a file, except that it's more readable. 1N/AIt will also croak() if accidentally called in a scalar context. 1N/A=item $io->ungetc ( ORD ) 1N/APushes a character with the given ordinal value back onto the given 1N/Ahandle's input stream. Only one character of pushback per handle is 1N/A=item $io->write ( BUF, LEN [, OFFSET ] ) 1N/AThis C<write> is like C<write> found in C, that is it is the 1N/Aopposite of read. The wrapper for the perl C<write> function is 1N/Acalled C<format_write>. 1N/AReturns a true value if the given handle has experienced any errors 1N/Asince it was opened or since the last call to C<clearerr>, or if the 1N/Ahandle is invalid. It only returns false for a valid handle with no 1N/AClear the given handle's error indicator. Returns -1 if the handle is 1N/Ainvalid, 0 otherwise. 1N/AC<sync> synchronizes a file's in-memory state with that on the 1N/Aphysical medium. C<sync> does not operate at the perlio api level, but 1N/Aoperates on the file descriptor (similar to sysread, sysseek and 1N/Asystell). This means that any data held at the perlio api level will not 1N/Abe synchronized. To synchronize data that is buffered at the perlio api 1N/Alevel you must use the flush method. C<sync> is not implemented on all 1N/Aplatforms. Returns "0 but true" on success, C<undef> on error, C<undef> 1N/Afor an invalid handle. See L<fsync(3c)>. 1N/AC<flush> causes perl to flush any buffered data at the perlio api level. 1N/AAny unread data in the buffer will be discarded, and any unwritten data 1N/Awill be written to the underlying file descriptor. Returns "0 but true" 1N/Aon success, C<undef> on error. 1N/A=item $io->printflush ( ARGS ) 1N/ATurns on autoflush, print ARGS and then restores the autoflush status of the 1N/AC<IO::Handle> object. Returns the return value from print. 1N/A=item $io->blocking ( [ BOOL ] ) 1N/AIf called with an argument C<blocking> will turn on non-blocking IO if 1N/AC<BOOL> is false, and turn it off if C<BOOL> is true. 1N/AC<blocking> will return the value of the previous setting, or the 1N/Acurrent setting if C<BOOL> is not given. 1N/AIf an error occurs C<blocking> will return undef and C<$!> will be set. 1N/AIf the C functions setbuf() and/or setvbuf() are available, then 1N/AC<IO::Handle::setbuf> and C<IO::Handle::setvbuf> set the buffering 1N/Apolicy for an IO::Handle. The calling sequences for the Perl functions 1N/Aare the same as their C counterparts--including the constants C<_IOFBF>, 1N/AC<_IOLBF>, and C<_IONBF> for setvbuf()--except that the buffer parameter 1N/Aspecifies a scalar variable to use as a buffer. You should only 1N/Achange the buffer before any I/O, or immediately after calling flush. 1N/AWARNING: The IO::Handle::setvbuf() is not available by default on 1N/APerls 5.8.0 and later because setvbuf() is rather specific to using 1N/Athe stdio library, while Perl prefers the new perlio subsystem instead. 1N/AWARNING: A variable used as a buffer by C<setbuf> or C<setvbuf> B<must not 1N/Abe modified> in any way until the IO::Handle is closed or C<setbuf> or 1N/AC<setvbuf> is called again, or memory corruption may result! Remember that 1N/Athe order of global destruction is undefined, so even if your buffer 1N/Avariable remains in scope until program termination, it may be undefined 1N/Abefore the file IO::Handle is closed. Note that you need to import the 1N/Aconstants C<_IOFBF>, C<_IOLBF>, and C<_IONBF> explicitly. Like C, setbuf 1N/Areturns nothing. setvbuf returns "0 but true", on success, C<undef> on 1N/ALastly, there is a special method for working under B<-T> and setuid/gid 1N/AMarks the object as taint-clean, and as such data read from it will also 1N/Abe considered taint-clean. Note that this is a very trusting action to 1N/Atake, and appropriate consideration for the data source and potential 1N/Avulnerability should be kept in mind. Returns 0 on success, -1 if setting 1N/Athe taint-clean flag failed. (eg invalid handle) 1N/AAn C<IO::Handle> object is a reference to a symbol/GLOB reference (see 1N/Athe C<Symbol> package). Some modules that 1N/Ainherit from C<IO::Handle> may want to keep object related variables 1N/Ain the hash table part of the GLOB. In an attempt to prevent modules 1N/Atrampling on each other I propose the that any such module should prefix 1N/Aits variables with its own name separated by _'s. For example the IO::Socket 1N/Amodule keeps a C<timeout> variable in 'io_socket_timeout'. 1N/AL<perlop/"I/O Operators">, 1N/ADue to backwards compatibility, all filehandles resemble objects 1N/Aof class C<IO::Handle>, or actually classes derived from that class. 1N/AThey actually aren't. Which means you can't derive your own 1N/Aclass from C<IO::Handle> and inherit those methods. 1N/Ause IO ();
# Load the XS module 1N/A################################################ 1N/A## Constructors, destructors. 1N/A my $
class =
ref($_[
0]) || $_[
0] ||
"IO::Handle";
1N/A @_ ==
1 or croak "usage: new $class";
1N/A my $
class =
ref($_[
0]) || $_[
0] ||
"IO::Handle";
1N/A @_ ==
3 or croak "usage: new_from_fd $class FD, MODE";
1N/A# There is no need for DESTROY to do anything, because when the 1N/A# last reference to an IO object is gone, Perl automatically 1N/A# closes its associated files (if any). However, to avoid any 1N/A# attempts to autoload DESTROY, we here define it to do nothing. 1N/A################################################ 1N/A or croak "IO::Handle: bad open mode: $mode";
1N/A @_ ==
3 or croak 'usage: $io->fdopen(FD, MODE)';
1N/A # It's a glob reference; Alias it as we cannot get name of anon GLOBs 1N/A }
elsif ($
fd =~ m
#^\d+$#) { 1N/A # It's an FD number; prefix with "=". 1N/A @_ ==
1 or croak 'usage: $io->close()';
1N/A################################################ 1N/A## Normal I/O functions. 1N/A @_ ==
1 or croak 'usage: $io->opened()';
1N/A defined fileno($_[
0]);
1N/A @_ ==
1 or croak 'usage: $io->fileno()';
1N/A @_ ==
1 or croak 'usage: $io->getc()';
1N/A @_ ==
1 or croak 'usage: $io->eof()';
1N/A @_
or croak 'usage: $io->print(ARGS)';
1N/A @_ >=
2 or croak 'usage: $io->printf(FMT,[ARGS])';
1N/A @_ ==
1 or croak 'usage: $io->getline()';
1N/A @_ ==
1 or croak 'usage: $io->getlines()';
1N/A croak 'Can\'t call $io->getlines in a scalar context, use $io->getline';
1N/A @_ ==
2 or croak 'usage: $io->truncate(LEN)';
1N/A truncate($_[
0], $_[
1]);
1N/A @_ ==
3 || @_ ==
4 or croak 'usage: $io->read(BUF, LEN [, OFFSET])';
1N/A read($_[
0], $_[
1], $_[
2], $_[
3] ||
0);
1N/A @_ ==
3 || @_ ==
4 or croak 'usage: $io->sysread(BUF, LEN [, OFFSET])';
1N/A sysread($_[
0], $_[
1], $_[
2], $_[
3] ||
0);
1N/A @_ >=
2 && @_ <=
4 or croak 'usage: $io->write(BUF [, LEN [, OFFSET]])';
1N/A $_[
2] =
length($_[
1])
unless defined $_[
2];
1N/A print { $_[
0] }
substr($_[
1], $_[
3] ||
0, $_[
2]);
1N/A @_ >=
2 && @_ <=
4 or croak 'usage: $io->syswrite(BUF [, LEN [, OFFSET]])';
1N/A if (
defined($_[
2])) {
1N/A syswrite($_[
0], $_[
1], $_[
2], $_[
3] ||
0);
1N/A syswrite($_[
0], $_[
1]);
1N/A @_ ==
1 or croak 'usage: $io->stat()';
1N/A################################################ 1N/A## State modification functions. 1N/A $| = @_ >
1 ? $_[
1] :
1;
1N/A carp "output_field_separator is not supported on a per-handle basis" 1N/A $, = $_[
1]
if @_ >
1;
1N/A carp "output_record_separator is not supported on a per-handle basis" 1N/A $\ = $_[
1]
if @_ >
1;
1N/A carp "input_record_separator is not supported on a per-handle basis" 1N/A $/ = $_[
1]
if @_ >
1;
1N/A $. = $_[
1]
if @_ >
1;
1N/A $% = $_[
1]
if @_ >
1;
1N/A $= = $_[
1]
if @_ >
1;
1N/A $- = $_[
1]
if @_ >
1;
1N/A carp "format_line_break_characters is not supported on a per-handle basis" 1N/A $: = $_[
1]
if @_ >
1;
1N/A carp "format_formfeed is not supported on a per-handle basis" 1N/A $^L = $_[
1]
if @_ >
1;
1N/A @_ <
3 ||
croak 'usage: $io->write( [FORMAT_NAME] )';
1N/A @_ ==
3 ||
croak 'usage: $io->fcntl( OP, VALUE );';
1N/A @_ ==
3 ||
croak 'usage: $io->ioctl( OP, VALUE );';
1N/A# this sub is for compatability with older releases of IO that used 1N/A# a sub called constant to detemine if a constant existed -- GMB 1N/A# The SEEK_* and _IO?BF constants were the only constants at that time 1N/A# any new code should just chech defined(&CONSTANT_NAME)