[MAIN][INDEX][KEYWORD][METHOD(NC)] [TOP][UP][<-PREV][NEXT->]

IO

IO クラスは基本的な入出力機能を実装します。

Traps: IO ポートのオープンに関わる問題

クラスメソッド:

IO.new(fd[, mode])

IO.for_fd(fd[, mode]) ((<ruby 1.7 feature>))

オープン済みのファイルディスクリプタ fd に対する新しい IO オブジェクトを生成して返します。IO オブジェクトの生成に失敗した場合は例外 Errno::EXXX が発生します。

mode には、File.open と同じ形式で IO のモードを指定します(ただし、文字列形式のみ)。 mode のデフォルト値は "r" です。

IO.foreach(path[, rs]) {|line| ... }

path で指定されたファイルの各行に対して繰り返します (open と同様 path の先頭が "|" ならば、コマンドの出力を読み取ります)。ちょうど以下のような働きをします。

port = open(path)
begin
  port.each_line {|line|
     ...
  }
ensure
  port.close
end

path のオープンに成功すれば nil を返します。失敗した場合は例外 Errno::EXXX が発生します。

行の区切りは引数 rs で指定した文字列になります。rs のデフォルト値はシステム変数 $/ の値です。

rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします (パラグラフモード)。

IO.pipe

pipe(2) を実行して、相互につながった2つの IO オブジェクトを要素とする配列を返します。IO オブジェクトの作成に失敗した場合は例外 Errno::EXXX が発生します。

返り値の配列は最初の要素が読み込み側で、次の要素が書き込み側です。

p pipe = IO.pipe    # => [#<IO:0x401b90f8>, #<IO:0x401b7718>]
pipe[1].puts "foo"
p pipe[0].gets      # => "foo\n"

IO.popen(command [, mode])

IO.popen(command [, mode]) {|io| ... }

command をサブプロセスとして実行し、そのプロセスの標準入出力との間にパイプラインを確立します。mode はオープンする IO ポートのモードを指定します(mode の詳細は open 参照)。省略されたときのデフォルトは "r" です。

生成したパイプ(IO オブジェクト)を返します。

p io = IO.popen("cat", "r+")  # => #<IO:0x401b75c8>
io.puts "foo"
p io.gets  # => "foo\n"

ブロックが与えられた場合は生成した IO オブジェクトを引数にブロックを実行し、その結果を返します。ブロックの実行後、生成したパイプは自動的にクローズされます。

p IO.popen("cat", "r+") {|io|
  io.puts "foo"
  io.gets
}
# => "foo\n"

コマンド名が "-" の時、Ruby は fork(2) を行い子プロセスの標準入出力との間にパイプラインを確立します。このときの戻りは、親プロセスは IO オブジェクトを返し、子プロセスは nil を返します。ブロックがあれば、親プロセスは生成した IO オブジェクトを引数にブロックを実行しその結果を返します。 (パイプはクローズされます) 子プロセスは nil を引数にブロックを実行し終了します。

# ブロックなしの例

io = IO.popen("-", "r+")
if io.nil?
  # child
  s = gets
  print "child output: " + s
  exit
end

# parent
io.puts "foo"
p io.gets                   # => "child output: foo\n"
io.close

# ブロックありの例

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"

パイプ、あるいは子プロセスの生成に失敗した場合は例外 Errno::EXXX が発生します。

IO.read(path,[length,[offset]]) ((<ruby 1.7 feature>))

path で指定されたファイルを offset 位置から length バイト分読み込んで返します。ちょうど以下のような働きをします。

port = open(path)
port.pos = offset if offset
begin
  port.read length
ensure
  port.close
end

length が nil であるか省略した場合には、EOF まで読み込みます。

IO が既に EOF に達していれば nil を返します。

path のオープン、offset 位置への設定、ファイルの読み込みに失敗した場合は例外 Errno::EXXX が発生します。 length が負の場合、例外 ArgumentError が発生します。

IO.readlines(path[, rs])

path で指定されたファイルを全て読み込んで、その各行を要素としてもつ配列を返します。 IO が既に EOF に達していれば空配列 [] を返します。

ちょうど以下のような働きをします。

port = open(path)
begin
  port.readlines
ensure
  port.close
end

