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

class IO

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

要約

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

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

path で指定したファイルを open し、offset の所まで seek し、 length バイト読み込みます。

binwrite(path, string, offset=nil) -> Integer

path で指定されるファイルを開き、string を書き込み、 閉じます。

copy_stream(src, dst, copy_length = nil) -> Integer
copy_stream(src, dst, copy_length, src_offset) -> Integer

指定された src から dst へコピーします。 コピーしたバイト数を返します。

new(fd, mode = "r", opt={}) -> IO
for_fd(fd, mode = "r", opt={}) -> IO
open(fd, mode = "r", opt={}) -> IO
open(fd, mode = "r" opt={}) {|io| ... } -> object

オープン済みのファイルディスクリプタ fd に対する新しい IO オブジェクトを生成して返します。

foreach(path, rs = $/) {|line| ... } -> nil
foreach(path, rs = $/) -> Enumerator

path で指定されたファイルの各行を引数としてブロックを繰り返し実行します。 path のオープンに成功すれば nil を返します。

pipe -> [IO]
pipe(ext_enc) -> [IO]
pipe(enc_str, opts={}) -> [IO]
pipe(ext_enc, int_enc, opts={}) -> [IO]
pipe {|read_io, write_io| ... } -> object
pipe(ext_enc) {|read_io, write_io| ... } -> object
pipe(enc_str, opt={}) {|read_io, write_io| ... } -> object
pipe(ext_enc, int_enc, opt={}) {|read_io, write_io| ... } -> object

pipe(2) を実行して、相互につながった2つの IO オブジェクトを要素とする配列を返します。

popen(command, mode = "r", opt={}) -> IO
popen(command, mode = "r", opt={}) {|f| ... } -> object
popen([env = {}, cmdname, *args, execopt={}], mode = "r", opt={}) -> IO
popen([env = {}, cmdname, *args, execopt={}], mode = "r", opt={}) {|f| ... } -> object
popen([env = {}, [cmdname, arg0], *args, execopt={}], mode = "r", opt={}) -> IO
popen([env = {}, [cmdname, arg0], *args, .., execopt={}], mode = "r", opt={}) {|f| ... } -> object

サブプロセスを実行し、そのプロセスの標準入出力 との間にパイプラインを確立します。生成したパイプを IO オブジェクトとして返します。

popen("-", mode = "r", opt={}) -> IO
popen("-", mode = "r", opt={}) {|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 = $/, opts={})
readlines(path, limit, opts={})
readlines(path, rs, limit, opts={})

path で指定されたファイルを全て読み込んで、その各行を要素としてもつ配列を返します。

select(reads, writes = [], excepts = [], timeout = nil) -> [[IO]] | nil

select(2) を実行します。

sysopen(path, mode = "r", perm = 0666) -> Integer

path で指定されるファイルをオープンし、ファイル記述子を返しま す。

try_convert(obj) -> IO | nil

obj を to_io メソッドによって IO オブジェクトに変換します。 変換できなかった場合は nil を返します。

write(path, string, offset=nil, opt={}) -> Integer

path で指定されるファイルを開き、string を書き込み、 閉じます。

インスタンスメソッド

定義 説明
self << object -> self

object を出力します。object が文字列でない時にはメソッ ド to_s を用いて文字列に変換します。

advise(advice, offset=0, len=0) -> nil

posix_fadvise(2) を呼びだし、 ファイルへのアクセスパターンをOSに知らせます。

autoclose=(bool)

auto-close フラグを設定します。

autoclose? -> bool

auto-close フラグを返します。

binmode -> self

ストリームをバイナリモードにします。MSDOS などバイナリモードの存在 する OS でのみ有効です。そうでない場合このメソッドは何もしません。

binmode? -> bool

自身がバイナリモードなら true を返します。そうでない場合、false を返します。

bytes {|ch| ... } -> self
bytes -> Enumerator

このメソッドは obsolete です。 代わりに IO#each_byte を使用してください。

chars {|c| ... } -> self
chars -> Enumerator

このメソッドは obsolete です。 代わりに IO#each_char を使用してください。

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

ポートがクローズされている時に真を返します。

codepoints {|c| ... } -> self
codepoints -> Enumerator

このメソッドは obsolete です。 代わりに IO#each_codepoint を使用してください。

each(rs = $/) {|line| ... } -> self
each(limit) {|line| ... } -> self
each(rs, limit) {|line| ... } -> self
each(rs = $/) -> Enumerator
each(limit) -> Enumerator
each(rs, limit) -> Enumerator
each_line(rs = $/) {|line| ... } -> self
each_line(limit) {|line| ... } -> self
each_line(rs, limit) {|line| ... } -> self
each_line(rs = $/) -> Enumerator
each_line(limit) -> Enumerator
each_line(rs, limit) -> Enumerator

IO の現在位置から 1 行ずつ文字列として読み込み、それを引数として 与えられたブロックを実行します。

each_byte {|ch| ... } -> self
each_byte -> Enumerator

