|Perl Language Reference Manual|
by Larry Wall and others
Paperback (6"x9"), 724 pages
RRP £29.95 ($39.95)
Sales of this book support The Perl Foundation! Get a printed copy>>>
binmode FILEHANDLE, LAYER
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
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. Also, people can set their I/O to be by default UTF-8 encoded Unicode, not bytes.
In other words: regardless of platform, use binmode() on binary data, 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 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
Other layers that would affect the binary nature of the stream are
also disabled. See "$obj->SYSOPEN($path,$imode,$perm,[$fh])" (PerlIO) in the Perl Library Reference Manual (Volume 3), 3, and the discussion about the
PERLIO environment variable.
:utf8, and any other directives of the
:..., are called I/O layers. The
open pragma can be used to
establish default I/O layers. See "Perl pragma to set default PerlIO layers for input and output" (open) in the Perl Library Reference Manual (Volume 1).
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 just marks the data as UTF-8 without further checking,
:encoding(utf8) 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, see "Perl pragma to set default PerlIO layers for input and output" (open) in the Perl Library Reference Manual (Volume 1).
:encoding layer sometimes needs to be called in
mid-stream, and it doesn't flush the stream. The
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 work together to let the programmer treat a single
\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
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
but what's stored in text files are the two characters
means that, if you don't use binmode() on these systems,
sequences on disk will be converted to
\n on input, and any
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
\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 28 for more details). See the
in 10 for how to manually set your input and output
|ISBN 9781906966027||Perl Language Reference Manual||See the print edition|