行の区切りは引数 rs で指定した文字列になります。rs のデフォルト値はシステム変数 $/ の値です。

rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします (パラグラフモード)。

path のオープン、ファイルの読み込みに失敗した場合は例外 Errno::EXXX が発生します。

IO.select(reads[, writes[, excepts[, timeout]]])

select(2) を実行します。 reads/writes/exceptsには、入力待ちする IO (またはそのサブクラス)のインスタンスの配列を渡します。

timeout は整数、Float または nil(省略時のデフォルト値)を指定します。nil を指定した時には IO がレディ状態になるまで待ち続けます。

戻り値は、timeout した時には nil を、そうでないときは 3 要素の配列を返し、その各要素が入力/出力/例外待ちのオブジェクトの配列です(指定した配列のサブセット)。

select と同じです。

IO.sysopen(path[, mode [, perm]]) ((<ruby 1.7 feature>))

pathで指定されるファイルをオープンし、ファイル記述子を返します。ファイルのオープンに失敗した場合は例外 Errno::EXXX が発生します。

引数 mode, perm については組込み関数 open と同じです。

IO.for_fd などで IO オブジェクトにしない限り、このメソッドでオープンしたファイルをクローズする手段はありません。^*1

メソッド:

self << object

object を出力します。object が文字列でない時にはメソッド to_s を用いて文字列に変換します。self を戻り値とするので、以下のような << の連鎖を使うことができます。

$stdout << 1 << " is a " << Fixnum << "\n"

出力に失敗した場合は例外 Errno::EXXX が発生します。

binmode

ストリームをバイナリモードにします。MSDOS などバイナリモードの存在する OS でのみ有効です(そうでない場合このメソッドは何もしません)。バイナリモードから通常のモードに戻す方法は再オープンしかありません。

self を返します。

clone

dup

レシーバと同じ IO を参照する新しい IO オブジェクトを返します。 (参照しているファイル記述子は dup(2) されます) clone の際に self は一旦 flush されます。

フリーズした IO の clone は同様にフリーズされた IO を返しますが、 dup は内容の等しいフリーズされていない IO を返します。

close

入出力ポートをクローズします。以後のこのポートに対する入出力操作は例外を発生します。ガーベージコレクトの際にはクローズされていないIOポートはクローズされます。 Traps:closeをGCにまかせる

self がパイプでプロセスにつながっていれば、そのプロセスの終了を待ち合わせます。

nil を返します。

close_read

読み込み用の IO を close します。主にパイプや読み書き両用に作成した IO オブジェクトで使用します。

self が読み込み用にオープンされていなければ、例外 IOError が発生します。

nil を返します。

close_write

書き込み用の IO を close します。

self が書き込み用にオープンされていなければ、例外 IOError が発生します。

nil を返します。

closed?

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

each([rs]) {|line| ... }

each_line([rs]) {|line| ... }

IO ポートから 1 行ずつ読み込んで繰り返すイテレータ。IO ポートはリードモードでオープンされている必要があります(open参照)。

行の区切りは引数 rs で指定した文字列になります。rs のデフォルト値はシステム変数 $/ の値です。

rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします (パラグラフモード)。

self を返します。

each_byte {|ch| ... }

IO ポートから 1 バイトずつ読み込みます。IO ポートはリードモードでオープンされている必要があります(open参照)。

self を返します。

eof

eof?

ストリームがファイルの終端に達した場合真を返します。

fcntl(cmd[, arg])

IOに対してシステムコール fcntl を実行します。機能の詳細はfcntl(2)を参照してください。

arg が整数の時にはその値を、true または false の場合はそれぞれ 1 または 0 を、文字列の場合には pack した構造体だとみなしてそのまま fcntl(2) に渡します。arg の省略時の値は 0 です。

cmd に対して指定できる値は、添付ライブラリ fcntl.so の Fcntl モジュールが提供しています。

fcntl(2) が返した数値を返します。fcntl(2) の実行に失敗した場合は例外 Errno::EXXX が発生します。

fsync ((<ruby 1.7 feature>))

書き込み用の IO に対して、システムコールfsync(2) を実行します。flushを行ったあと(OSレベルで)まだディスクに書き込まれていないメモリ上にあるデータをディスクに書き出します。

成功すれば 0 を返します。失敗した場合は例外 Errno::EXXX が発生します。self が書き込み用でなければ例外 IOError が発生します。