IO の現在位置から 1 バイトずつ読み込み、それを整数として与え、ブロックを実行します。

each_char {|c| ... } -> self
each_char -> Enumerator

self に含まれる文字を一文字つつブロックに渡して評価します。

each_codepoint {|c| ... } -> self
each_codepoint -> Enumerator

IO の各コードポイントに対して繰り返しブロックを呼びだします。

eof -> bool
eof? -> bool

ストリームがファイルの終端に達した場合、true を返します。そうでない場合、false を返します。

external_encoding -> Encoding | nil

IO の外部エンコーディングを返します。 外部エンコーディングが指定されていない場合は nil を返します。 ただし読み込み専用モードの場合は Encoding.default_external になります。

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 = $/) -> String | nil
gets(limit) -> String | nil
gets(rs, limit) -> String | 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 = $/) {|line| ... } -> self
lines(limit) {|line| ... } -> self
lines(rs, limit) {|line| ... } -> self
lines(rs = $/) -> Enumerator
lines(limit) -> Enumerator
lines(rs, limit) -> Enumerator

このメソッドは obsolete です。 代わりに IO#each_line を使用してください。

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
readline(limit) -> String
readline(rs, limit) -> String

一行読み込んで、読み込みに成功した時にはその文字列を返します。 EOF に到達した時には EOFError が発生します。

readlines(rs = $/) -> [String]
readlines(limit) -> [String]
readlines(rs = $/, limit) -> [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, opt={}) -> self
set_encoding(ext_enc) -> self
set_encoding(ext_enc, int_enc, opt={}) -> 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

指定したバイト列を書き戻します。

ungetc(char) -> nil

指定された char を読み戻します。

write(str) -> Integer

IOポートに対して str を出力します。str が文字列でなけ れば to_s による文字列化を試みます。 実際に出力できたバイト数を返します。

write_nonblock(string) -> Integer

IO をノンブロッキングモードに設定し、string を write(2) システムコールで書き出します。

定数

定義 説明
SEEK_CUR -> Fixnum

IO#seek を参照してください。

SEEK_END -> Fixnum

IO#seek を参照してください。

SEEK_SET -> Fixnum

IO#seek を参照してください。

継承したメソッド

!= __id__ instance_eval instance_exec singleton_method_added singleton_method_removed singleton_method_undefined ! <=> == === =~ __send__ _dump class display enum_for eql? equal? extend freeze frozen? hash initialize initialize_copy inspect 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? object_id pretty_inspect pretty_print pretty_print_cycle pretty_print_inspect pretty_print_instance_variables private_methods protected_methods psych_to_yaml public_method public_methods public_send remove_instance_variable respond_to? respond_to_missing? singleton_class singleton_methods taguri taguri= 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? .yaml_tag .yaml_tag_subclasses? ::ARGF ::ARGV ::DATA ::ENV ::FALSE ::NIL ::RUBY_COPYRIGHT ::RUBY_DESCRIPTION ::RUBY_ENGINE ::RUBY_PATCHLEVEL ::RUBY_PLATFORM ::RUBY_RELEASE_DATE ::RUBY_REVISION ::RUBY_VERSION ::SCRIPT_LINES__ ::STDERR ::STDIN ::STDOUT ::TOPLEVEL_BINDING ::TRUE

追加されるメソッド

定義 説明 ライブラリ
console -> File | nil

端末を File オブジェクトで返します。

io/console
console_size -> [Integer, Integer]

端末のサイズを [rows, columns] で返します。

io/console/size
cooked {|io| ... } -> object

cooked モードを有効にして指定されたブロックを評価します。

io/console
cooked! -> self

cooked モードを有効にします。端末のモードを後で元に戻す必要がある場合は IO#cooked を使用してください。

io/console
default_console_size -> [Integer, Integer]

デフォルトの端末のサイズを [rows, columns] で返します。

io/console/size
echo=(flag)

文字入力時のエコーバックが有効かどうかを設定します。

io/console
echo? -> bool

文字入力時のエコーバックが有効かどうかを返します。

io/console
expect(pattern, timeout = 9999999) -> Array | nil
expect(pattern, timeout = 9999999) {|array| ... } -> nil

レシーバから指定したパターンを読み込むまで待ちます。

expect
getch -> String

raw モードで一文字読み込んだ結果を返します。

io/console
iflush -> self

カーネルの入力バッファをフラッシュします。

io/console
ioflush -> self

カーネルの入出力バッファをフラッシュします。

io/console
noecho {|io| ... } -> object

文字入力時のエコーバックを無効に設定してブロックを評価します。

io/console
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
oflush -> self

カーネルの出力バッファをフラッシュします。

io/console
raw {|io| ... } -> object

raw モード、行編集を無効にして指定されたブロックを評価します。

io/console
raw! -> self

raw モードを有効にします。端末のモードを後で元に戻す必要がある場合は IO#raw を使用してください。

io/console
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
winsize -> [Integer, Integer]

端末のサイズを [rows, columns] で返します。

io/console
winsize=(size)

端末のサイズを設定します。

io/console