Ruby 1.9.3 リファレンスマニュアル > ライブラリ一覧 > 組み込みライブラリ > IOクラス
クラスの継承リスト: IO < Enumerable < File::Constants < Object < Kernel < BasicObject
基本的な入出力機能のためのクラスです。
File::Constants は、File から 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 からテキスト読み込みメソッドによって読み込まれた文字列のエンコーディングは Encoding.default_external に設定されます。このとき実際の文字エンコーディングは検査されず、変換もされません。
IO からテキスト読み込みメソッドによって読み込まれた文字列のエンコーディングは外部エンコーディング に設定されます。このとき実際の文字エンコーディングは検査されず、変換もされません。
IO へ書き込まれる文字列は外部エンコーディングへと変換されます。 外部エンコーディングへの変換方法が分からない場合は例外が発生します。
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 です。
Windows の IO にはテキストモードとバイナリモードという2種類のモードが存在します。 これらのモードは上で説明した IO のエンコーディングとは独立です。改行の変換にしか影響しません。
空ファイルや 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[permalink][rdoc]path で指定したファイルを open し、offset の所まで seek し、 length バイト読み込みます。
length を省略するとファイルの末尾まで読み込みます。
ファイルを開くときの mode は "rb:ASCII-8BIT" です。
[SEE_ALSO] IO.read
binwrite(path, string, offset=nil) -> Integer[permalink][rdoc]path で指定されるファイルを開き、string を書き込み、 閉じます。
offset を指定するとその位置までシークします。
offset を指定しないと、書き込みの末尾でファイルを 切り捨てます。
[SEE_ALSO] IO.write
copy_stream(src, dst, copy_length = nil) -> Integer[permalink][rdoc]copy_stream(src, dst, copy_length, src_offset) -> Integer指定された src から dst へコピーします。 コピーしたバイト数を返します。
コピー元の src が IO オブジェクトの場合は、src のオフセットから ファイル名の場合はファイルの最初からコピーを開始します。 コピー先の dst に関しても同様です。
dst にファイル名を指定し、そのファイルが存在しない場合、 ファイルは作成されます。ファイルが存在する場合は長さ 0 に切り詰められます。
src が IO オブジェクトでかつ src_offset が指定されている場合、 src のオフセット(src.pos)は変更されません。
new(fd, mode = "r", opt={}) -> IO[permalink][rdoc]for_fd(fd, mode = "r", opt={}) -> IOopen(fd, mode = "r", opt={}) -> IOopen(fd, mode = "r" opt={}) {|io| ... } -> objectオープン済みのファイルディスクリプタ fd に対する新しい IO オブジェクトを生成して返します。
IO.open にブロックが与えられた場合、IO オブジェクトを生成しそれを引数としてブロックを 実行します。ブロックの終了とともに fd はクローズされます。ブロックの結果を返します。 IO.new, IO.for_fd はブロックを受け付けません。
このメソッドは以下のオプションを利用できます。
また、String#encode で説明されている :invalid => :replace などの 変換オプションも指定することができます。外部エンコーディングから 内部エンコーディングへの変換をするときに用いられます。
foreach(path, rs = $/) {|line| ... } -> nil[permalink][rdoc]foreach(path, rs = $/) -> Enumeratorpath で指定されたファイルの各行を引数としてブロックを繰り返し実行します。 path のオープンに成功すれば nil を返します。
ブロックが与えられなかった場合は、path で指定されたファイルの各行を繰り返す Enumerator オブジェクトを生成して返します。
テキスト読み込みメソッドとして動作します。 path が空ファイルの場合、何もせずに nil を返します。 Kernel.#open と同様 path の先頭が "|" ならば、"|" に続くコマンドの出力を読み取ります。
[SEE_ALSO] $/
pipe -> [IO][permalink][rdoc]pipe(ext_enc) -> [IO]pipe(enc_str, opts={}) -> [IO]pipe(ext_enc, int_enc, opts={}) -> [IO]pipe {|read_io, write_io| ... } -> objectpipe(ext_enc) {|read_io, write_io| ... } -> objectpipe(enc_str, opt={}) {|read_io, write_io| ... } -> objectpipe(ext_enc, int_enc, opt={}) {|read_io, write_io| ... } -> objectpipe(2) を実行して、相互につながった2つの IO オブジェクトを要素とする配列を返します。
戻り値の配列は最初の要素が読み込み側で、次の要素が書き込み側です。
ブロックが渡された場合は、そのブロックに2つの IO オブジェクトが渡され、 ブロックの返り値がこのメソッドの返り値となります。 ブロック終了時に IO オブジェクトがもし close されていないならば close します(close されていてるオブジェクトはそのままです)。
得られる2つの IO オブジェクトのエンコーディングを引数で指定することが できます。
r, w = IO.pipe p [r, w] # => [#<IO:0x401b90f8>, #<IO:0x401b7718>] Thread.new do w.puts "foo" w.close end p r.gets # => "foo\n"
popen(command, mode = "r", opt={}) -> IO[permalink][rdoc]popen(command, mode = "r", opt={}) {|f| ... } -> objectpopen([env = {}, cmdname, *args, execopt={}], mode = "r", opt={}) -> IOpopen([env = {}, cmdname, *args, execopt={}], mode = "r", opt={}) {|f| ... } -> objectpopen([env = {}, [cmdname, arg0], *args, execopt={}], mode = "r", opt={}) -> IOpopen([env = {}, [cmdname, arg0], *args, .., execopt={}], mode = "r", opt={}) {|f| ... } -> objectサブプロセスを実行し、そのプロセスの標準入出力 との間にパイプラインを確立します。生成したパイプを IO オブジェクトとして返します。
p io = IO.popen("cat", "r+") # => #<IO:fd 4>
io.puts "foo"
io.close_write
p io.gets # => "foo\n"
サブプロセスを指定する方法は2通りあります。文字列を指定する場合と配列を指定する場合です。 文字列の場合は、シェルを経由して子プロセスを実行し、 配列の場合は、シェルを経由せずに子プロセスを実行します。
シェルを経由しない場合(上のシグネチャで cmdname を含む場合)には *args がサブプロセスの引数として使われます。この場合には *args はシェルでの ワイルドカード展開などはなされません。
配列内に配列を指定することで、arg0(みせかけのプログラム名)を指定することができます。
ブロックが与えられた場合は生成した IO オブジェクトを引数にブ ロックを実行し、ブロックの実行結果を返します。ブロックの実行後、生成したパイ プは自動的にクローズされます。
p IO.popen("cat", "r+") {|io|
io.puts "foo"
io.close_write
io.gets
}
# => "foo\n"
opt でプロセス起動のためのオプションや、パイプ IO オブジェクトの属性(エンコーディングや 読み書き能力)を指定することができます。 プロセス起動のためのオプションは Kernel.#spawn と、 パイプオブジェクトの属性の指定のオプションは IO.new と共通です。 つまり、 :external_encoding や :unsetenv_others が指定できます。 オプションの詳しい意味は Kernel.#spawn や IO.new を参照してください。
# nkfプロセスから得られる文字列を EUC-JP と指定する
# IO.new などと共通のオプションが指定できる
IO.popen("nkf -e filename", external_encoding: "EUC-JP"){|nkf_io|
nkf_io.read
}
これに加えて、プロセス起動のためのオプションを execopt で指定することもできます。 execopt ではエンコーディングなどは指定できません。
# 標準エラー出力を子プロセス側で標準出力にリダイレクトする
# 標準エラー出力と標準出力がマージされる
# Kernel.#spawn と共通のオプション
IO.popen(["ls", "/", :err=>[:child, :out]]) {|ls_io|
ls_result_with_error = ls_io.read
}
# 上と同じ、配列の外側でもオプションが指定できる
IO.popen(["ls", "/"], :err=>[:child, :out]) {|ls_io|
ls_result_with_error = ls_io.read
}
popen("-", mode = "r", opt={}) -> IO[permalink][rdoc]popen("-", mode = "r", opt={}) {|io| ... } -> object第一引数に文字列 "-" が指定された時、fork(2) を 行い子プロセスの標準入出力との間にパイプラインを確立します。 親プロセスでは IO オブジェクトを返し、子プロセスでは nil を返します。
io = IO.popen("-", "r+")
if io # parent
io.puts "foo"
p io.gets # => "child output: foo\n"
io.close
else # child
s = gets
print "child output: " + s
exit
end
ブロックを与えられた場合、親プロセスでは生成した IO オブジェクトを引数に ブロックを実行し、その結果を返します。ブロックの実行後、生成したパイ プは自動的にクローズされます。 子プロセスでは nil を引数にブロックを実行し終了します。
p IO.popen("-", "r+") {|io|
if io # parent
io.puts "foo"
io.gets
else # child
s = gets
puts "child output: " + s
end
}
# => "child output: foo\n"
opt ではエンコーディングの設定やプロセス起動のためのオプションが指定できます。 IO.new や Kernel.#spawn で指定できるものと共通なので 詳しくはそちらを見てください。
read(path, opt = {}) -> String | nil[permalink][rdoc]read(path, length = nil, opt = {}) -> String | nilread(path, length = nil, offset = 0, opt = {}) -> String | nilpath で指定されたファイルを offset 位置から length バイト分読み込んで返します。
既に EOF に達している場合は nil を返します。ただし、length に nil か 0 が指定されている場合は、空文字列 "" を返します。例えば、IO.read(空ファイル) は "" を返します。
引数 length が指定された場合はバイナリ読み込みメソッド、そうでない場合はテキスト読み込みメソッドとして 動作します。
Kernel.#open と同様 path の先頭が "|" ならば、"|" に続くコマンドの出力を読み取ります。
引数 opt で有効なキーと値は以下のとおりです。 キーはいずれも Symbol オブジェクトです。
読み込んだ文字列のエンコーディングを指定します。 読み込む長さを指定した場合はこれは無視されます。
IO.open のモードを指定します。 "r" で始まる文字列である必要があります。
IO.open に渡される引数を配列で指定します。
これらの他、 :external_encoding など IO.open のオプション引数が指定できます。
[SEE_ALSO] IO.binread
例:
IO.read(empty_file) #=> "" IO.read(empty_file, 1) #=> nil IO.read(one_byte_file, 0, 10) #=> "" IO.read(one_byte_file, nil, 10) #=> "" IO.read(one_byte_file, 1, 10) #=> nil
readlines(path, rs = $/, opts={})[permalink][rdoc]readlines(path, limit, opts={})readlines(path, rs, limit, opts={})path で指定されたファイルを全て読み込んで、その各行を要素としてもつ配列を返します。
Kernel.#open と同様 path の先頭が "|" ならば、"|" に続くコマンドの出力を読み取ります。
テキスト読み込みメソッドとして動作します。
limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で 切れないように余分に読み込む場合があります。
opts でファイルを開くときのオプションを指定します。エンコーディングなど を指定できます。 File.open と同様なのでそちらを参照してください。
select(reads, writes = [], excepts = [], timeout = nil) -> [[IO]] | nil[permalink][rdoc]select(2) を実行します。
与えられた入力/出力/例外待ちの IO オブジェクトの中から準備ができたものを それぞれ配列にして、配列の配列として返します。 タイムアウトした時には nil を返します。
Kernel.#select と同じです。
rp, wp = IO.pipe
mesg = "ping "
100.times{
rs, ws, = IO.select([rp], [wp])
if r = rs[0]
ret = r.read(5)
print ret
case ret
when /ping/
mesg = "pong\n"
when /pong/
mesg = "ping "
end
end
if w = ws[0]
w.write(mesg)
end
}
sysopen(path, mode = "r", perm = 0666) -> Integer[permalink][rdoc]path で指定されるファイルをオープンし、ファイル記述子を返しま す。
IO.for_fd などで IO オブジェクトにしない限り、このメソッ ドでオープンしたファイルをクローズする手段はありません。
[SEE_ALSO] Kernel.#open
try_convert(obj) -> IO | nil[permalink][rdoc]obj を to_io メソッドによって IO オブジェクトに変換します。 変換できなかった場合は nil を返します。
IO.try_convert(STDOUT) # => STDOUT
IO.try_convert("STDOUT") # => nil
write(path, string, offset=nil, opt={}) -> Integer[permalink][rdoc]path で指定されるファイルを開き、string を書き込み、 閉じます。
offset を指定するとその位置までシークします。
offset を指定しないと、書き込みの末尾でファイルを 切り捨てます。
引数最後のハッシュはファイルを開くときに使われます。 エンコーディングなどを指定することができます。 詳しくは IO.open を見てください。
[SEE_ALSO] IO.binwrite
self << object -> self[permalink][rdoc]object を出力します。object が文字列でない時にはメソッ ド to_s を用いて文字列に変換します。
以下のような << の連鎖を使うことができます。
STDOUT << 1 << " is a " << Fixnum << "\n"
advise(advice, offset=0, len=0) -> nil[permalink][rdoc]posix_fadvise(2) を呼びだし、 ファイルへのアクセスパターンをOSに知らせます。
advice には以下のいずれかのシンボルを指定します。
これらの advice が具体的に何をするのかはプラットフォーム依存です。
ここでいう「データ」は offset と len で特定することができます。 len が 0 ならば、offset からファイル末尾までを指定したことになります。 デフォルトでは offset と len がともに 0 なので、 ファイル全体を指定したことになります。
posix_fadvise をサポートしていないプラットフォーム上では 何もしません。
autoclose=(bool)[permalink][rdoc]auto-close フラグを設定します。
フラグが設定されているオブジェクトは close時/GCでのファイナライザ呼出時にファイルデスクリプタを close します。 設定されていない場合は close しません。
[SEE_ALSO] IO#autoclose?
f = open("/dev/null")
IO.for_fd(f.fileno)
# ...
f.gets # may cause IOError
f = open("/dev/null")
IO.for_fd(f.fileno).autoclose = true
# ...
f.gets # won't cause IOError
autoclose? -> bool[permalink][rdoc]auto-close フラグを返します。
[SEE_ALSO] IO#autoclose=
binmode -> self[permalink][rdoc]ストリームをバイナリモードにします。MSDOS などバイナリモードの存在 する OS でのみ有効です。そうでない場合このメソッドは何もしません。
バイナリモードから通常のモードに戻す方法は再オープンしかありません。
binmode? -> bool[permalink][rdoc]自身がバイナリモードなら true を返します。そうでない場合、false を返します。
bytes {|ch| ... } -> self[permalink][rdoc]bytes -> Enumeratorこのメソッドは obsolete です。 代わりに IO#each_byte を使用してください。
IO の現在位置から 1 バイトずつ読み込み、それを整数として与え、ブロックを実行します。
ブロックが与えられなかった場合は、自身から生成した Enumerator オブジェクトを返します。
バイナリ読み込みメソッドとして動作します。
[SEE_ALSO] IO#each_byte
chars {|c| ... } -> self[permalink][rdoc]chars -> Enumeratorこのメソッドは obsolete です。 代わりに IO#each_char を使用してください。
self に含まれる文字を一文字ずつブロックに渡して評価します。
self は読み込み用にオープンされていなければなりません。
ブロックを省略した場合は各文字について繰り返す Enumerator を返します。
[SEE_ALSO] IO#each_char
clone -> IO[permalink][rdoc]dup -> IOレシーバと同じ IO を参照する新しい IO オブジェクトを返します。 参照しているファイル記述子は dup(2) されます。
clone の際に self は一旦 IO#flush されます。 フリーズした IO の clone は同様にフリーズされた IO を返しますが、 dup は内容の等しいフリーズされていない IO を返します。
close -> nil[permalink][rdoc]入出力ポートをクローズします。
以後このポートに対して入出力を行うと例外 IOError が発生しま す。ガーベージコレクトの際にはクローズされていない IO ポートはクロー ズされます。 self がパイプでプロセスにつながっていれば、そのプロセスの終 了を待ち合わせます。
close_on_exec=(bool)[permalink][rdoc]自身に close-on-exec フラグを設定します。
このフラグをセットすると exec(2) 時にそのファイルデスクリプタを close します。
[SEE_ALSO] fcntl(2)
f = open("/dev/null")
f.close_on_exec = true
system("cat", "/proc/self/fd/#{f.fileno}") # cat: /proc/self/fd/3: No such file or directory
f.closed? #=> false
[SEE_ALSO] IO#close_on_exec?
close_on_exec? -> bool[permalink][rdoc]自身に close-on-exec フラグが設定されていた場合 true を返します。 そうでない場合に false を返します。
f = open("/dev/null")
f.close_on_exec? #=> false
f.close_on_exec = true
f.close_on_exec? #=> true
f.close_on_exec = false
f.close_on_exec? #=> false
[SEE_ALSO] IO#close_on_exec=
close_read -> nil[permalink][rdoc]読み込み用の IO を close します。主にパイプや読み書き両用に作成し た IO オブジェクトで使用します。
close_write -> nil[permalink][rdoc]書き込み用の IO を close します。
closed? -> bool[permalink][rdoc]ポートがクローズされている時に真を返します。
codepoints {|c| ... } -> self[permalink][rdoc]codepoints -> Enumeratorこのメソッドは obsolete です。 代わりに IO#each_codepoint を使用してください。
IO の各コードポイントに対して繰り返しブロックを呼びだします。
ブロックの引数にはコードポイントを表す整数が渡されます。
ブロックを省略した場合には、Enumerator を返します。
[SEE_ALSO] IO#each_codepoint
each(rs = $/) {|line| ... } -> self[permalink][rdoc]each(limit) {|line| ... } -> selfeach(rs, limit) {|line| ... } -> selfeach(rs = $/) -> Enumeratoreach(limit) -> Enumeratoreach(rs, limit) -> Enumeratoreach_line(rs = $/) {|line| ... } -> selfeach_line(limit) {|line| ... } -> selfeach_line(rs, limit) {|line| ... } -> selfeach_line(rs = $/) -> Enumeratoreach_line(limit) -> Enumeratoreach_line(rs, limit) -> EnumeratorIO の現在位置から 1 行ずつ文字列として読み込み、それを引数として 与えられたブロックを実行します。
ブロックが与えられなかった場合は、自身から生成した Enumerator オブジェクトを返します。
テキスト読み込みメソッドとして動作します。
limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で 切れないように余分に読み込む場合があります。
each_byte {|ch| ... } -> self[permalink][rdoc]each_byte -> EnumeratorIO の現在位置から 1 バイトずつ読み込み、それを整数として与え、ブロックを実行します。
ブロックが与えられなかった場合は、自身から生成した Enumerator オブジェクトを返します。
バイナリ読み込みメソッドとして動作します。
each_char {|c| ... } -> self[permalink][rdoc]each_char -> Enumeratorself に含まれる文字を一文字ずつブロックに渡して評価します。
self は読み込み用にオープンされていなければなりません。
ブロックを省略した場合は各文字について繰り返す Enumerator を返します。
f = File.new("testfile")
f.each_char {|c| print c, ' ' } #=> #<File:testfile>
each_codepoint {|c| ... } -> self[permalink][rdoc]each_codepoint -> EnumeratorIO の各コードポイントに対して繰り返しブロックを呼びだします。
ブロックの引数にはコードポイントを表す整数が渡されます。
ブロックを省略した場合には、Enumerator を返します。
eof -> bool[permalink][rdoc]eof? -> boolストリームがファイルの終端に達した場合、true を返します。そうでない場合、false を返します。
f = File.new("testfile")
dummy = f.readlines
f.eof #=> true
自身がパイプやソケットなどのストリームであった場合、相手がデータを送るか close するまでブロックします。
r, w = IO.pipe
Thread.new { sleep 10; w.close }
r.eof? #=> 10秒ブロックしてから true を返す。
r, w = IO.pipe
Thread.new { sleep 10; w.puts "a" }
r.eof? #=> 10秒ブロックしてから false を返す。
r, w = IO.pipe
r.eof? # 永久にブロックします。
eof, eof? は入力バッファにデータを読み込むので、IO#sysread と同時に使うと正常に 動作しません。
external_encoding -> Encoding | nil[permalink][rdoc]IO の外部エンコーディングを返します。 外部エンコーディングが指定されていない場合は nil を返します。 ただし読み込み専用モードの場合は Encoding.default_external になります。
fcntl(cmd, arg = 0) -> Integer[permalink][rdoc]IOに対してシステムコール fcntl を実行します。 機能の詳細は fcntl(2) を参照してください。 fcntl(2) が返した整数を返します。
fdatasync -> 0 | nil[permalink][rdoc]IO のすべてのバッファされているデータを直ちにディスクに書き込みます。
fdatasync(2) をサポートしていない OS 上では代わりに IO#fsync を呼びだします。
IO#fsync との違いは fdatasync(2) を参照してください。
fileno -> Integer[permalink][rdoc]to_i -> Integerファイル記述子を表す整数を返します。
flush -> self[permalink][rdoc]IO ポートの内部バッファをフラッシュします。
fsync -> 0 | nil[permalink][rdoc]書き込み用の IO に対して、システムコール fsync(2) を実行します。IO#flush を行ったあと、(OSレベルで)まだディスクに 書き込まれていないメモリ上にあるデータをディスクに書き出します。
成功すれば 0 を返します。 fsync(2) がサポートされていない場合は nil を返します。
getbyte -> Integer | nil[permalink][rdoc]IO から1バイトを読み込み整数として返します。 既に EOF に達していれば nil を返します。
f = File.new("testfile")
f.getbyte #=> 84
f.getbyte #=> 104
getc -> String | nil[permalink][rdoc]IO ポートから外部エンコーディングに従い 1 文字読み込んで返します。 EOF に到達した時には nil を返します。
テキスト読み込みメソッドとして動作します。 IO#readchar との違いは EOF での振る舞いのみです。
例:
[SEE_ALSO] IO#readchar
gets(rs = $/) -> String | nil[permalink][rdoc]gets(limit) -> String | nilgets(rs, limit) -> String | nil一行読み込んで、読み込みに成功した時にはその文字列を返します。 EOF に到達した時には nil を返します。
テキスト読み込みメソッドとして動作します。 読み込んだ文字列を変数 $_ にセットします。 IO#readline との違いは EOF での振る舞いのみです。
limit で最大の読み込みバイト数を指定します。ただし ファイルのエンコーディングがマルチバイトエンコーディングである場合には 読み込んだ文字列がマルチバイト文字の途中で切れないように 数バイト余分に読み込む場合があります。
f = File.new("oneline_file")
f.gets #=> "This is line one\n"
$_ #=> "This is line one\n"
f.gets #=> nil
$_ #=> nil
[SEE_ALSO] $/, IO#readline
internal_encoding -> Encoding | nil[permalink][rdoc]IO の内部エンコーディングを返します。 内部エンコーディングが指定されていない場合は nil を返します。
ioctl(cmd, arg = 0) -> Integer[permalink][rdoc]IO に対してシステムコール ioctl を実行し、その結果を返します。 機能の詳細は ioctl(2) を参照してください。
isatty -> bool[permalink][rdoc]tty? -> bool入出力ポートがttyに結合している時、真を返します。そうでない場合 false を返します。
lineno -> Integer[permalink][rdoc]現在の行番号を整数で返します。実際には IO#gets が呼ばれた回数です。 改行以外のセパレータで gets が呼ばれた場合など、実際の行番号と異なる場合があります。
f = File.new("testfile")
f.lineno #=> 0
f.gets #=> "This is line one\n"
f.lineno #=> 1
f.gets #=> "This is line two\n"
f.lineno #=> 2
[SEE_ALSO] $.
lineno=(number)[permalink][rdoc]現在の行番号を number にセットします。 $. は次回の読み込みの時に更新されます。
f = File.new("testfile")
f.gets #=> "This is line one\n"
$. #=> 1
f.lineno = 1000
f.lineno #=> 1000
$. #=> 1
f.gets #=> "This is line two\n"
$. #=> 1001
[SEE_ALSO] $.
lines(rs = $/) {|line| ... } -> self[permalink][rdoc]lines(limit) {|line| ... } -> selflines(rs, limit) {|line| ... } -> selflines(rs = $/) -> Enumeratorlines(limit) -> Enumeratorlines(rs, limit) -> Enumeratorこのメソッドは obsolete です。 代わりに IO#each_line を使用してください。
IO の現在位置から 1 行ずつ文字列として読み込み、それを引数として 与えられたブロックを実行します。
ブロックが与えられなかった場合は、自身から生成した Enumerator オブジェクトを返します。
テキスト読み込みメソッドとして動作します。
limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で 切れないように余分に読み込む場合があります。
[SEE_ALSO] $/, IO#each_line
pid -> Integer | nil[permalink][rdoc]自身が IO.popen で作られたIOポートなら、子プロセスのプロセス ID を 返します。それ以外は nil を返します。
pos -> Integer[permalink][rdoc]tell -> Integerファイルポインタの現在の位置を整数で返します。
pos=(n)[permalink][rdoc]ファイルポインタを指定位置に移動します。 IO#seek(n, IO::SEEK_SET) と同じです。
print(*arg) -> nil[permalink][rdoc]引数を IO ポートに順に出力します。引数を省略した場合は、$_ を出力します。
printf(format, *arg) -> nil[permalink][rdoc]C 言語の printf と同じように、format に従い引数 を文字列に変換して、self に出力します。
第一引数に IO を指定できないこと、引数を省略できないことを除けば Kernel.#printf と同じです。
[SEE_ALSO] Kernel.#printf
putc(ch) -> object[permalink][rdoc]文字 ch を self に出力します。 引数の扱いは Kernel.#putc と同じです。詳細はこちらを参照し てください。ch を返します。
[SEE_ALSO] Kernel.#putc
puts(*obj) -> nil[permalink][rdoc]各 obj を self に出力し、それぞれの後に改行を出力します。 引数の扱いは Kernel.#puts と同じです。詳細はこちらを参照し てください。
$stdout.puts("this", "is", "a", "test", [1, [nil, 3]])
#=>
this
is
a
test
1
nil
3
[SEE_ALSO] Kernel.#puts
read(length = nil, outbuf = "") -> String | nil[permalink][rdoc]length バイト読み込んで、その文字列を返します。
引数 length が指定された場合はバイナリ読み込みメソッド、そうでない場合はテキスト読み込みメソッドとして 動作します。 既に EOF に達していれば nil を返します。 ただし、length に nil か 0 が指定されている場合は、空文字列 "" を返します。 例えば、open(空ファイル) {|f| f.read } は "" となります。
第二引数を指定した read の呼び出しでデータが空であった場合 (read が nil を返す場合)、outbuf は空文字列になります。
outbuf = "x" * 20;
io = File.open("/dev/null")
p io.read(10,outbuf)
p outbuf
=> nil
""
read_nonblock(maxlen, outbuf = nil) -> String[permalink][rdoc]IO をノンブロッキングモードに設定し、 その後で read(2) システムコールにより 長さ maxlen を上限として読み込み、文字列として返します。 EAGAIN, EINTR などは Errno::EXXX 例外として呼出元に報告されます。
発生した例外 がErrno::EAGAIN、 Errno::EWOULDBLOCK である場合は、 その例外オブジェクトに IO::WaitReadable が Object#extend されます。
なお、バッファが空でない場合は、read_nonblock はバッファから読み込みます。この場合、read(2) システムコールは呼ばれません。
このメソッドはノンブロッキングモードにする点を除いて IO#readpartial と 同じであることに注意してください。
バイナリ読み込みメソッドとして動作します。 既に EOF に達していれば EOFError が発生します。ただし、maxlen に 0 が指定されている場合は、空文字列 "" を返します。
readbyte -> Integer[permalink][rdoc]IO から1バイトを読み込み整数として返します。 既に EOF に達していれば EOFError が発生します。
readchar -> String[permalink][rdoc]IO ポートから 1 文字読み込んで返します。 EOF に到達した時には EOFError が発生します。
テキスト読み込みメソッドとして動作します。 IO#getc との違いは EOF での振る舞いのみです。
f = File.new("testfile")
p f.readchar #=> "い"
p f.readchar #=> "ろ"
p f.readchar #=> "は"
f.read
f.readchar #=> EOFError
[SEE_ALSO] IO#getc
readline(rs = $/) -> String[permalink][rdoc]readline(limit) -> Stringreadline(rs, limit) -> String一行読み込んで、読み込みに成功した時にはその文字列を返します。 EOF に到達した時には EOFError が発生します。
テキスト読み込みメソッドとして動作します。 読み込んだ文字列を変数 $_ にセットします。IO#gets との違いは EOF での振る舞いのみです。
limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で 切れないように余分に読み込む場合があります。
f = File.new("oneline_file")
f.readline #=> "This is line one\n"
$_ #=> "This is line one\n"
f.readline #=> EOFError
$_ #=> nil
readlines(rs = $/) -> [String][permalink][rdoc]readlines(limit) -> [String]readlines(rs = $/, limit) -> [String]データを全て読み込んで、その各行を要素としてもつ配列を返します。 既に EOF に達していれば空配列 [] を返します。
テキスト読み込みメソッドとして動作します。
limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で 切れないように余分に読み込む場合があります。
readpartial(maxlen, outbuf = "") -> String[permalink][rdoc]IO から長さ maxlen を上限として読み込み、文字列として返します。 即座に得られるデータが存在しないときにはブロックしてデータの到着を待ちます。 即座に得られるデータが 1byte でも存在すればブロックしません。
バイナリ読み込みメソッドとして動作します。 既に EOF に達していれば EOFError が発生します。 ただし、maxlen に 0 が指定されている場合は、空文字列 "" を返します。
readpartial はブロックを最小限に抑えることによって、 パイプ、ソケット、端末などのストリームに対して適切に動作するよう設計されています。 readpartial がブロックするのは次の全ての条件が満たされたときだけです。
これらの条件が満たされる場合、何らかのデータが到着するか EOF になるまで readpartial はブロックします。
readpartial の結果は以下のようになります。
例えば、パイプに対しては次のように動作します。
r, w = IO.pipe # buffer pipe content w << "abc" # "" "abc". r.readpartial(4096) #=> "abc" "" "" r.readpartial(4096) # バッファにもパイプにもデータがないのでブロックする r, w = IO.pipe # buffer pipe content w << "abc" # "" "abc" w.close # "" "abc" EOF r.readpartial(4096) #=> "abc" "" EOF r.readpartial(4096) # 例外 EOFError 発生 r, w = IO.pipe # buffer pipe content w << "abc\ndef\n" # "" "abc\ndef\n" r.gets #=> "abc\n" "def\n" "" w << "ghi\n" # "def\n" "ghi\n" r.readpartial(4096) #=> "def\n" "" "ghi\n" r.readpartial(4096) #=> "ghi\n" "" ""
なお、readpartial は nonblock フラグに影響されません。 つまり、nonblock フラグが設定されていて sysread であれば Errno::EAGAIN になる場合でもブロックします。
また、readpartial の挙動は sysread によく似ています。 とくに、バッファが空の場合には同じ挙動を示します。 ただし、EAGAIN および EINTR エラーは内部で発生したとしても通知されず、データが到着するまでブロックし続けます。
reopen(io) -> self[permalink][rdoc]自身を指定された io に繋ぎ換えます。
クラスも io に等しくなることに注意してください。 IO#pos, IO#lineno などは指定された io と等しくなります。
reopen(path) -> self[permalink][rdoc]reopen(path, mode) -> selfpath で指定されたファイルにストリームを繋ぎ換えます。
第二引数を省略したとき self のモードをそのまま引き継ぎます。 IO#pos, IO#lineno などはリセットされます。
[SEE_ALSO] Kernel.#open
rewind -> 0[permalink][rdoc]ファイルポインタを先頭に移動します。IO#lineno は 0 になります。
f = File.new("testfile")
f.readline #=> "This is line one\n"
f.rewind #=> 0
f.lineno #=> 0
f.readline #=> "This is line one\n"
seek(offset, whence = IO::SEEK_SET) -> 0[permalink][rdoc]ファイルポインタを whence の位置から offset だけ移動させます。 offset 位置への移動が成功すれば 0 を返します。
f = File.new("testfile")
f.seek(-13, IO::SEEK_END) #=> 0
f.readline #=> "And so on...\n"
[SEE_ALSO] IO#sysseek
set_encoding(enc_str, opt={}) -> self[permalink][rdoc]set_encoding(ext_enc) -> selfset_encoding(ext_enc, int_enc, opt={}) -> selfIO のエンコーディングを設定します。
引数が "A:B" のようにコロンで区切られた文字列の場合は、 A を外部エンコーディング、 B を内部エンコーディングに指定します。
引数が一つで、上のような形式でない場合には、 それが外部エンコーディングと見なされます。
引数が2つの場合はそのそれぞれを外部エンコーディング、内部エンコーディング に設定します。
opt のハッシュで外部エンコーディングを内部エンコーディングに変換する際の オプションを指定します。 詳しくは String#encode を参照してください。
例:
io = File.open(file)
io.set_encoding("ASCII-8BIT", "EUC-JP")
stat -> File::Stat[permalink][rdoc]ファイルのステータスを含む File::Stat オブジェクトを生成して 返します。
[SEE_ALSO] File#lstat, File.stat, File.lstat
sync -> bool[permalink][rdoc]現在の出力が同期モードならば true を返します。そうでない場合は false を返します。
sync=(newstate)[permalink][rdoc]自身を同期モードに設定すると、出力関数の呼出毎にバッファがフラッシュされます。
sysread(maxlen, outbuf = "") -> String[permalink][rdoc]read(2) を用いて入力を行ない、入力されたデータを 含む文字列を返します。stdio を経由しないので gets や getc や eof? などと混用すると思わぬ動作 をすることがあります。
バイナリ読み込みメソッドとして動作します。 既に EOF に達していれば EOFError が発生します。ただし、maxlen に 0 が指定されている場合は、空文字列 "" を返します。
第二引数を指定した sysread の呼び出しでデータが空であった場 合(sysread が例外 EOFError を発生させる場合)、 outbuf は空文字列になります。
outbuf = "x" * 20;
io = File.open("/dev/null")
p((io.sysread(10,outbuf) rescue nil))
p outbuf
=> nil
""
sysseek(offset, whence = IO::SEEK_SET) -> Integer[permalink][rdoc]lseek(2) と同じです。IO#seek では、 IO#sysread, IO#syswrite と併用すると正しく動作しないので代わりにこのメソッドを使います。 位置 offset への移動が成功すれば移動した位置(ファイル先頭からのオフセット)を返します。
書き込み用にバッファリングされた IO に対して実行すると警告が出ます。
File.open("/dev/zero") {|f|
buf = f.read(3)
f.sysseek(0)
}
# => -:3:in `sysseek': sysseek for buffered IO (IOError)
File.open("/dev/null", "w") {|f|
f.print "foo"
f.sysseek(0)
}
# => -:3: warning: sysseek for buffered IO
[SEE_ALSO] IO#seek
syswrite(string) -> Integer[permalink][rdoc]write(2) を用いて string を出力します。 string が文字列でなければ to_s による文字列化を試みます。 実際に出力できたバイト数を返します。
stdio を経由しないので他の出力メソッドと混用すると思わぬ動作 をすることがあります。
to_io -> self[permalink][rdoc]self を返します。
ungetbyte(c) -> nil[permalink][rdoc]指定したバイト列を書き戻します。
2バイト以上の書き戻しは仕様として保証しません。
このメソッドはバッファを経由しない読み出し(IO#sysread など) には影響しません。
例:
f = File.new("testfile") #=> #<File:testfile>
b = f.getbyte #=> 0x38
f.ungetbyte(b) #=> nil
f.getbyte #=> 0x38
ungetc(char) -> nil[permalink][rdoc]指定された char を読み戻します。
write(str) -> Integer[permalink][rdoc]IOポートに対して str を出力します。str が文字列でなけ れば to_s による文字列化を試みます。 実際に出力できたバイト数を返します。
IO#syswrite を除く全ての出力メソッドは、最終的に "write" という名のメソッドを呼び出すので、このメソッドを置き換える ことで出力関数の挙動を変更することができます。
write_nonblock(string) -> Integer[permalink][rdoc]IO をノンブロッキングモードに設定し、string を write(2) システムコールで書き出します。
write(2) が成功した場合、書き込んだ長さを返します。 EAGAIN, EINTR などは例外 Errno::EXXX として呼出元に報告されます。 書き込んだバイト数(つまり返り値)は String#bytesize の 値より小さい可能性があります。
発生した例外 がErrno::EAGAIN、 Errno::EWOULDBLOCK である場合は、 その例外オブジェクトに IO::WaitWritable が Object#extend されます。よって IO::WaitWritable を write_nonblock のリトライが必要 かの判定に用いることができます。
SEEK_CUR -> Fixnum[permalink][rdoc]IO#seek を参照してください。
SEEK_END -> Fixnum[permalink][rdoc]IO#seek を参照してください。
SEEK_SET -> Fixnum[permalink][rdoc]IO#seek を参照してください。