1N/Apackage IO::Handle;
1N/A
1N/A=head1 NAME
1N/A
1N/AIO::Handle - supply object methods for I/O handles
1N/A
1N/A=head1 SYNOPSIS
1N/A
1N/A use IO::Handle;
1N/A
1N/A $io = new IO::Handle;
1N/A if ($io->fdopen(fileno(STDIN),"r")) {
1N/A print $io->getline;
1N/A $io->close;
1N/A }
1N/A
1N/A $io = new IO::Handle;
1N/A if ($io->fdopen(fileno(STDOUT),"w")) {
1N/A $io->print("Some text\n");
1N/A }
1N/A
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
1N/A undef $io; # automatically closes the file if it's open
1N/A
1N/A autoflush STDOUT 1;
1N/A
1N/A=head1 DESCRIPTION
1N/A
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/Ain the IO hierarchy.
1N/A
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/Afor C<IO::File> too.
1N/A
1N/A=head1 CONSTRUCTOR
1N/A
1N/A=over 4
1N/A
1N/A=item new ()
1N/A
1N/ACreates a new C<IO::Handle> object.
1N/A
1N/A=item new_from_fd ( FD, MODE )
1N/A
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/Ato the caller.
1N/A
1N/A=back
1N/A
1N/A=head1 METHODS
1N/A
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
1N/A $io->close
1N/A $io->eof
1N/A $io->fileno
1N/A $io->format_write( [FORMAT_NAME] )
1N/A $io->getc
1N/A $io->read ( BUF, LEN, [OFFSET] )
1N/A $io->print ( ARGS )
1N/A $io->printf ( FMT, [ARGS] )
1N/A $io->stat
1N/A $io->sysread ( BUF, LEN, [OFFSET] )
1N/A $io->syswrite ( BUF, [LEN, [OFFSET]] )
1N/A $io->truncate ( LEN )
1N/A
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
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/A
1N/AThe following methods are not supported on a per-filehandle basis.
1N/A
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
1N/A IO::Handle->input_record_separator( [STR] ) $/
1N/A
1N/AFurthermore, for doing normal I/O you might need these:
1N/A
1N/A=over 4
1N/A
1N/A=item $io->fdopen ( FD, MODE )
1N/A
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/A
1N/A=item $io->opened
1N/A
1N/AReturns true if the object is currently a valid file descriptor, false
1N/Aotherwise.
1N/A
1N/A=item $io->getline
1N/A
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/A
1N/A=item $io->getlines
1N/A
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
1N/A=item $io->ungetc ( ORD )
1N/A
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/Aguaranteed.
1N/A
1N/A=item $io->write ( BUF, LEN [, OFFSET ] )
1N/A
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/A
1N/A=item $io->error
1N/A
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/Aoutstanding errors.
1N/A
1N/A=item $io->clearerr
1N/A
1N/AClear the given handle's error indicator. Returns -1 if the handle is
1N/Ainvalid, 0 otherwise.
1N/A
1N/A=item $io->sync
1N/A
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/A
1N/A=item $io->flush
1N/A
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
1N/A=item $io->printflush ( ARGS )
1N/A
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
1N/A=item $io->blocking ( [ BOOL ] )
1N/A
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/A
1N/AC<blocking> will return the value of the previous setting, or the
1N/Acurrent setting if C<BOOL> is not given.
1N/A
1N/AIf an error occurs C<blocking> will return undef and C<$!> will be set.
1N/A
1N/A=back
1N/A
1N/A
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/A
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/A
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/Afailure.
1N/A
1N/ALastly, there is a special method for working under B<-T> and setuid/gid
1N/Ascripts:
1N/A
1N/A=over 4
1N/A
1N/A=item $io->untaint
1N/A
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/A
1N/A=back
1N/A
1N/A=head1 NOTE
1N/A
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/A
1N/A=head1 SEE ALSO
1N/A
1N/AL<perlfunc>,
1N/AL<perlop/"I/O Operators">,
1N/AL<IO::File>
1N/A
1N/A=head1 BUGS
1N/A
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/A
1N/A=head1 HISTORY
1N/A
1N/ADerived from FileHandle.pm by Graham Barr E<lt>F<gbarr@pobox.com>E<gt>
1N/A
1N/A=cut
1N/A
1N/Ause 5.006_001;
1N/Ause strict;
1N/Aour($VERSION, @EXPORT_OK, @ISA);
1N/Ause Carp;
1N/Ause Symbol;
1N/Ause SelectSaver;
1N/Ause IO (); # Load the XS module
1N/A
1N/Arequire Exporter;
1N/A@ISA = qw(Exporter);
1N/A
1N/A$VERSION = "1.24";
1N/A$VERSION = eval $VERSION;
1N/A
1N/A@EXPORT_OK = qw(
1N/A autoflush
1N/A output_field_separator
1N/A output_record_separator
1N/A input_record_separator
1N/A input_line_number
1N/A format_page_number
1N/A format_lines_per_page
1N/A format_lines_left
1N/A format_name
1N/A format_top_name
1N/A format_line_break_characters
1N/A format_formfeed
1N/A format_write
1N/A
1N/A print
1N/A printf
1N/A getline
1N/A getlines
1N/A
1N/A printflush
1N/A flush
1N/A
1N/A SEEK_SET
1N/A SEEK_CUR
1N/A SEEK_END
1N/A _IOFBF
1N/A _IOLBF
1N/A _IONBF
1N/A);
1N/A
1N/A################################################
1N/A## Constructors, destructors.
1N/A##
1N/A
1N/Asub new {
1N/A my $class = ref($_[0]) || $_[0] || "IO::Handle";
1N/A @_ == 1 or croak "usage: new $class";
1N/A my $io = gensym;
1N/A bless $io, $class;
1N/A}
1N/A
1N/Asub new_from_fd {
1N/A my $class = ref($_[0]) || $_[0] || "IO::Handle";
1N/A @_ == 3 or croak "usage: new_from_fd $class FD, MODE";
1N/A my $io = gensym;
1N/A shift;
1N/A IO::Handle::fdopen($io, @_)
1N/A or return undef;
1N/A bless $io, $class;
1N/A}
1N/A
1N/A#
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/Asub DESTROY {}
1N/A
1N/A
1N/A################################################
1N/A## Open and close.
1N/A##
1N/A
1N/Asub _open_mode_string {
1N/A my ($mode) = @_;
1N/A $mode =~ /^\+?(<|>>?)$/
1N/A or $mode =~ s/^r(\+?)$/$1</
1N/A or $mode =~ s/^w(\+?)$/$1>/
1N/A or $mode =~ s/^a(\+?)$/$1>>/
1N/A or croak "IO::Handle: bad open mode: $mode";
1N/A $mode;
1N/A}
1N/A
1N/Asub fdopen {
1N/A @_ == 3 or croak 'usage: $io->fdopen(FD, MODE)';
1N/A my ($io, $fd, $mode) = @_;
1N/A local(*GLOB);
1N/A
1N/A if (ref($fd) && "".$fd =~ /GLOB\(/o) {
1N/A # It's a glob reference; Alias it as we cannot get name of anon GLOBs
1N/A my $n = qualify(*GLOB);
1N/A *GLOB = *{*$fd};
1N/A $fd = $n;
1N/A } elsif ($fd =~ m#^\d+$#) {
1N/A # It's an FD number; prefix with "=".
1N/A $fd = "=$fd";
1N/A }
1N/A
1N/A open($io, _open_mode_string($mode) . '&' . $fd)
1N/A ? $io : undef;
1N/A}
1N/A
1N/Asub close {
1N/A @_ == 1 or croak 'usage: $io->close()';
1N/A my($io) = @_;
1N/A
1N/A close($io);
1N/A}
1N/A
1N/A################################################
1N/A## Normal I/O functions.
1N/A##
1N/A
1N/A# flock
1N/A# select
1N/A
1N/Asub opened {
1N/A @_ == 1 or croak 'usage: $io->opened()';
1N/A defined fileno($_[0]);
1N/A}
1N/A
1N/Asub fileno {
1N/A @_ == 1 or croak 'usage: $io->fileno()';
1N/A fileno($_[0]);
1N/A}
1N/A
1N/Asub getc {
1N/A @_ == 1 or croak 'usage: $io->getc()';
1N/A getc($_[0]);
1N/A}
1N/A
1N/Asub eof {
1N/A @_ == 1 or croak 'usage: $io->eof()';
1N/A eof($_[0]);
1N/A}
1N/A
1N/Asub print {
1N/A @_ or croak 'usage: $io->print(ARGS)';
1N/A my $this = shift;
1N/A print $this @_;
1N/A}
1N/A
1N/Asub printf {
1N/A @_ >= 2 or croak 'usage: $io->printf(FMT,[ARGS])';
1N/A my $this = shift;
1N/A printf $this @_;
1N/A}
1N/A
1N/Asub getline {
1N/A @_ == 1 or croak 'usage: $io->getline()';
1N/A my $this = shift;
1N/A return scalar <$this>;
1N/A}
1N/A
1N/A*gets = \&getline; # deprecated
1N/A
1N/Asub getlines {
1N/A @_ == 1 or croak 'usage: $io->getlines()';
1N/A wantarray or
1N/A croak 'Can\'t call $io->getlines in a scalar context, use $io->getline';
1N/A my $this = shift;
1N/A return <$this>;
1N/A}
1N/A
1N/Asub truncate {
1N/A @_ == 2 or croak 'usage: $io->truncate(LEN)';
1N/A truncate($_[0], $_[1]);
1N/A}
1N/A
1N/Asub read {
1N/A @_ == 3 || @_ == 4 or croak 'usage: $io->read(BUF, LEN [, OFFSET])';
1N/A read($_[0], $_[1], $_[2], $_[3] || 0);
1N/A}
1N/A
1N/Asub sysread {
1N/A @_ == 3 || @_ == 4 or croak 'usage: $io->sysread(BUF, LEN [, OFFSET])';
1N/A sysread($_[0], $_[1], $_[2], $_[3] || 0);
1N/A}
1N/A
1N/Asub write {
1N/A @_ >= 2 && @_ <= 4 or croak 'usage: $io->write(BUF [, LEN [, OFFSET]])';
1N/A local($\) = "";
1N/A $_[2] = length($_[1]) unless defined $_[2];
1N/A print { $_[0] } substr($_[1], $_[3] || 0, $_[2]);
1N/A}
1N/A
1N/Asub syswrite {
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 } else {
1N/A syswrite($_[0], $_[1]);
1N/A }
1N/A}
1N/A
1N/Asub stat {
1N/A @_ == 1 or croak 'usage: $io->stat()';
1N/A stat($_[0]);
1N/A}
1N/A
1N/A################################################
1N/A## State modification functions.
1N/A##
1N/A
1N/Asub autoflush {
1N/A my $old = new SelectSaver qualify($_[0], caller);
1N/A my $prev = $|;
1N/A $| = @_ > 1 ? $_[1] : 1;
1N/A $prev;
1N/A}
1N/A
1N/Asub output_field_separator {
1N/A carp "output_field_separator is not supported on a per-handle basis"
1N/A if ref($_[0]);
1N/A my $prev = $,;
1N/A $, = $_[1] if @_ > 1;
1N/A $prev;
1N/A}
1N/A
1N/Asub output_record_separator {
1N/A carp "output_record_separator is not supported on a per-handle basis"
1N/A if ref($_[0]);
1N/A my $prev = $\;
1N/A $\ = $_[1] if @_ > 1;
1N/A $prev;
1N/A}
1N/A
1N/Asub input_record_separator {
1N/A carp "input_record_separator is not supported on a per-handle basis"
1N/A if ref($_[0]);
1N/A my $prev = $/;
1N/A $/ = $_[1] if @_ > 1;
1N/A $prev;
1N/A}
1N/A
1N/Asub input_line_number {
1N/A local $.;
1N/A () = tell qualify($_[0], caller) if ref($_[0]);
1N/A my $prev = $.;
1N/A $. = $_[1] if @_ > 1;
1N/A $prev;
1N/A}
1N/A
1N/Asub format_page_number {
1N/A my $old;
1N/A $old = new SelectSaver qualify($_[0], caller) if ref($_[0]);
1N/A my $prev = $%;
1N/A $% = $_[1] if @_ > 1;
1N/A $prev;
1N/A}
1N/A
1N/Asub format_lines_per_page {
1N/A my $old;
1N/A $old = new SelectSaver qualify($_[0], caller) if ref($_[0]);
1N/A my $prev = $=;
1N/A $= = $_[1] if @_ > 1;
1N/A $prev;
1N/A}
1N/A
1N/Asub format_lines_left {
1N/A my $old;
1N/A $old = new SelectSaver qualify($_[0], caller) if ref($_[0]);
1N/A my $prev = $-;
1N/A $- = $_[1] if @_ > 1;
1N/A $prev;
1N/A}
1N/A
1N/Asub format_name {
1N/A my $old;
1N/A $old = new SelectSaver qualify($_[0], caller) if ref($_[0]);
1N/A my $prev = $~;
1N/A $~ = qualify($_[1], caller) if @_ > 1;
1N/A $prev;
1N/A}
1N/A
1N/Asub format_top_name {
1N/A my $old;
1N/A $old = new SelectSaver qualify($_[0], caller) if ref($_[0]);
1N/A my $prev = $^;
1N/A $^ = qualify($_[1], caller) if @_ > 1;
1N/A $prev;
1N/A}
1N/A
1N/Asub format_line_break_characters {
1N/A carp "format_line_break_characters is not supported on a per-handle basis"
1N/A if ref($_[0]);
1N/A my $prev = $:;
1N/A $: = $_[1] if @_ > 1;
1N/A $prev;
1N/A}
1N/A
1N/Asub format_formfeed {
1N/A carp "format_formfeed is not supported on a per-handle basis"
1N/A if ref($_[0]);
1N/A my $prev = $^L;
1N/A $^L = $_[1] if @_ > 1;
1N/A $prev;
1N/A}
1N/A
1N/Asub formline {
1N/A my $io = shift;
1N/A my $picture = shift;
1N/A local($^A) = $^A;
1N/A local($\) = "";
1N/A formline($picture, @_);
1N/A print $io $^A;
1N/A}
1N/A
1N/Asub format_write {
1N/A @_ < 3 || croak 'usage: $io->write( [FORMAT_NAME] )';
1N/A if (@_ == 2) {
1N/A my ($io, $fmt) = @_;
1N/A my $oldfmt = $io->format_name($fmt);
1N/A CORE::write($io);
1N/A $io->format_name($oldfmt);
1N/A } else {
1N/A CORE::write($_[0]);
1N/A }
1N/A}
1N/A
1N/A# XXX undocumented
1N/Asub fcntl {
1N/A @_ == 3 || croak 'usage: $io->fcntl( OP, VALUE );';
1N/A my ($io, $op) = @_;
1N/A return fcntl($io, $op, $_[2]);
1N/A}
1N/A
1N/A# XXX undocumented
1N/Asub ioctl {
1N/A @_ == 3 || croak 'usage: $io->ioctl( OP, VALUE );';
1N/A my ($io, $op) = @_;
1N/A return ioctl($io, $op, $_[2]);
1N/A}
1N/A
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#
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)
1N/A
1N/Asub constant {
1N/A no strict 'refs';
1N/A my $name = shift;
1N/A (($name =~ /^(SEEK_(SET|CUR|END)|_IO[FLN]BF)$/) && defined &{$name})
1N/A ? &{$name}() : undef;
1N/A}
1N/A
1N/A
1N/A# so that flush.pl can be deprecated
1N/A
1N/Asub printflush {
1N/A my $io = shift;
1N/A my $old;
1N/A $old = new SelectSaver qualify($io, caller) if ref($io);
1N/A local $| = 1;
1N/A if(ref($io)) {
1N/A print $io @_;
1N/A }
1N/A else {
1N/A print @_;
1N/A }
1N/A}
1N/A
1N/A1;