Ruby 1.9.0 > Home > All Libraries > library _builtin > class IO

class IO

ancestors: IO < Enumerable < File::Constants < Object < Kernel < BasicObject

Abstract

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

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

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

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

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へ変換されていることが分かる。

まとめ

以上をまとめると以下の表のようになります。

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

                               指定無し          外部エンコーディングのみ    両方のエンコーディング
------------------------------------------------------------------------------------------------
バイナリ読み込みメソッド      ASCII-8BIT                ASCII-8BIT                ASCII-8BIT

テキスト読み込みメソッド     default_external      外部エンコーディング       内部エンコーディング

エンコーディングの変換

                             指定無し     外部エンコーディングのみ      両方のエンコーディング
------------------------------------------------------------------------------------------------
バイナリ読み込みメソッド     変換なし             変換なし                     変換なし

テキスト読み込みメソッド     変換なし             変換なし                     変換あり

書き込みメソッド             変換なし             変換あり                     変換あり

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

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                      通常どおり

Singleton Methods

signature	description
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 -> Enumerable::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.

Instance Methods

signature	description
<<(object) -> self	object を出力します。object が文字列でない時にはメソッド to_s を用いて文字列に変換します。
binmode -> self	ストリームをバイナリモードにします。MSDOS などバイナリモードの存在する OS でのみ有効です。そうでない場合このメソッドは何もしません。
bytes -> Enumerable::Enumerator	自身を 1 バイトずつ整数としてイテレートするような Enumerable::Enumerator オブジェクトを生成して返します。
each_char{\|c\| ... } -> self chars{\|c\| ... } -> self each_char -> Enumerable::Enumerator chars -> Enumerable::Enumerator	self に含まれる文字を一文字つつブロックに渡して評価します。
clone -> IO dup -> IO	レシーバと同じ IO を参照する新しい IO オブジェクトを返します。参照しているファイル記述子は dup(2) されます。
close -> nil	入出力ポートをクローズします。
close_on_exec=(bool) -> 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(rs = $/) {\|line\| ... } -> self each_line(rs = $/) {\|line\| ... } -> self each(rs = $/) -> Enumerable::Enumerator each_line(rs = $/) -> Enumerable::Enumerator	IO の現在位置から 1 行ずつ文字列として読み込み、それを引数として与えられたブロックを実行します。
each_byte {\|ch\| ... } -> self each_byte -> Enumerable::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) が返した整数を返します。
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 = $/) -> Enumerable::Enumerator	自身を 1 行ずつイテレートするような Enumerable::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 を返します。
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 として呼出元に報告されます。

Constants

signature	description
SEEK_CUR	IO#seek を参照してください。
SEEK_END	IO#seek を参照してください。
SEEK_SET	IO#seek を参照してください。

Inherited Methods

! != == === =~ __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 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? 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_splat to_str to_yaml to_yaml_properties to_yaml_style untaint

Added Methods

signature	description	library
expect(pattern, timeout = 9999999) -> Array \| nil expect(pattern, timeout = 9999999){\|array\| ... } -> nil	レシーバから指定したパターンを読み込むまで待ちます。	expect
nonblock(bool = true) { ... }	ブロック実行中、一時的に self のブロックモードを変更する。 bool が真ならノンブロックモード、偽ならブロックモードになる。	io/nonblock
nonblock=(bool)	bool が真なら self をノンブロックモードに、偽ならブロックモードにする。	io/nonblock
nonblock?	self がノンブロックモードならば真を、ブロックモードなら偽を返す。	io/nonblock
ready?	ブロックせずに読み込み可能なら真を返します。そうでなければ nil を返します。 self が EOF に達していれば false を返します。	io/wait
scanf(format) scanf(format) {\|*ary\| ...}	String#scanfも参照してください。	scanf
wait([timeout = nil])	self が読み込み可能になるまでブロックし、読み込み可能になったら self を返します。	io/wait