perl 5.003_04: ext/IO/lib/IO/File.pm

This patch fixes a bug observed by Tom Christiansen: IO::File::new
didn't allow for file permissions after the file mode.  Here's a patch.

This patch documents the behavior of IO::File::{new,open} with
regard to open modes.  It also documents the exportation of Fcntl
constants.

diff --git a/ext/IO/lib/IO/File.pm b/ext/IO/lib/IO/File.pm
index c447dfa..49439a5 100644 (file)
--- a/ext/IO/lib/IO/File.pm
+++ b/ext/IO/lib/IO/File.pm
@@ -53,8 +53,17 @@ C<IO::File::open> accepts one parameter or two.  With one parameter,
 it is just a front end for the built-in C<open> function.  With two
 parameters, the first parameter is a filename that may include
 whitespace or other special characters, and the second parameter is
-the open mode in either Perl form (">", "+<", etc.) or POSIX form
-("w", "r+", etc.).
+the open mode, optionally followed by a file permission value.
+
+If C<IO::File::open> receives a Perl mode string (">", "+<", etc.)
+or a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic
+Perl C<open> operator.
+
+If C<IO::File::open> is given a numeric mode, it passes that mode
+and the optional permissions value to the Perl C<sysopen> operator.
+For convenience, C<IO::File::import> tries to import the O_XXX
+constants from the Fcntl module.  If dynamic loading is not available,
+this may fail, but the rest of IO::File will still work.
 
 =head1 SEE ALSO
 
@@ -112,7 +121,8 @@ sub import {
 ##
 
 sub new {
-    @_ >= 1 && @_ <= 3 or croak 'usage: new IO::File [FILENAME [,MODE]]';
+    @_ >= 1 && @_ <= 4
+       or croak 'usage: new IO::File [FILENAME [,MODE [,PERMS]]]';
     my $class = shift;
     my $fh = $class->SUPER::new();
     if (@_) {