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, undef on failure.
If LAYER is omitted or specified as :raw the filehandle is made suitable
for passing binary data. This includes turning off possible CRLF translation and marking
it as bytes (as opposed to Unicode characters). Note that as desipite what may be implied
in "Programming Perl" (the Camel) or elsewhere :raw is not
the simply inverse of :crlf -- other layers which would affect binary nature
of the stream are also disabled. See PerlIO, perlrun and the discussion
about the PERLIO environment variable.
The LAYER parameter of the binmode() function is described as "DISCIPLINE"
in "Programming Perl, 3rd Edition". However, since the publishing of this book,
by many known as "Camel III", the consensus of the naming of this functionality
has moved from "discipline" to "layer". All documentation of this
version of Perl therefore refers to "layers" rather than to
"disciplines". Now back to the regularly scheduled documentation...
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 LAYER is present it is a single string, but may contain multiple directives. The
directives alter the behaviour of the file handle. When LAYER is present using binmode on
text file makes sense.
To mark FILEHANDLE as UTF-8, use :utf8.
The :bytes, :crlf, and :utf8, and any other
directives of the form :..., are called I/O layers. The open
pragma can be used to establish default I/O layers. See open.
In general, binmode() should be called after open() but before any I/O 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 :encoding
layer that changes the default character encoding of the handle, see open. The :encoding
layer sometimes needs to be called in mid-stream, and it doesn't flush the stream.
The operating system, device drivers, C libraries, and Perl run-time system all work
together to let the programmer treat a single character (\n) as the line
terminator, irrespective of the external representation. On many operating systems, the
native text file representation matches the internal representation, but on some platforms
the external representation of \n is made up of more than one character.
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). In other systems like
OS/2, DOS and the various flavors of MS-Windows your program sees a \n as a
simple \cJ, but what's stored in text files are the two characters \cM\cJ.
That means that, if you don't use binmode() on these systems, \cM\cJ
sequences on disk will be converted to \n on input, and any \n
in your program will be converted back to \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. For systems from the Microsoft family
this means that if your binary data contains \cZ, the I/O subsystem will
regard it as the end of the file, unless you use binmode().
binmode() is not only important for readline() and print() operations, but also when
using read(), seek(), sysread(), syswrite() and tell() (see perlport for more details).
See the $/ and $\ variables in perlvar for how to manually
set your input and output line-termination sequences.
