[inseparable changes from patch from perl5.003_24 to perl5.003_25]

[p5sagit/p5-mst-13.2.git] / ext / IO / lib / IO / Handle.pm

diff --git a/ext/IO/lib/IO/Handle.pm b/ext/IO/lib/IO/Handle.pm
index 54b32f4..e02f6df 100644 (file)
--- a/ext/IO/lib/IO/Handle.pm
+++ b/ext/IO/lib/IO/Handle.pm
@@ -1,4 +1,3 @@
-#
 
 package IO::Handle;
 
@@ -11,39 +10,33 @@ IO::Handle - supply object methods for I/O handles
     use IO::Handle;
 
     $fh = new IO::Handle;
-    if ($fh->open "< file") {
-        print <$fh>;
-        $fh->close;
-    }
-
-    $fh = new IO::Handle "> FOO";
-    if (defined $fh) {
-        print $fh "bar\n";
+    if ($fh->fdopen(fileno(STDIN),"r")) {
+        print $fh->getline;
         $fh->close;
     }
 
-    $fh = new IO::Handle "file", "r";
-    if (defined $fh) {
-        print <$fh>;
-        undef $fh;       # automatically closes the file
-    }
-
-    $fh = new IO::Handle "file", O_WRONLY|O_APPEND;
-    if (defined $fh) {
-        print $fh "corge\n";
-        undef $fh;       # automatically closes the file
+    $fh = new IO::Handle;
+    if ($fh->fdopen(fileno(STDOUT),"w")) {
+        $fh->print("Some text\n");
     }
 
-    $pos = $fh->getpos;
-    $fh->setpos $pos;
-
     $fh->setvbuf($buffer_var, _IOLBF, 1024);
 
+    undef $fh;       # automatically closes the file if it's open
+
     autoflush STDOUT 1;
 
 =head1 DESCRIPTION
 
-C<IO::Handle> is the base class for all other IO handle classes.
+C<IO::Handle> is the base class for all other IO handle classes. It is
+not intended that objects of C<IO::Handle> would be created directly,
+but instead C<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 C<FileHandle> package, then I suggest you read the documentation
+for C<IO::File>
+
 A C<IO::Handle> object is a reference to a symbol (see the C<Symbol> package)
 
 =head1 CONSTRUCTOR
@@ -78,11 +71,10 @@ result!
 See L<perlfunc> for complete descriptions of each of the following
 supported C<IO::Handle> methods, which are just front ends for the
 corresponding built-in functions:
-  
+
     close
     fileno
     getc
-    gets
     eof
     read
     truncate
@@ -143,6 +135,19 @@ Returns true if the object is currently a valid file descriptor.
 
 =back
 
+Lastly, a special method for working under B<-T> and setuid/gid scripts:
+
+=over
+
+=item $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.
+
+=back
+
 =head1 NOTE
 
 A C<IO::Handle> object is a GLOB reference. Some modules that
@@ -156,7 +161,7 @@ module keeps a C<timeout> variable in 'io_socket_timeout'.
 
 L<perlfunc>, 
 L<perlop/"I/O Operators">,
-L<POSIX/"FileHandle">
+L<IO::File>
 
 =head1 BUGS
 
@@ -172,7 +177,8 @@ Derived from FileHandle.pm by Graham Barr E<lt>F<bodg@tiuk.ti.com>E<gt>
 =cut
 
 require 5.000;
-use vars qw($RCS $VERSION @EXPORT_OK $AUTOLOAD);
+use strict;
+use vars qw($VERSION $XS_VERSION @EXPORT_OK $AUTOLOAD @ISA);
 use Carp;
 use Symbol;
 use SelectSaver;
@@ -180,13 +186,8 @@ use SelectSaver;
 require Exporter;
 @ISA = qw(Exporter);
 
-##
-## TEMPORARY workaround as perl expects handles to be <FileHandle> objects
-##
-@FileHandle::ISA = qw(IO::Handle);
-
-$VERSION = "1.12";
-$RCS = sprintf("%s", q$Revision: 1.15 $ =~ /([\d\.]+)/);
+$VERSION = "1.1502";
+$XS_VERSION = "1.15";
 
 @EXPORT_OK = qw(
     autoflush
@@ -225,7 +226,7 @@ $RCS = sprintf("%s", q$Revision: 1.15 $ =~ /([\d\.]+)/);
 
 require DynaLoader;
 @IO::ISA = qw(DynaLoader);
-bootstrap IO $VERSION;
+bootstrap IO $XS_VERSION;
 
 sub AUTOLOAD {
     if ($AUTOLOAD =~ /::(_?[a-z])/) {
@@ -236,6 +237,7 @@ sub AUTOLOAD {
     $constname =~ s/.*:://;
     my $val = constant($constname);
     defined $val or croak "$constname is not a valid IO::Handle macro";
+    no strict 'refs';
     *$AUTOLOAD = sub { $val };
     goto &$AUTOLOAD;
 }
@@ -256,29 +258,20 @@ sub new_from_fd {
     my $class = ref($_[0]) || $_[0] || "IO::Handle";
     @_ == 3 or croak "usage: new_from_fd $class FD, MODE";
     my $fh = gensym;
+    shift;
     IO::Handle::fdopen($fh, @_)
        or return undef;
     bless $fh, $class;
 }
 
-sub DESTROY {
-    my ($fh) = @_;
-
-    # During global object destruction, this function may be called
-    # on FILEHANDLEs as well as on the GLOBs that contains them.
-    # Thus the following trickery.  If only the CORE file operators
-    # could deal with FILEHANDLEs, it wouldn't be necessary...
+#
+# There is no need for DESTROY to do anything, because when the
+# last reference to an IO object is gone, Perl automatically
+# closes its associated files (if any).  However, to avoid any
+# attempts to autoload DESTROY, we here define it to do nothing.
+#
+sub DESTROY {}
 
-    if ($fh =~ /=FILEHANDLE\(/) {
-       local *TMP = $fh;
-       close(TMP)
-           if defined fileno(TMP);
-    }
-    else {
-       close($fh)
-           if defined fileno($fh);
-    }
-}
 
 ################################################
 ## Open and close.
@@ -316,14 +309,8 @@ sub fdopen {
 sub close {
     @_ == 1 or croak 'usage: $fh->close()';
     my($fh) = @_;
-    my $r = close($fh);
-
-    # This may seem as though it should be in IO::Pipe, but the
-    # object gets blessed out of IO::Pipe when reader/writer is called
-    waitpid(${*$fh}{'io_pipe_pid'},0)
-       if(defined ${*$fh}{'io_pipe_pid'});
 
-    $r;
+    close($fh);
 }
 
 ################################################
@@ -348,12 +335,6 @@ sub getc {
     getc($_[0]);
 }
 
-sub gets {
-    @_ == 1 or croak 'usage: $fh->gets()';
-    my ($handle) = @_;
-    scalar <$handle>;
-}
-
 sub eof {
     @_ == 1 or croak 'usage: $fh->eof()';
     eof($_[0]);
@@ -377,6 +358,8 @@ sub getline {
     return scalar <$this>;
 } 
 
+*gets = \&getline;  # deprecated
+
 sub getlines {
     @_ == 1 or croak 'usage: $fh->getline()';
     wantarray or
@@ -408,7 +391,7 @@ sub write {
 
 sub syswrite {
     @_ == 3 || @_ == 4 or croak '$fh->syswrite(BUF, LEN [, OFFSET])';
-    sysread($_[0], $_[1], $_[2], $_[3] || 0);
+    syswrite($_[0], $_[1], $_[2], $_[3] || 0);
 }
 
 sub stat {