Deprecate != Depreciate.

[perl5.git] / ext / IO / lib / IO / Handle.pm

diff --git a/ext/IO/lib/IO/Handle.pm b/ext/IO/lib/IO/Handle.pm
index b6cb410..37aa99c 100644 (file)
--- a/ext/IO/lib/IO/Handle.pm
+++ b/ext/IO/lib/IO/Handle.pm
@@ -100,7 +100,7 @@ The following methods are not supported on a per-filehandle basis.
 
 Furthermore, for doing normal I/O you might need these:
 
-=over 
+=over 4
 
 =item $io->fdopen ( FD, MODE )
 
@@ -110,7 +110,8 @@ or a file descriptor number.
 
 =item $io->opened
 
-Returns true if the object is currently a valid file descriptor.
+Returns true if the object is currently a valid file descriptor, false
+otherwise.
 
 =item $io->getline
 
@@ -139,31 +140,37 @@ called C<format_write>.
 =item $io->error
 
 Returns a true value if the given handle has experienced any errors
-since it was opened or since the last call to C<clearerr>.
+since it was opened or since the last call to C<clearerr>, or if the
+handle is invalid. It only returns false for a valid handle with no
+outstanding errors.
 
 =item $io->clearerr
 
-Clear the given handle's error indicator.
+Clear the given handle's error indicator. Returns -1 if the handle is
+invalid, 0 otherwise.
 
 =item $io->sync
 
 C<sync> synchronizes a file's in-memory state  with  that  on the
 physical medium. C<sync> does not operate at the perlio api level, but
-operates on the file descriptor, this means that any data held at the
-perlio api level will not be synchronized. To synchronize data that is
-buffered at the perlio api level you must use the flush method. C<sync>
-is not implemented on all platforms. See L<fsync(3c)>.
+operates on the file descriptor (similar to sysread, sysseek and
+systell). This means that any data held at the perlio api level will not
+be synchronized. To synchronize data that is buffered at the perlio api
+level you must use the flush method. C<sync> is not implemented on all
+platforms. Returns "0 but true" on success, C<undef> on error, C<undef>
+for an invalid handle. See L<fsync(3c)>.
 
 =item $io->flush
 
 C<flush> causes perl to flush any buffered data at the perlio api level.
 Any unread data in the buffer will be discarded, and any unwritten data
-will be written to the underlying file descriptor.
+will be written to the underlying file descriptor. Returns "0 but true"
+on success, C<undef> on error.
 
 =item $io->printflush ( ARGS )
 
 Turns on autoflush, print ARGS and then restores the autoflush status of the
-C<IO::Handle> object.
+C<IO::Handle> object. Returns the return value from print.
 
 =item $io->blocking ( [ BOOL ] )
 
@@ -183,23 +190,31 @@ C<IO::Handle::setbuf> and C<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 C<_IOFBF>,
 C<_IOLBF>, and C<_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 C<setbuf> or C<setvbuf> must not be modified in any
-way until the IO::Handle is closed or C<setbuf> or C<setvbuf> is called
-again, or memory corruption may result! Note that you need to import
-the constants C<_IOFBF>, C<_IOLBF>, and C<_IONBF> explicitly.
+specifies a scalar variable to use as a buffer. You should only
+change the buffer before any I/O, or immediately after calling flush.
+
+WARNING: A variable used as a buffer by C<setbuf> or C<setvbuf> B<must not
+be modified> in any way until the IO::Handle is closed or C<setbuf> or
+C<setvbuf> is called again, or memory corruption may result! Remember that
+the order of global destruction is undefined, so even if your buffer
+variable remains in scope until program termination, it may be undefined
+before the file IO::Handle is closed. Note that you need to import the
+constants C<_IOFBF>, C<_IOLBF>, and C<_IONBF> explicitly. Like C, setbuf
+returns nothing. setvbuf returns "0 but true", on success, C<undef> on
+failure.
 
 Lastly, there is a special method for working under B<-T> and setuid/gid
 scripts:
 
-=over
+=over 4
 
 =item $io->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.
+vulnerability should be kept in mind. Returns 0 on success, -1 if setting
+the taint-clean flag failed. (eg invalid handle)
 
 =back
 
@@ -232,7 +247,7 @@ Derived from FileHandle.pm by Graham Barr E<lt>F<gbarr@pobox.com>E<gt>
 
 =cut
 
-require 5.005_64;
+require 5.6.1;
 use strict;
 our($VERSION, @EXPORT_OK, @ISA);
 use Carp;
@@ -243,7 +258,7 @@ use IO ();  # Load the XS module
 require Exporter;
 @ISA = qw(Exporter);
 
-$VERSION = "1.21";
+$VERSION = "1.21_00";
 
 @EXPORT_OK = qw(
     autoflush
@@ -580,7 +595,7 @@ sub constant {
 }
 
 
-# so that flush.pl can be depriciated
+# so that flush.pl can be deprecated
 
 sub printflush {
     my $io = shift;