Ruby 1.9.2 リファレンスマニュアル > ライブラリ一覧 > 組み込みライブラリ > IOクラス

class IO

クラスの継承リスト: IO < Enumerable < File::Constants < Object < Kernel < BasicObject

要約

基本的な入出力機能のためのクラスです。

[[unknown:Traps: IO ポートのオープンに関わる問題|trap::IO]]

File::Constants は、File から IO へ移動しました。

多言語化と IO のエンコーディング

IO オブジェクトはエンコーディングを持ちます。エンコーディングの影響を受けるメソッドと受けないメソッドがあります。

影響を受けるメソッドでは、IO のエンコーディングに従い読み込まれた文字列のエンコーディングが決定されます。また IO のエンコーディングを適切に設定することにより、読み込み時・書き込み時に文字列のエンコーディングを変換させることもできます。

エンコーディングの影響を受けるメソッドと受けないメソッド

IO の読み込みメソッドは2種類存在します。テキスト読み込みメソッドとバイナリ読み込みメソッドです。

テキスト読み込みメソッドは IO のエンコーディングの影響をうけます。詳しくは「IO のエンコーディングとエンコーディングの変換」を参照して下さい。以下がテキスト読み込みメソッドです。

バイナリ読み込みメソッドは IO のエンコーディングの影響を受けません。返す文字列のエンコーディングは常に ASCII-8BIT になります。以下がバイナリ読み込みメソッドです。

また書き込みメソッド IO#write も IO のエンコーディングの影響を受けます。 IO のすべての書き込みメソッドは内部で IO#write を呼びますので、書き込みメソッドはすべて IO のエンコーディングの影響を受けます。

シーク関連のメソッドはエンコーディングの影響を受けません。常に1バイトを単位として動作します。

例:

f = File.open('t.txt', 'r+:euc-jp')
p f.getc.encoding                             #=> Encoding::EUC_JP
p f.read(1).encoding                          #=> Encoding::ASCII_8BIT

IO のエンコーディングとエンコーディングの変換

IO オブジェクトは外部エンコーディングと内部エンコーディングを持ちます。外部エンコーディングとは IO が表すファイルなどの文字エンコーディングです。内部エンコーディングとは IO から読み込まれた文字列、あるいは IO の書き込みメソッドへ渡す文字列の文字エンコーディングです。

以下の三通りがあります。

IO のエンコーディングが指定されていない場合

IO からテキスト読み込みメソッドによって読み込まれた文字列のエンコーディングは Encoding.default_external に設定されます。このとき実際の文字エンコーディングは検査されず、変換もされません。

外部エンコーディングのみが指定されている場合

IO からテキスト読み込みメソッドによって読み込まれた文字列のエンコーディングは外部エンコーディングに設定されます。このとき実際の文字エンコーディングは検査されず、変換もされません。

IO へ書き込まれる文字列は外部エンコーディングへと変換されます。外部エンコーディングへの変換方法が分からない場合は例外が発生します。

外部エンコーディングと内部エンコーディング(あるいは default_internal)が指定されている場合

IO からテキスト読み込みメソッドによって読み込まれた文字列は、外部エンコーディングから内部エンコーディング(あるいは default_internal)へと変換されます。指定された文字エンコーディングと実際の文字エンコーディングが違っていた場合、例外が発生します。内部エンコーディングと Encoding.default_internal が両方とも指定されている場合は、内部エンコーディングが優先されます。

IO へ書き込まれる文字列は外部エンコーディングへと変換されます。外部エンコーディングへの変換方法が分からない場合は例外が発生します。

IO に対してエンコーディングを指定する方法には、生成時に IO.open や File.open に渡すモードとともに指定するものと生成後に IO#set_encoding を使って指定するものの二通りがあります。詳しくはそれぞれのメソッドの項を参照して下さい。通常は前者の方法を使います。

例1:

f = File.open('file1')
p f.getc.encoding        #=> Encoding::EUC_JP

例2:

f = File.open('t.txt', 'w+:shift_jis:euc-jp')
f.write "\xB4\xC1\xBB\xFA"            # 文字列 "漢字" の EUC-JP リテラル
f.rewind
s = f.read(4)
puts s.dump                           #=> "\x8A\xBF\x8E\x9A"
                                      # エンコーディングがSJISへ変換されていることが分かる。

まとめ

以上をまとめると以下の表のようになります。Encoding.default_external は常に設定されているので、省略してあります。