fileno

to_i

ファイル記述子の番号を返します。

flush

IO ポートの内部バッファをフラッシュします。 self が書き込み用でなければ例外 IOError が発生します。

self を返します。

getc

IO ポートから 1 文字読み込んで、その文字に対応する Fixnum を返します。EOF に到達した時には nil を返します。

gets([rs])

一行読み込んで、読み込みに成功した時にはその文字列を返します。ファイルの終りに到達した時には nil を返します。 IO#each と同じように動作しますが、こちらは 1 行返すだけで繰り返しません。

行の区切りは引数 rs で指定した文字列になります。rs のデフォルト値はシステム変数 $/ の値です。

rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします (パラグラフモード)。

IO#gets はgets 同様、読み込んだ文字列を変数 $_ にセットします。

ioctl(cmd[, arg])

IO に対してシステムコール ioctl を実行します。機能の詳細はioctl(2)を参照してください。

argが整数の時にはその値を、文字列の場合にはpackした構造体だとみなしてioctl(2)に渡します。argの省略時の値は0です。

isatty

tty?

入出力ポートがttyに結合している時、真を返します。

lineno

現在の行番号を返します。

lineno=number

行番号をセットします。

pid

IO.popen で作られたIOポートなら、子プロセスのプロセス ID を返します。それ以外は nil を返します。

pos

tell

ファイルポインタの現在の位置を返します。

pos = n

ファイルポインタを指定位置に移動します。 io.seek(pos, IO::SEEK_SET)と同じです。

print([arg[, ...]])

引数を IO ポートに順に出力します。引数を省略した場合は、 $_ を出力します。引数の扱いは print と同じです(詳細はこちらを参照してください)。

nil を返します。

printf(format[, arg[, ...]])

C 言語の printf と同じように、format に従い引数を文字列に変換して、self に出力します。

第一引数に IO を指定できないこと、引数を省略できないことを除けば printf と同じです。引数の扱いの詳細については sprintfフォーマットを参照してください。

nil を返します。

putc(ch)

文字 ch を self に出力します。引数の扱いは putc と同じです(詳細はこちらを参照してください)。

ch を返します。

puts([obj[, ...]])

各 obj を self に出力した後、改行します。引数の扱いは puts と同じです(詳細はこちらを参照してください)。

nil を返します。

read([length])

length バイト読み込んで、その文字列を返します。 length が省略された時には、EOF までの全てのデータを読み込みます。

IO が既に EOF に達していれば nil を返します。

データの読み込みに失敗した場合は例外 Errno::EXXX が発生します。length が負の場合、例外 ArgumentError が発生します。

readchar

IO#getc と同様に 1 文字読み込んで、その文字に対応する Fixnum を返しますが、EOF に到達した時に例外 EOFError を発生させます。

readline([rs])

IO#gets と同様に 1 行読み込みその文字列を返しますが、 EOF に到達した時に例外 EOFError を発生させます。

行の区切りは引数 rs で指定した文字列になります。rs のデフォルト値はシステム変数 $/ の値です。

rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします (パラグラフモード)。

readline は gets 同様読み込んだ文字列を変数 $_ にセットします。

readlines([rs])

データを全て読み込んで、その各行を要素としてもつ配列を返します。 IO が既に EOF に達していれば空配列 [] を返します。

行の区切りは引数 rs で指定した文字列になります。rs のデフォルト値はシステム変数 $/ の値です。

rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします (パラグラフモード)。

reopen(io)

reopen(name[, mode])

自身を io に繋ぎ換えます。クラスも io に等しくなります (注意)。

第 1 引数が文字列の時、name で指定されたファイルにストリームを繋ぎ換えます。

self を返します。

rewind

ファイルポインタを先頭に移動します。IO#lineno は 0 になります。

seek(offset[, whence])

ファイルポインタを offset だけ移動させます。whence の値が IO::SEEK_SET の時にはファイルの先頭から、 IO::SEEK_CUR の時には現在のファイルポインタから、 IO::SEEK_END の時にはEOFから offset バイトだけ移動します。whence の省略値は IO::SEEK_SET です。

offset 位置への移動が成功すれば 0 を返します。失敗した場合は例外 Errno::EXXX が発生します。

stat