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, otherwise it returns undef and sets $! (errno).
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 always to use it when appropriate, and never to use it when it isn't appropriate. Also, people can set their I/O to be by default UTF8-encoded Unicode, not bytes.
In other words: regardless of platform, use binmode on binary data, like images, for example.
If LAYER is present it is a single string, but may contain multiple directives. The directives alter the behaviour of the filehandle. When LAYER is present, using binmode on a text file makes sense.
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, despite what may be implied in "Programming Perl" (the
Camel, 3rd edition) or elsewhere, :raw
is not simply the inverse of :crlf
.
Other layers that would affect the binary nature of the stream are
also disabled. See PerlIO, perlrun, and the discussion about the
PERLIO environment variable.
The :bytes
, :crlf
, :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.
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...
To mark FILEHANDLE as UTF-8, use :utf8
or :encoding(UTF-8)
.
:utf8
just marks the data as UTF-8 without further checking,
while :encoding(UTF-8)
checks the data for actually being valid
UTF-8. More details can be found in PerlIO::encoding.
In general, binmode should be called
after open but before any I/O is done on the
filehandle. Calling binmode normally
flushes 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.
The :encoding
layer sometimes needs to be called in
mid-stream, and it doesn't flush the stream. :encoding
also implicitly pushes on top of itself the :utf8
layer because
internally Perl operates on UTF8-encoded Unicode characters.
The operating system, device drivers, C libraries, and Perl run-time
system all conspire to let the programmer treat a single
character (\n
) as the line terminator, irrespective of 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.
All variants of Unix, Mac OS (old and new), 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 old, pre-Darwin
flavors of Mac OS, and is 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 contain \cZ
, the I/O subsystem will
regard it as the end of the file, unless you use
binmode.
binmode is important not only 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.
Portability issues: binmode in perlport.