[perl #117791] Clarify that write does not match the C 'write' semantics

diff --git a/dist/IO/lib/IO/Handle.pm b/dist/IO/lib/IO/Handle.pm
index 68e6d90..3b1e67d 100644 (file)
--- a/dist/IO/lib/IO/Handle.pm
+++ b/dist/IO/lib/IO/Handle.pm
@@ -139,9 +139,12 @@ guaranteed.
 
 =item $io->write ( BUF, LEN [, OFFSET ] )
 
-This C<write> is like C<write> found in C, that is it is the
+This C<write> is somewhat like C<write> found in C, in that it is the
 opposite of read. The wrapper for the perl C<write> function is
-called C<format_write>.
+called C<format_write>. However, whilst the C C<write> function returns
+the number of bytes written, this C<write> function simply returns true
+if successful (like C<print>). A more C-like C<write> is C<syswrite>
+(see above).
 
 =item $io->error