perl-5.20.1
binmode FILEHANDLE, LAYER
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 undef and sets $! (errno).

バイナリファイルとテキストファイルを区別する OS において、 FILEHANDLE を「バイナリ」または「テキスト」で読み書きするように 指定します。 FILEHANDLE が式である場合には、その式の値がファイルハンドルの 名前として使われます。 成功時には真を返し、失敗時には undef を返して $! (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.

テキストファイルでないものを扱う場合に binmode() が必要な システムもあります(一般的には DOS と Windows ベースのシステムです)。 移植性のために、適切なときには常にこれを使い、適切でないときには 決して使わないというのは良い考えです。 また、デフォルトとして I/O を bytes ではなく UTF-8 エンコードされた Unicode にセットすることも出来ます。

In other words: regardless of platform, use binmode() on binary data, like images, for example.

言い換えると: プラットフォームに関わらず、 例えばイメージのようなバイナリファイルに対しては binmode() を 使ってください。

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.

LAYER が存在すると、それは単一の文字列ですが、複数の指示子を 含むことができます。 指示子はファイルハンドルの振る舞いを変更します。 LAYER が存在すると、テキストファイルでの binmode が意味を持ちます。

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.

LAYER が省略されたり、:raw が指定されると、ファイルハンドルはバイナリ データの通過に適するように設定されます。 これには CRLF 変換をオフにしたり、それぞれを(Unicode 文字ではなく) バイトであるとマークしたりすることを含みます。 "プログラミング Perl"(ラクダ本第三版) やその他で暗示されているにも関わらず、 :raw は単なる :crlf逆ではありません。 ストリームのバイナリとしての性質に影響を与える その他の層も無効にされますPerlIO, perlrun およびPERLIO 環境変数に関する議論を参照してください。

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. See open.

:bytes, :crlf, and :utf8, 及びその他の :... 形式の指示子は I/O が呼び出されます。 open プラグマはデフォルト I/O 層を指定するために使われます。 open を参照してください。

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...

binmode() 関数の LAYER パラメータは 「プログラミングPerl 第3版」では 「ディシプリン(DISCIPLINE)」と表現されていました。 しかし、「ラクダ本第3版」として知られているこの本の出版後、この機能の名前は 「ディシプリン」から「層」に変更することで合意されました。 従って、このバージョンの Perl の全ての文書では「ディシプリン」ではなく 「層」と記述されています。では通常の解説に戻ります…

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.

FILEHANDLE が UTF-8 であるというマークをつけるには、:utf8:encoding(UTF-8) を使ってください。 :utf8 は、さらなるチェックなしにデータが UTF-8 としてマークしますが、 :encoding(UTF-8) はデータが実際に有効な UTF-8 かどうかをチェックします。 さらなる詳細は 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 open. The :encoding layer sometimes needs to be called in mid-stream, and it doesn't flush the stream. The :encoding also implicitly pushes on top of itself the :utf8 layer because internally Perl operates on UTF8-encoded Unicode characters.

一般的に binmode() は open() を呼び出した後、このファイルハンドルに対する I/O 操作をする前に呼び出すべきです。 binmode() を呼び出すと、普通はこのファイルハンドルに対して バッファリングされている全ての出力データ (およびおそらくは入力データ)をフラッシュします。 例外は、このハンドルに対するデフォルト文字エンコーディングを変更する :encoding 層です; open を参照してください。 :encoding 層はストリームの途中で呼び出す必要があることがあり、 それによってストリームはフラッシュされません。 Perl は内部で UTF-8 エンコードされた Unicode 文字を操作しているので、 :encoding は暗黙のうちに自身を :utf8 層の上に押し上げます。

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.

オペレーションシステム、デバイスドライバ、C ライブラリ、 Perl ランタイムシステムは全て、プログラマが外部表現に関わらず 1 文字 (\n) を行終端として扱えるように協調作業します。 多くのオペレーティングシステムでは、ネイティブテキストファイル表現は 内部表現と同じですが、\n の外部表現が複数文字になる プラットフォームもあります。

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.

全ての Unix 系、(新旧の)Mac OS、VMS の Stream_LF ファイルは テキストの外部表現として各行の末尾に一つの文字を 使っています(しかしその文字は古い Darwin 以前の Mac OS では復帰で、 Unix とほとんどのVMS のファイルでは改行です)。 VMS, MS-DOS, MS-Windows 系といったその他のシステムでは、 プログラムからは \n は単純に \cJ に見えますが、 テキストファイルとして保存される場合は \cM\cJ の 2 文字になります。 つまり、もしこれらのシステムで binmode() を使わないと、 ディスク上の \cM\cJ という並びは入力時に \n に変換され、 プログラムが出力した全ての \n\cM\cJ に逆変換されます。 これはテキストファイルの場合は思い通りの結果でしょうが、 バイナリファイルの場合は悲惨です。

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() を(いくつかのシステムで)使うことによるその他の作用としては、 特別なファイル終端マーカーがデータストリームの一部として 見られることです。 Microsoft ファミリーのシステムでは、binmode() を使っていないと もしバイナリデータに \cZ が含まれていたときに、I/O サブシステムが これをファイル終端とみなすことを意味します。

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.

binmode() は readline() と print() 操作にだけではなく、 read(), seek(), sysread(), syswrite(), tell() を使うときにも重要です (詳細は perlport を参照してください)。 入出力の行端末シーケンスを手動でセットする方法については perlvar$/ 変数と $\ 変数を参照してください。

Portability issues: "binmode" in perlport.

移植性の問題: "binmode" in perlport