読み込んだ文字列のエンコーディング

                                                   バイナリ読み込みメソッド      テキスト読み込みメソッド
----------------------------------------------------------------------------------------------------------
                                        指定無し        ASCII-8BIT                   default_external

                           default_internal のみ        ASCII-8BIT                   default_internal

                        外部エンコーディングのみ        ASCII-8BIT                 外部エンコーディング

                    内部エンコーディング指定あり        ASCII-8BIT                 内部エンコーディング

    内部エンコーディングと default_internal 両方        ASCII-8BIT                 内部エンコーディング

エンコーディングの変換

                                              バイナリ読み込みメソッド   テキスト読み込みメソッド   書き込みメソッド
---------------------------------------------------------------------------------------------------------------------
                                  指定無し           変換なし                 変換なし                   変換なし

                  外部エンコーディングのみ           変換なし                 変換なし                   変換あり

                     default_internal のみ           変換なし                 変換あり                   変換あり

                  内部エンコーディングのみ           変換なし                 変換あり                   変換あり

外部エンコーディングと内部エンコーディング           変換なし                 変換あり                   変換あり

   外部エンコーディングと default_internal           変換なし                 変換あり                   変換あり

デフォルトの外部エンコーディングの指定

Encoding.default_external はコマンドオプション -E で指定します。 -E が指定されなかった場合は次のような優先順位で決定されます。

-E (最優先) > -K > locale

ファイル名のエンコーディング

ファイル名の文字エンコーディングはプラットフォームに依存します。ファイル名の文字エンコーディングが固定されているプラットフォーム(Win, Mac)では、エンコーディングは暗黙に変換されます(予定)。UNIX では変換されずそのままシステムコールに渡されます。

Dir.glob, Dir.foreach などが返すファイル名のエンコーディングも同様にプラットフォーム依存です。 UNIX では ASCII-8BIT です。

binmode

Windows の IO にはテキストモードとバイナリモードという2種類のモードが存在します。これらのモードは上で説明した IO のエンコーディングとは独立です。改行の変換にしか影響しません。

EOF での読み込みメソッドの振る舞いの違い

空ファイルや EOF での各読み込みメソッドの振る舞いは以下のとおりです。ただし、length を指定できるメソッドに関しては、length に nil または 0 を指定した場合、 EOF であっても常に空文字列 "" を返します。

メソッド                      空のファイルに対して

IO.read(空ファイル)           ""
IO.read(空ファイル, length)   nil
IO.readlines(空ファイル)      []
IO.foreach(空ファイル)        何もしない

メソッド                      既にEOFだったら

IO#each                       何もしない
IO#each_byte                  何もしない
IO#getc                       nil
IO#gets                       nil
IO#read()                     ""
IO#read(length)               nil
IO#read_nonblock              EOFError
IO#readchar                   EOFError
IO#readline                   EOFError
IO#readlines                  []
IO#readpartial                EOFError
IO#sysread                    EOFError
IO#bytes                      通常どおり
IO#lines                      通常どおり

特異メソッド

定義	説明
`binread(path, length = nil, offset = 0) -> String \| nil`	@see IO.read
`copy_stream(src, dst, copy_length = nil) -> Integer copy_stream(src, dst, copy_length, src_offset) -> Integer`	指定された src から dst へコピーします。コピーしたバイト数を返します。
`new(fd, mode = "r") -> IO for_fd(fd, mode = "r") -> IO open(fd, mode = "r") -> IO open(fd, mode = "r") {\|io\| ... } -> object`	オープン済みのファイルディスクリプタ fd に対する新しい IO オブジェクトを生成して返します。
`foreach(path, rs = $/) {\|line\| ... } -> nil foreach(path, rs = $/) -> Enumerator`	path で指定されたファイルの各行を引数としてブロックを繰り返し実行します。 path のオープンに成功すれば nil を返します。
`pipe -> [IO] pipe(enc_str) -> [IO] pipe(ext_enc) -> [IO] pipe(ext_enc, int_enc) -> [IO]`	pipe(2) を実行して、相互につながった2つの IO オブジェクトを要素とする配列を返します。
`popen(command, mode = "r") -> IO popen(command, mode = "r") {\|io\| ... } -> object`	command をサブプロセスとして実行し、そのプロセスの標準入出力との間にパイプラインを確立します。生成したパイプを IO オブジェクトとして返します。
`popen("-", mode = "r") -> IO popen("-", mode = "r") {\|io\| ... } -> object`	第一引数に文字列 "-" が指定された時、fork(2) を行い子プロセスの標準入出力との間にパイプラインを確立します。親プロセスでは IO オブジェクトを返し、子プロセスでは nil を返します。
`read(path, opt = {}) -> String \| nil read(path, length = nil, opt = {}) -> String \| nil read(path, length = nil, offset = 0, opt = {}) -> String \| nil`	path で指定されたファイルを offset 位置から length バイト分読み込んで返します。
`readlines(path, rs = $/) -> [String]`	path で指定されたファイルを全て読み込んで、その各行を要素としてもつ配列を返します。
`select(reads, writes = [], excepts = [], timeout = nil) -> [[IO]] \| nil`	select(2) を実行します。
`sysopen(path, mode = "r", perm = 0666) -> Integer`	path で指定されるファイルをオープンし、ファイル記述子を返します。
`try_convert(obj) -> IO \| nil`	Try to convert obj into an IO, using to_io method. Returns converted IO or nil if obj cannot be converted for any reason.

