=over =item binmode FILEHANDLE, LAYER X X X X X =item binmode FILEHANDLE 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 C and sets C<$!> (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 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 file handle. When LAYER is present using binmode on a text file makes sense. If LAYER is omitted or specified as C<: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 I<"Programming Perl"> (the Camel) or elsewhere, C<:raw> is I simply the inverse of C<:crlf> -- other layers which would affect the binary nature of the stream are I disabled. See L, L and the discussion about the PERLIO environment variable. The C<:bytes>, C<:crlf>, and C<:utf8>, and any other directives of the form C<:...>, are called I/O I. The C pragma can be used to establish default I/O layers. See L. I To mark FILEHANDLE as UTF-8, use C<:utf8> or C<:encoding(utf8)>. C<:utf8> just marks the data as UTF-8 without further checking, while C<:encoding(utf8)> checks the data for actually being valid UTF-8. More details can be found in L. 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 C<:encoding> layer that changes the default character encoding of the handle, see L. The C<:encoding> layer sometimes needs to be called in mid-stream, and it doesn't flush the stream. The C<:encoding> also implicitly pushes on top of itself the C<:utf8> layer because internally Perl will operate on UTF-8 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 character (C<\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 C<\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 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. For systems from the Microsoft family this means that if your binary data contains C<\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 L for more details). See the C<$/> and C<$\> variables in L for how to manually set your input and output line-termination sequences. =back