This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate mainline
authorNick Ing-Simmons <nik@tiuk.ti.com>
Mon, 17 Jun 2002 14:50:35 +0000 (14:50 +0000)
committerNick Ing-Simmons <nik@tiuk.ti.com>
Mon, 17 Jun 2002 14:50:35 +0000 (14:50 +0000)
p4raw-id: //depot/perlio@17274

README.vms
lib/File/Basename.pm
lib/PerlIO.pm
lib/open.pm
pod/perlfunc.pod
pod/perlrun.pod

index 06deb13..2739c0e 100644 (file)
@@ -289,6 +289,17 @@ a lot of tests.  If any tests fail, there will be a note made on-screen.
 At the end of all the tests, a summary of the tests, the number passed and 
 failed, and the time taken will be displayed.
 
+The test driver invoked via MMS TEST has a DCL wrapper ([.VMS]TEST.COM) that
+downgrades privileges to NETMBX, TMPMBX for the duration of the test run,
+and then restores them to their prior state upon completion of testing. 
+This is done to ensure that the tests run in a private sandbox and can do no
+harm to your system even in the unlikely event something goes badly wrong in
+one of the test scripts while running the tests from a privileged account. 
+A side effect of this safety precaution is that the account used to run the
+test suite must be the owner of the directory tree in which Perl has been
+built; otherwise the manipulations of temporary files and directories
+attempted by some of the tests will fail.
+
 If any tests fail, it means something is wrong with Perl. If the test suite
 hangs (some tests can take upwards of two or three minutes, or more if
 you're on an especially slow machine, depending on your machine speed, so
@@ -304,10 +315,18 @@ issuing this command sequence:
 where ".typ" is the file type of the Perl images you just built (if you
 didn't do anything special, use .EXE), and "[.subdir]test.T" is the test
 that failed. For example, with a normal Perl build, if the test indicated
-that [.op]time failed, then you'd do this:
+that t/op/time failed, then you'd do this:
 
     @ [.VMS]TEST .EXE "" "-v" [.OP]TIME.T
 
+Note that test names are reported in UNIX syntax and relative to the
+top-level build directory.  When supplying them individually to the test
+driver, you can use either UNIX or VMS syntax, but you must give the path
+relative to the [.T] directory and you must also add the .T extension to the
+filename.  So, for example if the test lib/Math/Trig fails, you would run:
+
+    @ [.VMS]TEST .EXE "" -"v" [-.lib.math]trig.t
+
 When you send in a bug report for failed tests, please include the output
 from this command, which is run from the main source directory:
 
index 37faa6d..b2ab469 100644 (file)
@@ -167,6 +167,10 @@ sub fileparse_set_fstype {
 
 sub fileparse {
   my($fullname,@suffices) = @_;
+  unless (defined $fullname) {
+      require Carp;
+      Carp::croak "fileparse(): need a valid pathname";
+  }
   my($fstype,$igncase) = ($Fileparse_fstype, $Fileparse_igncase);
   my($dirpath,$tail,$suffix,$basename);
   my($taint) = substr($fullname,0,0);  # Is $fullname tainted?
index 6bef21f..9a4da3a 100644 (file)
@@ -33,8 +33,10 @@ PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space
 
 =head1 SYNOPSIS
 
-  open($fh,">:crlf","my.txt")
-  open($fh,">:raw","his.jpg")
+  open($fh,">:crlf", "my.txt"); # portably open a text file for writing
+
+  open($fh,"<","his.jpg");      # portably open a binary file for reading
+  binmode($fh);
 
   Shell:
     PERLIO=perlio perl ....
@@ -108,6 +110,8 @@ to a such a stream.
 
 =item raw
 
+B<Note that the explicit use of the C<raw> layer is deprecated.>
+
 A pseudo-layer which performs two functions (which is messy, but
 necessary to maintain compatibility with non-PerlIO builds of Perl
 and their way things have been documented elsewhere).
index aab99fb..872d8ea 100644 (file)
@@ -146,7 +146,7 @@ open - perl pragma to set default disciplines for input and output
 
 =head1 SYNOPSIS
 
-    use open IN  => ":crlf", OUT => ":raw";
+    use open IN  => ":crlf", OUT => ":bytes";
     use open OUT => ':utf8';
     use open IO  => ":encoding(iso-8859-7)";
 
@@ -263,9 +263,9 @@ Directory handles may also support disciplines in future.
 =head1 NONPERLIO FUNCTIONALITY
 
 If Perl is not built to use PerlIO as its IO system then only the two
-pseudo-disciplines ":raw" and ":crlf" are available.
+pseudo-disciplines C<:bytes> and C<:crlf> are available.
 
-The ":raw" discipline corresponds to "binary mode" and the ":crlf"
+The C<:bytes> discipline corresponds to "binary mode" and the C<:crlf>
 discipline corresponds to "text mode" on platforms that distinguish
 between the two modes when opening files (which is many DOS-like
 platforms, including Windows).  These two disciplines are no-ops on
index f2ca525..858f23f 100644 (file)
@@ -449,21 +449,25 @@ L<perlipc/"Sockets: Client/Server Communication">.
 
 =item binmode FILEHANDLE
 
-Arranges for FILEHANDLE to be read or written in "binary" or "text" mode
-on systems where the run-time libraries distinguish between binary and
-text files.  If FILEHANDLE is an expression, the value is taken as the
-name of the filehandle.
-
-DISCIPLINE can be either of C<:raw> for binary mode or C<:crlf> for
-"text" mode.  If the DISCIPLINE is omitted, it defaults to C<:raw>.
-Returns true on success, C<undef> on failure.  To mark FILEHANDLE as
-UTF-8, use C<:utf8>, and to mark it as bytes, use C<:bytes>.
-For backward compatibility binmode(FILEHANDLE) also implicitly
-marks the handle as bytes.
-
-The C<:raw> are C<:clrf>, and any other directives of the form
-C<:...>, are called I/O I<disciplines>.  The C<open> pragma can be
-used to establish default I/O disciplines.  See L<open>.
+Arranges for FILEHANDLE to be read or written in "binary" or "text"
+mode on systems where the run-time libraries distinguish between
+binary and text files.  If FILEHANDLE is an expression, the value is
+taken as the name of the filehandle.  Returns true on success,
+C<undef> on failure.
+
+DISCIPLINE can be either of C<:bytes> for "binary" mode or C<:crlf>
+for "text" mode.  If the DISCIPLINE is omitted, it defaults to
+C<:bytes>.  To mark FILEHANDLE as UTF-8, use C<:utf8>.  For backward
+compatibility C<binmode(FILEHANDLE)> also implicitly marks the
+filehandle as bytes.
+
+The C<:bytes>, C<:crlf>, and C<:utf8>, and any other directives of the
+form C<:...>, are called I/O I<disciplines>.  The C<open> pragma can
+be used to establish default I/O disciplines.  See L<open>.
+
+The C<:raw> discipline is deprecated.  (As opposed to what Camel III
+said, it is not the inverse of C<:crlf>.)  See L<perlrun> and the
+discussion about the PERLIO environment variable.
 
 In general, binmode() should be called after open() but before any I/O
 is done on the filehandle.  Calling binmode() will flush any possibly
@@ -473,12 +477,13 @@ the default character encoding of the handle, see L<open>.
 The C<:encoding> discipline sometimes needs to be called in
 mid-stream, and it doesn't flush the stream.
 
-On some systems binmode() is necessary when you're not working with a
-text file.  For the sake of portability it is a good idea to always use
-it when appropriate, and to never use it when it isn't appropriate.
+On some systems (in general, DOS and Windows-based systems) binmode()
+is necessary when you're not working with a text file.  For the sake
+of portability it is a good idea to always use it when appropriate,
+and to never use it when it isn't appropriate.
 
-In other words:  Regardless of platform, use binmode() on binary
-files, and do not use binmode() on text files.
+In other words: regardless of platform, use binmode() on binary files
+(like for example images), and do not use binmode() on text files.
 
 The operating system, device drivers, C libraries, and Perl run-time
 system all work together to let the programmer treat a single
index 60c7929..2531838 100644 (file)
@@ -909,19 +909,21 @@ C<:perlio> will insert a C<:unix> layer below itself to do low level IO.
 
 =item :raw
 
+B<Note that the explicit use of the C<:raw> layer is deprecated.>
+
 Arranges for all accesses go straight to the lowest level layer provided
 by the configration. That is it strips off any layers above that layer.
 (The intent - unless layers are then pushed on top again -
 is to make perl's C<read> behave like C<sysread>.)
 
-Not really useful in PERLIO environment variable, instead just use C<:unix>
-layer explicitly.
+Not really useful in PERLIO environment variable, instead just use
+C<:unix> layer explicitly.
 
-In perl5.6 and some books the C<:raw> layer (also called a discipline) is
-documented as the inverse of the C<:crlf> layer. That is not really the case.
-If you want UNIX line endings on a platform that normaly does CRLF translation
-the appropriate thing to do is to add C<:perlio> to PERLIO environment
-variable.
+In Perl 5.6 and some books the C<:raw> layer (also called a discipline)
+is documented as the inverse of the C<:crlf> layer. That is not really
+the case.  If you want UNIX line endings on a platform that normally
+does CRLF translation the appropriate thing to do is to add C<:perlio>
+to PERLIO environment variable.
 
 =item :stdio