Clarify VMS-specific handling of $/ = \N.
authorCraig A. Berry <craigberry@mac.com>
Sun, 25 Mar 2012 18:57:09 +0000 (13:57 -0500)
committerCraig A. Berry <craigberry@mac.com>
Sun, 25 Mar 2012 19:36:38 +0000 (14:36 -0500)
When the record read feature was introduced in 5b2b9c687790241e8
in 1998 (but by Dan Sugalski, not Hans Mulder as the git history
erroneously says), sysread() was a couple of years from learning
about utf-8 and PerlIO was just a fancy way of calling stdio.  The
documentation was reasonable given that environment.

Now it's potentially misleading to say that record reads are "the
equivalent of C<sysread>" because sysread on filehandles opened
with ":utf8" does characters, not bytes.  The salient point about
the analogy with sysread was always that the read is unbuffered.
In the old days, this was in contrast to the buffering done in
stdio's fread(), but now it's in contrast to the buffering in the
perlio layer.  By emphasizing the role of buffering, we can
actually shorten and simplify the docs.

Side note:  Both Camel 3 and Camel 4 have the following problematic
statement in the documentation of $/: "Record mode mixes with line
mode only on systems where standard I/O supplies a read(3) function;
VMS is a notable exception."  VMS certainly does have a read(3)
function and in fact that's what's used directly for record reads
(via PerlLIO_read) on VMS only.  And as far as I know, it is
fread(), not read(), that is considered "standard I/O" everywhere.

N.B. Record reads on non-record-oriented files on VMS will likely
start using the same buffering as other platforms in a future
version of Perl.

pod/perlvar.pod

index ea1f601..c09aea5 100644 (file)
@@ -1341,12 +1341,10 @@ with every read.  If a record is larger than the record size you've
 set, you'll get the record back in pieces.  Trying to set the record
 size to zero or less will cause reading in the (rest of the) whole file.
 
-On VMS, record reads are done with the equivalent of C<sysread>,
-so it's best not to mix record and non-record reads on the same
-file.  (This is unlikely to be a problem, because any file you'd
-want to read in record mode is probably unusable in line mode.)
-Non-VMS systems do normal I/O, so it's safe to mix record and
-non-record reads of a file.
+On VMS only, record reads bypass PerlIO layers and any associated
+buffering,so you must not mix record and non-record reads on the
+same filehandle.  Record mode mixes with line mode only when the
+same buffering layer is in use for both modes.
 
 If you perform a record read on a FILE with an encoding layer such as
 C<:encoding(latin1)> or C<:utf8>, you may get an invalid string as a