=head1 SYNOPSIS
- open($fh,">:crlf", "my.txt"); # portably open a text file for writing
+ open($fh,"<:crlf", "my.txt"); # portably open a text file for reading
open($fh,"<","his.jpg"); # portably open a binary file for reading
binmode($fh);
=item raw
-B<Note that the explicit use of the C<raw> layer is deprecated.>
+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).
+C<:raw> has been documented as both the opposite of C<:crlf> and
+as a way to make a stream "binary". With the new IO system those
+two are no longer equivalent. The name has also been read as meaning
+an unbuffered stream "as close to the operating system as possible".
+See below for better ways to do things.
+
+The C<:raw> layer exists to maintain compatibility with non-PerlIO builds
+of Perl and to approximate the way it has been documented and how
+it was "faked" in perl5.6. It is a pseudo-layer which performs two
+functions (which is messy).
Firstly it forces the file handle to be considered binary at that
-point in the layer stack, i.e. it turns off any CRLF translation.
+point in the layer stack, i.e it turns off any CRLF translation.
Secondly in prevents the IO system seaching back before it in the
-layer specification. Thus:
+layer specification. This second effect is intended to disable other
+non-binary features of the stream.
+
+Thus:
open($fh,":raw:perlio",...)
-Forces the use of C<perlio> layer even if the platform default, or
+forces the use of C<perlio> layer even if the platform default, or
C<use open> default is something else (such as ":encoding(iso-8859-7)")
(the C<:encoding> requires C<use Encode>) which would interfere with
binary nature of the stream.
=back
+=head2 Alternatives to raw
+
+To get a binary stream the prefered method is to use:
+
+ binmode($fh);
+
+which is neatly backward compatible with how such things have
+had to be coded on some platforms for years.
+The current implementation comprehends the effects of C<:utf8> and
+C<:crlf> layers and will be extended to comprehend similar translations
+if they are defined in future releases of perl.
+
+To get an un-buffered stream specify an unbuffered layer (e.g. C<:unix>)
+the open call:
+
+ open($fh,"<:unix",$path)
+
+To get a non-CRLF translated stream on any platform start from
+the un-buffered stream and add the appropriate layer:
+
+ open($fh,"<:unix:perlio",$path)
+
+
=head2 Defaults and how to override them
If the platform is MS-DOS like and normally does CRLF to "\n"
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.
+If DISCIPLINE is ommited the filehandle is made suitable for
+passing binary data. This includes turning off CRLF translation
+and marking it as bytes.
+
+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
+(like for example images).
+
+If DISCIPLINE is present it is a single string, but may contain
+multiple directives. The directives alter the behaviour of the
+file handle. When DISCIPLINE is present using binmode on text
+file makes sense.
+
+To mark FILEHANDLE as UTF-8, use C<:utf8>.
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>.
+form C<:...>, are called I/O I<disciplines>. The normal implementation
+of disciplines in perl5.8 and later is in terms of I<layers>. See
+L<PerlIO>. (There is typically a one-to-one correspondence between
+layers and disiplines.) 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.
+said, it is not the inverse of C<:crlf>.) See L<PerlIO>, 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
-pending buffered input or output data on the handle. The only
-exception to this is the C<:encoding> discipline that changes
-the default character encoding of the handle, see L<open>.
+is done on the filehandle. Calling binmode() will normally flush any
+pending buffered output data (and perhaps pending input data) on the
+handle. An exception to this is the C<:encoding> discipline that
+changes 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 (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
-(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
character (C<\n>) as the line terminator, irrespective of the external
Mac OS, all variants of Unix, and Stream_LF files on VMS use a single
character to end each line in the external representation of text (even
though that single character is CARRIAGE RETURN on Mac OS and LINE FEED
-on Unix and most VMS files). Consequently binmode() has no effect on
-these operating systems. In other systems like OS/2, DOS and the various
-flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>, but
-what's stored in text files are the two characters C<\cM\cJ>. That means
-that, if you don't use binmode() on these systems, C<\cM\cJ> sequences on
-disk will be converted to C<\n> on input, and any C<\n> in your program
-will be converted back to C<\cM\cJ> on output. This is what you want for
-text files, but it can be disastrous for binary files.
+on Unix and most VMS files). In other systems like OS/2, DOS and the
+various flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>,
+but what's stored in text files are the two characters C<\cM\cJ>. That
+means that, if you don't use binmode() on these systems, C<\cM\cJ>
+sequences on disk will be converted to C<\n> on input, and any C<\n> in
+your program will be converted back to C<\cM\cJ> on output. This is what
+you want for text files, but it can be disastrous for binary files.
Another consequence of using binmode() (on some systems) is that
special end-of-file markers will be seen as part of the data stream.
=item lock THING
-This function places an advisory lock on a shared variable, or referenced
+This function places an advisory lock on a shared variable, or referenced
object contained in I<THING> until the lock goes out of scope.
lock() is a "weak keyword" : this means that if you've defined a function
and opening C<< '>-' >> opens STDOUT.
You may use the three-argument form of open to specify
-I<I/O disciplines> that affect how the input and output
-are processed: see L</binmode> and L<open>. For example
+I<I/O disciplines> or IO "layers" to be applied to the handle that affect how the input and output
+are processed: (see L<open> and L<PerlIO> for more details).
+For example
open(FH, "<:utf8", "file")
will open the UTF-8 encoded file containing Unicode characters,
-see L<perluniintro>.
+see L<perluniintro>. (Note that if disciplines are specified in the
+three-arg form then default disciplines set by the C<open> pragma are
+ignored.)
Open returns nonzero upon success, the undefined value otherwise. If
the C<open> involved a pipe, the return value happens to be the pid of
character, and which encode that character in C as C<"\n">, do not
need C<binmode>. The rest need it.
-In the three argument form MODE may also contain a list of IO "layers"
-(see L<open> and L<PerlIO> for more details) to be applied to the
-handle. This can be used to achieve the effect of C<binmode> as well
-as more complex behaviours.
-
When opening a file, it's usually a bad idea to continue normal execution
if the request failed, so C<open> is frequently used in connection with
C<die>. Even if C<die> won't do what you want (say, in a CGI script,
projects / p5sagit/p5-mst-13.2.git / commitdiff