インスタンスメソッド

定義	説明
`self << object -> self`	object を出力します。object が文字列でない時にはメソッド to_s を用いて文字列に変換します。
`autoclose=(bool)`	auto-close フラグを設定します。
`autoclose? -> bool`	Returns +true+ if the underlying file descriptor of _ios_ will be closed automatically at its finalization, otherwise +false+.
`binmode -> self`	ストリームをバイナリモードにします。MSDOS などバイナリモードの存在する OS でのみ有効です。そうでない場合このメソッドは何もしません。
`binmode? -> bool`	自身がバイナリモードなら true を返します。そうでない場合、false を返します。
`bytes -> Enumerator`	自身を 1 バイトずつ整数としてイテレートするような Enumerator オブジェクトを生成して返します。
`each_char {\|c\| ... } -> self chars {\|c\| ... } -> self each_char -> Enumerator chars -> Enumerator`	self に含まれる文字を一文字つつブロックに渡して評価します。
`clone -> IO dup -> IO`	レシーバと同じ IO を参照する新しい IO オブジェクトを返します。参照しているファイル記述子は dup(2) されます。
`close -> nil`	入出力ポートをクローズします。
`close_on_exec=(bool)`	自身に close-on-exec フラグを設定します。
`close_on_exec? -> bool`	自身に close-on-exec フラグが設定されていた場合 true を返します。そうでない場合に false を返します。
`close_read -> nil`	読み込み用の IO を close します。主にパイプや読み書き両用に作成した IO オブジェクトで使用します。
`close_write -> nil`	書き込み用の IO を close します。
`closed? -> bool`	ポートがクローズされている時に真を返します。
`each_codepoint {\|c\| ... } -> self codepoints {\|c\| ... } -> self each_codepoint -> Enumerator codepoints -> Enumerator`	IO の各コードポイントに対して繰り返します。
`each(rs = $/) {\|line\| ... } -> self each_line(rs = $/) {\|line\| ... } -> self each(rs = $/) -> Enumerator each_line(rs = $/) -> Enumerator`	IO の現在位置から 1 行ずつ文字列として読み込み、それを引数として与えられたブロックを実行します。
`each_byte {\|ch\| ... } -> self each_byte -> Enumerator`	IO の現在位置から 1 バイトずつ読み込み、それを整数として与え、ブロックを実行します。
`eof -> bool eof? -> bool`	ストリームがファイルの終端に達した場合、true を返します。そうでない場合、false を返します。
`external_encoding -> Encoding \| nil`	IO の外部エンコーディングを返します。外部エンコーディングが指定されていない場合は nil を返します。
`fcntl(cmd, arg = 0) -> Integer`	IOに対してシステムコール fcntl を実行します。機能の詳細は fcntl(2) を参照してください。 fcntl(2) が返した整数を返します。
`fdatasync -> 0 \| nil`	IO のすべてのバッファされているデータを直ちにディスクに書き込みます。
`fileno -> Integer to_i -> Integer`	ファイル記述子を表す整数を返します。
`flush -> self`	IO ポートの内部バッファをフラッシュします。
`fsync -> 0 \| nil`	書き込み用の IO に対して、システムコール fsync(2) を実行します。IO#flush を行ったあと、(OSレベルで)まだディスクに書き込まれていないメモリ上にあるデータをディスクに書き出します。
`getbyte -> Integer \| nil`	IO から1バイトを読み込み整数として返します。既に EOF に達していれば nil を返します。
`getc -> String \| nil`	IO ポートから外部エンコーディングに従い 1 文字読み込んで返します。 EOF に到達した時には nil を返します。
`gets(rs = $/, limit) -> String \| nil`	一行読み込んで、読み込みに成功した時にはその文字列を返します。 EOF に到達した時には nil を返します。
`internal_encoding -> Encoding \| nil`	IO の内部エンコーディングを返します。内部エンコーディングが指定されていない場合は nil を返します。
`ioctl(cmd, arg = 0) -> Integer`	IO に対してシステムコール ioctl を実行し、その結果を返します。機能の詳細は ioctl(2) を参照してください。
`isatty -> bool tty? -> bool`	入出力ポートがttyに結合している時、真を返します。そうでない場合 false を返します。
`lineno -> Integer`	現在の行番号を整数で返します。実際には IO#gets が呼ばれた回数です。改行以外のセパレータで gets が呼ばれた場合など、実際の行番号と異なる場合があります。
`lineno=(number)`	現在の行番号を number にセットします。 $. は次回の読み込みの時に更新されます。
`lines(rs = $/) -> Enumerator`	自身を 1 行ずつイテレートするような Enumerator オブジェクトを生成して返します。
`pid -> Integer \| nil`	自身が IO.popen で作られたIOポートなら、子プロセスのプロセス ID を返します。それ以外は nil を返します。
`pos -> Integer tell -> Integer`	ファイルポインタの現在の位置を整数で返します。
`pos=(n)`	ファイルポインタを指定位置に移動します。 IO#seek(n, IO::SEEK_SET) と同じです。
`print(*arg) -> nil`	引数を IO ポートに順に出力します。引数を省略した場合は、$_ を出力します。
`printf(format, *arg) -> nil`	C 言語の printf と同じように、format に従い引数を文字列に変換して、self に出力します。
`putc(ch) -> object`	文字 ch を self に出力します。引数の扱いは Kernel.#putc と同じです。詳細はこちらを参照してください。ch を返します。
`puts(*obj) -> nil`	各 obj を self に出力し、それぞれの後に改行を出力します。引数の扱いは Kernel.#puts と同じです。詳細はこちらを参照してください。
`read(length = nil, outbuf = "") -> String \| nil`	length バイト読み込んで、その文字列を返します。
`read_nonblock(maxlen, outbuf = "") -> String`	IO をノンブロッキングモードに設定し、その後で read(2) システムコールにより長さ maxlen を上限として読み込み、文字列として返します。 EAGAIN, EINTR などは Errno::EXXX 例外として呼出元に報告されます。
`readbyte -> Integer`	IO から1バイトを読み込み整数として返します。既に EOF に達していれば EOFError が発生します。
`readchar -> String`	IO ポートから 1 文字読み込んで返します。 EOF に到達した時には EOFError が発生します。
`readline(rs = $/) -> String`	一行読み込んで、読み込みに成功した時にはその文字列を返します。 EOF に到達した時には EOFError が発生します。
`readlines(rs = $/) -> [String]`	データを全て読み込んで、その各行を要素としてもつ配列を返します。既に EOF に達していれば空配列 [] を返します。
`readpartial(maxlen, outbuf = "") -> String`	IO から長さ maxlen を上限として読み込み、文字列として返します。即座に得られるデータが存在しないときにはブロックしてデータの到着を待ちます。即座に得られるデータが 1byte でも存在すればブロックしません。
`reopen(io) -> self`	自身を指定された io に繋ぎ換えます。
`reopen(path) -> self reopen(path, mode) -> self`	path で指定されたファイルにストリームを繋ぎ換えます。
`rewind -> 0`	ファイルポインタを先頭に移動します。IO#lineno は 0 になります。
`seek(offset, whence = IO::SEEK_SET) -> 0`	ファイルポインタを whence の位置から offset だけ移動させます。 offset 位置への移動が成功すれば 0 を返します。
`set_encoding(enc_str) -> self set_encoding(ext_enc) -> self set_encoding(ext_enc, int_enc) -> self`	IO のエンコーディングを設定します。
`stat -> File::Stat`	ファイルのステータスを含む File::Stat オブジェクトを生成して返します。
`sync -> bool`	現在の出力が同期モードならば true を返します。そうでない場合は false を返します。
`sync=(newstate)`	自身を同期モードに設定すると、出力関数の呼出毎にバッファがフラッシュされます。
`sysread(maxlen, outbuf = "") -> String`	read(2) を用いて入力を行ない、入力されたデータを含む文字列を返します。stdio を経由しないので gets や getc や eof? などと混用すると思わぬ動作をすることがあります。
`sysseek(offset, whence = IO::SEEK_SET) -> Integer`	lseek(2) と同じです。IO#seek では、 IO#sysread, IO#syswrite と併用すると正しく動作しないので代わりにこのメソッドを使います。位置 offset への移動が成功すれば移動した位置(ファイル先頭からのオフセット)を返します。
`syswrite(string) -> Integer`	write(2) を用いて string を出力します。 string が文字列でなければ to_s による文字列化を試みます。実際に出力できたバイト数を返します。
`to_io -> self`	self を返します。
`ungetbyte(c) -> nil`	Pushes back bytes (passed as a parameter) onto <em>ios</em>, such that a subsequent buffered read will return it. Only one byte may be pushed back before a subsequent read operation (that is, you will be able to read only the last of several bytes that have been pushed back). Has no effect with unbuffered reads (such as <code>IO#sysread</code>).
`ungetc(char) -> nil`	指定された char を読み戻します。
`write(str) -> Integer`	IOポートに対して str を出力します。str が文字列でなければ to_s による文字列化を試みます。実際に出力できたバイト数を返します。
`write_nonblock(string) -> Integer`	IO をノンブロッキングモードに設定し、string を write(2) システムコールで書き出します。 write(2) が成功した場合、書き込んだ長さを返します。 EAGAIN, EINTR などは例外 Errno::EXXX として呼出元に報告されます。

定数

定義	説明
`SEEK_CUR -> Fixnum`	IO#seek を参照してください。
`SEEK_END -> Fixnum`	IO#seek を参照してください。
`SEEK_SET -> Fixnum`	IO#seek を参照してください。
`WaitReadable -> Module`	IO#read_nonblock を参照してください。
`WaitWritable -> Module`	IO#write_nonblock を参照してください。

継承したメソッド

! != == === =~ __id__ __send__ _dump class dclone display enum_for eql? equal? extend freeze frozen? hash initialize initialize_copy inspect instance_eval instance_exec instance_of? instance_variable_defined? instance_variable_get instance_variable_set instance_variables is_a? marshal_dump marshal_load method method_missing methods must_be must_be_close_to must_be_empty must_be_instance_of must_be_kind_of must_be_nil must_be_same_as must_be_within_epsilon must_equal must_include must_match must_raise must_respond_to must_send must_throw nil? pretty_inspect pretty_print pretty_print_cycle pretty_print_inspect pretty_print_instance_variables private_methods protected_methods public_methods remove_instance_variable respond_to? respond_to_missing? singleton_class singleton_method_added singleton_method_removed singleton_method_undefined singleton_methods taint tainted? tap to_a to_ary to_hash to_int to_proc to_regexp to_s to_str to_yaml to_yaml_properties to_yaml_style trust untaint untrust untrusted? wont_be wont_be_close_to wont_be_empty wont_be_instance_of wont_be_kind_of wont_be_nil wont_be_same_as wont_be_within_epsilon wont_equal wont_include wont_match wont_respond_to

追加されるメソッド

定義	説明	ライブラリ
`expect(pattern, timeout = 9999999) -> Array \| nil expect(pattern, timeout = 9999999) {\|array\| ... } -> nil`	レシーバから指定したパターンを読み込むまで待ちます。	expect
`nonblock(bool = true) { ... } -> object`	ブロック実行中、一時的に self のブロックモードを変更します。 bool が真ならノンブロックモード、偽ならブロックモードになります。	io/nonblock
`nonblock=(bool)`	bool が真なら self をノンブロックモードに、偽ならブロックモードにします。	io/nonblock
`nonblock? -> bool`	self がノンブロックモードならば true を、ブロックモードなら false を返します。	io/nonblock
`nread -> Integer`	ブロックせずに読み込み可能なバイト数を返します。ブロックする場合は0を返します。	io/wait
`ready? -> bool \| nil`	ブロックせずに読み込み可能ならtrueを、ブロックしてしまう可能性があるならfalseを返します。	io/wait
`scanf(format) -> Array scanf(format) {\|*ary\| ...} -> Array`	String#scanfも参照してください。	scanf
`wait(timeout = nil) -> bool \| self \| nil`	self が読み込み可能になるまでブロックし、読み込み可能になったら真値を返します。タイムアウト、もしくはEOFでそれ以上読みこめない場合は偽の値を返します。	io/wait