binmode FILEHANDLEArranges for FILEHANDLE to be read or written in "binary" or "text"mode on systems where the run-time libraries distinguish betweenbinary and text files. If FILEHANDLE is an expression, the value istaken 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 sakeof portability it is a good idea always to use it when appropriate,and never to use it when it isn't appropriate. Also, people canset 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 multipledirectives. 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 madesuitable for passing binary data. This includes turning off possible CRLFtranslation and marking it as bytes (as opposed to Unicode characters).Note that, despite what may be implied in "Programming Perl" (theCamel, 3rd edition) or elsewhere, :raw is not simply the inverse of :crlf.Other layers that would affect the binary nature of the stream arealso disabled. See PerlIO, perlrun, and the discussion about thePERLIO environment variable.
The :bytes, :crlf, :utf8, and any other directives of theform :..., are called I/O layers. The open pragma can be used toestablish default I/O layers. See open.
The LAYER parameter of the binmode() function is described as "DISCIPLINE"in "Programming Perl, 3rd Edition". However, since the publishing of thisbook, by many known as "Camel III", the consensus of the naming of thisfunctionality has moved from "discipline" to "layer". All documentationof 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 validUTF-8. More details can be found in PerlIO::encoding.
In general, binmode() should be called after open() but before any I/Ois done on the filehandle. Calling binmode() normally flushes anypending buffered output data (and perhaps pending input data) on thehandle. An exception to this is the :encoding layer thatchanges the default character encoding of the handle; see open.The :encoding layer sometimes needs to be called inmid-stream, and it doesn't flush the stream. The :encodingalso implicitly pushes on top of itself the :utf8 layer becauseinternally Perl operates on UTF8-encoded Unicode characters.
The operating system, device drivers, C libraries, and Perl run-timesystem all conspire to let the programmer treat a singlecharacter (\n) as the line terminator, irrespective of externalrepresentation. On many operating systems, the native text filerepresentation matches the internal representation, but on someplatforms the external representation of \n is made up of more thanone character.
All variants of Unix, Mac OS (old and new), and Stream_LF files on VMS usea single character to end each line in the external representation of text(even though that single character is CARRIAGE RETURN on old, pre-Darwinflavors of Mac OS, and is LINE FEED on Unix and most VMS files). In othersystems like OS/2, DOS, and the various flavors of MS-Windows, your programsees a \n as a simple \cJ, but what's stored in text files are thetwo characters \cM\cJ. That means that if you don't use binmode() onthese systems, \cM\cJ sequences on disk will be converted to \n oninput, and any \n in your program will be converted back to \cM\cJ onoutput. This is what you want for text files, but it can be disastrous forbinary files.
Another consequence of using binmode() (on some systems) is thatspecial end-of-file markers will be seen as part of the data stream.For systems from the Microsoft family this means that, if your binarydata contain \cZ, the I/O subsystem will regard it as the end ofthe 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 $\ variablesin perlvar for how to manually set your input and outputline-termination sequences.
Portability issues: binmode in perlport.
