Ruby 1.8.7 リファレンスマニュアル > ライブラリ一覧 > socketライブラリ > BasicSocketクラス

class BasicSocket + IO

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

要約

ソケットを表す抽象クラスです。具体的なソケット操作はサブクラスで 定義されます。

例えばインターネットドメインストリームソケットの場合は TCPSocket を用います。

do_not_reverse_lookup -> bool

この値が真ならアドレスからホスト名への逆引きを行わなくなります。

この設定は大域的に作用します。

デフォルトは false です。

以下のメソッドの動作に影響します。

• BasicSocket#recv
• IPSocket#recvfrom
• UNIXSocket#recvfrom
• Socket#recvfrom
• IPSocket#addr
• IPSocket#peeraddr
• Socket.getaddrinfo

do_not_reverse_lookup=(bool)

BasicSocket#do_not_reverse_lookup の値を変更します。

[PARAM] bool:

この値が真ならアドレスからホスト名への逆引きを行わなくなります。

例:

require 'socket'

p TCPSocket.new('localhost', 'telnet').addr
TCPSocket.do_not_reverse_lookup = true
p TCPSocket.new('localhost', 'telnet').addr

=> ["AF_INET", 2253, "localhost", "127.0.0.1"]
   ["AF_INET", 2254, "127.0.0.1", "127.0.0.1"]

for_fd(fd) -> BasicSocket

ファイルディスクリプタ fd に対する新しいソケットを生成します。

返り値のクラスはどのクラスの for_fd を呼びだしたかによって決まります。

BasicSocket.for_fd(fd) # BasicSocket のインスタンスを返す
TCPSocket.for_fd(fd) # TCPSocket のインスタンスを返す

[PARAM] fd:

ファイルディスクリプタ を指定します。

[RETURN]

任意のソケットである fd から対応するソケットクラスのインスタンスを作り、それを返します。

new(fd, mode = "r") -> IO

for_fd(fd, mode = "r") -> IO

open(fd, mode = "r") -> IO

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

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

IO.open にブロックが与えられた場合、IO オブジェクトを生成しそれを引数としてブロックを 実行します。ブロックの終了とともに fd はクローズされます。ブロックの結果を返します。 IO.new, IO.for_fd はブロックを受け付けません。

[PARAM] fd:

ファイルディスクリプタである整数を指定します。

[PARAM] mode:

Kernel.#open と同じ形式で IO のモードを指定します。File::Constants::RDONLY などの 定数(数値)でモードを指定できます。詳細は組み込み関数 Kernel.#open を参照 してください。 mode は省略可能で、省略時のデフォルトのモードは、 fcntl(2) で F_GETFL フラグが利用できる環境では第一引数で指定した fd のモードを引き継ぎ、 利用できない環境では "r" になります。

[EXCEPTION] Errno::EXXX:

IO オブジェクトの生成に失敗した場合に発生します。

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

foreach(path, rs = $/) -> Enumerable::Enumerator

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

ブロックが与えられなかった場合は、path で指定されたファイルの各行を繰り返す Enumerable::Enumerator オブジェクトを生成して返します。

path が空ファイルの場合、何もせずに nil を返します。 Kernel.#open と同様 path の先頭が "|" ならば、"|" に続くコマンドの出力を読み取ります。

[PARAM] path:

ファイル名を表す文字列か "|コマンド名" を指定します。

[PARAM] rs:

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

[EXCEPTION] Errno::EXXX:

path のオープンに失敗した場合、発生します。

[SEE_ALSO] $/

pipe -> [IO]

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

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

[EXCEPTION] Errno::EXXX:

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") -> IO

popen(command, mode = "r") {|io| ... } -> object

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

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

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

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

[PARAM] command:

コマンド名を文字列で指定します。

[PARAM] mode:

オープンする IO ポートのモードを指定します。mode の詳細は Kernel.#open 参照して下さい。

[EXCEPTION] Errno::EXXX:

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

popen("-", mode = "r") -> IO

popen("-", mode = "r") {|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"

[PARAM] mode:

オープンする IO ポートのモードを指定します。mode の詳細は Kernel.#open 参照して下さい。

[EXCEPTION] Errno::EXXX:

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

read(path, length = nil, offset = 0) -> String | nil

path で指定されたファイルを offset 位置から length バイト分読み込んで返します。

既に EOF に達している場合は nil を返します。ただし、length に nil か 0 が指定されている場合は、空文字列 "" を返します。例えば、IO.read(空ファイル) は "" を返します。

Kernel.#open と同様 path の先頭が "|" ならば、"|" に続くコマンドの出力を読み取ります。

[PARAM] path:

ファイル名を表す文字列か "|コマンド名" を指定します。

[PARAM] length:

読み込む長さを整数で指定します。nil であるか省略した場合には、EOF まで読み込みます。

[PARAM] offset:

読み込みを始めるオフセットを整数で指定します。

[EXCEPTION] Errno::EXXX:

path のオープン、offset 位置への設定、ファイルの読み込みに失敗した場合に発生します。

[EXCEPTION] ArgumentError:

length が負の場合に発生します。

例:

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 = $/) -> [String]

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

Kernel.#open と同様 path の先頭が "|" ならば、"|" に続くコマンドの出力を読み取ります。

[PARAM] path:

ファイル名を表す文字列か "|コマンド名" を指定します。

[PARAM] rs:

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

[EXCEPTION] Errno::EXXX:

path のオープン、ファイルの読み込みに失敗した場合に発生します。

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

select(2) を実行します。

与えられた入力/出力/例外待ちの IO オブジェクトの中から準備ができたものを それぞれ配列にして、配列の配列として返します。 タイムアウトした時には nil を返します。

Kernel.#select と同じです。

[PARAM] reads:

入力待ちする IO オブジェクトの配列を渡します。

[PARAM] writes:

出力待ちする IO オブジェクトの配列を渡します。

[PARAM] excepts:

例外待ちする IO オブジェクトの配列を渡します。

[PARAM] timeout:

タイムアウトまでの時間を表す数値または nil を指定します。数値で指定したときの単位は秒です。nil を指定した時には IO がどれかひとつレディ状態になるまで待ち続けます。

[EXCEPTION] IOError:

与えられた IO オブジェクトが閉じられていた時に発生します。

[EXCEPTION] Errno::EXXX:

select(2) に失敗した場合に発生します。

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

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

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

[PARAM] path:

ファイル名を表す文字列を指定します。

[PARAM] mode:

モードを文字列か定数の論理和で指定します。Kernel.#open と同じです。

[PARAM] perm:

open(2) の第 3 引数のように、ファイルを生成する場合の ファイルのパーミッションを整数で指定します。Kernel.#open と同じです。

[EXCEPTION] Errno::EXXX:

ファイルのオープンに失敗した場合に発生します。

[SEE_ALSO] Kernel.#open

self << object -> self

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

以下のような << の連鎖を使うことができます。

STDOUT << 1 << " is a " << Fixnum << "\n"

[PARAM] object:

出力したいオブジェクトを与えます。

[EXCEPTION] Errno::EXXX:

出力に失敗した場合に発生します。

binmode -> self

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

バイナリモードから通常のモードに戻す方法は再オープンしかありません。

[EXCEPTION] Errno::EXXX:

モードの変更に失敗した場合に発生します。

bytes -> Enumerable::Enumerator

自身を 1 バイトずつ整数としてイテレートするような Enumerable::Enumerator オブジェクトを生成して返します。

"hello".bytes.to_a        #=> [104, 101, 108, 108, 111]

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

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

each_char -> Enumerable::Enumerator

chars -> Enumerable::Enumerator

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

self は読み込み用にオープンされていなければなりません。

また、マルチバイト文字列を使用する場合は $KCODE を適切に設定してください。

ブロックを省略した場合は各文字について繰り返す Enumerable::Enumerator を返します。

[EXCEPTION] IOError:

self が読み込み用にオープンされていない場合に発生します。

f = File.new("testfile")
f.each_char {|c| print c, ' ' }   #=> #<File:testfile>

clone -> IO

dup -> IO

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

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

[EXCEPTION] IOError:

既に close されていた場合に発生します。

close -> nil

入出力ポートをクローズします。

以後このポートに対して入出力を行うと例外 IOError が発生しま す。ガーベージコレクトの際にはクローズされていない IO ポートはクロー ズされます。 self がパイプでプロセスにつながっていれば、そのプロセスの終 了を待ち合わせます。

[EXCEPTION] Errno::EXXX:

close に失敗した場合に発生します。

[EXCEPTION] IOError:

既に close されていた場合に発生します。

close_read -> nil

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

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

[EXCEPTION] Errno::EXXX:

close に失敗した場合に発生します。

close_write -> nil

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

[EXCEPTION] IOError:

自身が書き込み用にオープンされていなければ発生します。

[EXCEPTION] Errno::EXXX:

close に失敗した場合に発生します。

closed? -> bool

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

each(rs = $/) {|line| ... } -> self

each(rs = $/) -> Enumerable::Enumerator

each_line(rs = $/) {|line| ... } -> self

each_line(rs = $/) -> Enumerable::Enumerator

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

ブロックが与えられなかった場合は、自身から生成した Enumerable::Enumerator オブジェクトを返します。

[PARAM] rs:

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

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

[SEE_ALSO] $/, IO#gets

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

each_byte -> Enumerable::Enumerator

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

ブロックが与えられなかった場合は、自身から生成した Enumerable::Enumerator オブジェクトを返します。

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

eof -> bool

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 と同時に使うと正常に 動作しません。

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

fcntl(cmd, arg = 0) -> Integer

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

[PARAM] cmd:

IO に対するコマンドを、添付ライブラリ fcntl が提供している定数で指定します。

[PARAM] arg:

cmd に対する引数を整数、文字列、booleanのいずれかで指定します。 整数の時にはその値を fcntl(2) に渡します。 文字列の場合には Array#pack した構造体だとみなして渡します。 arg が nil か false の場合には 0を、true の場合には 1 を渡します。

[EXCEPTION] Errno::EXXX:

fcntl の実行に失敗した場合に発生します。

[EXCEPTION] IOError:

既に close されている場合に発生します。

fileno -> Integer

to_i -> Integer

ファイル記述子を表す整数を返します。

[EXCEPTION] IOError:

既に close されている場合に発生します。

flush -> self

IO ポートの内部バッファをフラッシュします。

[EXCEPTION] IOError:

自身が書き込み用にオープンされていなければ発生します。

[EXCEPTION] Errno::EXXX:

fflush(3) が失敗した場合に発生します。

fsync -> 0 | nil

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

成功すれば 0 を返します。 fsync(2) がサポートされていない場合は nil を返します。

[EXCEPTION] Errno::EXXX:

失敗した場合に発生します。

[EXCEPTION] IOError:

既に close されている場合に発生します。

getbyte -> Integer | nil

IO から1バイトを読み込み整数として返します。 既に EOF に達していれば nil を返します。

f = File.new("testfile")
f.getbyte   #=> 84
f.getbyte   #=> 104

getc -> Integer | nil

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

IO#readchar との違いは EOF での振る舞いのみです。

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

f = File.new("testfile")
f.getc                   #=> 84
f.getc                   #=> 104
f.read
f.getc                   #=> nil

[SEE_ALSO] IO#readchar

getpeername -> String

接続の相手先のソケットの情報を取得します。sockaddr 構造体をパッ クした文字列を返します。getpeername(2) を参照してください。

例:

serv = TCPServer.open("", 0)
c = TCPSocket.open(*Socket.unpack_sockaddr_in(serv.getsockname).reverse)
s = serv.accept
addr = c.getpeername
p addr      #=> "\002\000\267\214\177\000\000\001\000\000\000\000\000\000\000\000"
p Socket.unpack_sockaddr_in(addr)   #=> [46988, "127.0.0.1"]
p addr == s.getsockname     #=> true

gets(rs = $/) -> String | nil

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

読み込んだ文字列を変数 $_ にセットします。 IO#readline との違いは EOF での振る舞いのみです。

[PARAM] rs:

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

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

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

getsockname -> String

ソケットの情報を取得します。sockaddr 構造体をパックした 文字列を返します。getsockname(2) を参照してください。

例:

serv = TCPServer.open("", 0)
p serv.getsockname        #=> "\002\000\236C\000\000\000\000\000\000\000\000\000\000\000\000"
p Socket.unpack_sockaddr_in(serv.getsockname)     #=> [40515, "0.0.0.0"]
c = TCPSocket.open(*Socket.unpack_sockaddr_in(serv.getsockname).reverse)
s = serv.accept

getsockopt(level, optname) -> String

ソケットのオプションを取得します。getsockopt(2) を参照してください。 取得したオプションのデータをパックした文字列を 返します。

[PARAM] level:

getsockopt(2) の 第二引数のlevel

[PARAM] optname:

getsockopt(2) の 第三引数のoption_name

[SEE_ALSO] BasicSocket#setsockopt

例:

serv = TCPServer.open("", 0)
c = TCPSocket.open(*Socket.unpack_sockaddr_in(serv.getsockname).reverse)
s = serv.accept
opt = c.getsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY)
p opt #=> "\000\000\000\000"
p opt.unpack("i")[0] #=> 0   (Nagle アルゴリズム有効)

ioctl(cmd, arg = 0) -> Integer

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

[PARAM] cmd:

IO に対するコマンドを整数で指定します。どのようなコマンドが使えるかはプラットフォームに依存します。

[PARAM] arg:

cmd に対する引数を指定します。整数の時にはその値を ioctl に渡します。 文字列の場合には Array#pack した構造体だとみなして渡します。 arg が nil か false の場合には 0を、true の場合には 1 を渡します。

[EXCEPTION] IOError:

既に close されている場合に発生します。

isatty -> bool

tty? -> bool

入出力ポートがttyに結合している時、真を返します。そうでない場合 false を返します。

[EXCEPTION] IOError:

既に close されている場合に発生します。

lineno -> Integer

現在の行番号を整数で返します。実際には IO#gets が呼ばれた回数です。 改行以外のセパレータで gets が呼ばれた場合など、実際の行番号と異なる場合があります。

[EXCEPTION] IOError:

読み込み用にオープンされていなければ発生します。

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)

現在の行番号を number にセットします。 $. は次回の読み込みの時に更新されます。

[PARAM] number:

行番号を整数で指定します。

[EXCEPTION] IOError:

読み込み用にオープンされていなければ発生します。

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 = $/) -> Enumerable::Enumerator

自身を 1 行ずつイテレートするような Enumerable::Enumerator オブジェクトを生成して返します。

テキスト読み込みメソッドとして動作します。

[PARAM] rs:

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

"foo\nbar\n".lines.to_a   #=> ["foo\n", "bar\n"]
"foo\nb ar".lines.sort    #=> ["b ar", "foo\n"]

[SEE_ALSO] $/

pid -> Integer | nil

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

[EXCEPTION] IOError:

既に close されている場合に発生します。

pos -> Integer

tell -> Integer

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

[EXCEPTION] IOError:

既に close されている場合に発生します。

pos=(n)

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

[PARAM] n:

先頭からのオフセットを整数で指定します。

[EXCEPTION] IOError:

既に close されている場合に発生します。

print(*arg) -> nil

引数を IO ポートに順に出力します。引数を省略した場合は、$_ を出力します。

[PARAM] arg:

Kernel.#print と同じです。

[EXCEPTION] IOError:

自身が書き込み用にオープンされていなければ発生します。

[EXCEPTION] Errno::EXXX:

出力に失敗した場合に発生します。

printf(format, *arg) -> nil

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

第一引数に IO を指定できないこと、引数を省略できないことを除けば Kernel.#printf と同じです。

[PARAM] format:

Kernel.#printf と同じです。sprintf フォーマット を参照してください。

[PARAM] arg:

Kernel.#printf と同じです。

[EXCEPTION] IOError:

自身が書き込み用にオープンされていなければ発生します。

[EXCEPTION] Errno::EXXX:

出力に失敗した場合に発生します。

[SEE_ALSO] Kernel.#printf

putc(ch) -> object

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

[PARAM] ch:

出力したい文字を、文字列か文字コード(整数)で与えます。

[EXCEPTION] IOError:

自身が書き込み用にオープンされていなければ発生します。

[EXCEPTION] Errno::EXXX:

出力に失敗した場合に発生します。

[SEE_ALSO] Kernel.#putc

puts(*obj) -> nil

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

[PARAM] obj:

出力したいオブジェクトを指定します。Kernel.#puts と同じです。

[EXCEPTION] IOError:

自身が書き込み用にオープンされていなければ発生します。

[EXCEPTION] Errno::EXXX:

出力に失敗した場合に発生します。

$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

length バイト読み込んで、その文字列を返します。

既に EOF に達していれば nil を返します。 ただし、length に nil が指定されている場合は、空文字列 "" を返します。 例えば、open(空ファイル) {|f| f.read } は "" となります。

[PARAM] length:

読み込むサイズを整数で指定します。 nil が指定された場合、EOF までの全てのデータを読み込んで、その文字列を返します。

[PARAM] outbuf:

出力用のバッファを文字列で指定します。IO#read は読み込んだ データをその文字列オブジェクトに上書きして返します。指定し た文字列オブジェクトがあらかじめ length 長の領域であれば、 余計なメモリの割当てが行われません。指定した文字列の長さが length と異なる場合、その文字列は一旦 length 長に拡張(ある いは縮小)されたあと、実際に読み込んだデータのサイズになります。

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

[EXCEPTION] Errno::EXXX:

データの読み込みに失敗した場合に発生します。

[EXCEPTION] ArgumentError:

length が負の場合に発生します。

第二引数を指定した read の呼び出しでデータが空であった場合 (read が nil を返す場合)、outbuf は空文字列になります。

outbuf = "x" * 20;
io = File.open("/dev/null")
p io.read(10,outbuf)
p outbuf
=> nil
   ""

read_nonblock(maxlen, outbuf = "") -> String

IO をノンブロッキングモードに設定し、 その後で read(2) システムコールにより 長さ maxlen を上限として読み込み、文字列として返します。 EAGAIN, EINTR などは Errno::EXXX 例外として呼出元に報告されます。

なお、バッファが空でない場合は、read_nonblock はバッファから読み込みます。この場合、read(2) システムコールは呼ばれません。

このメソッドはノンブロッキングモードにする点を除いて IO#readpartial と 同じであることに注意してください。

既に EOF に達していれば EOFError が発生します。ただし、maxlen に 0 が指定されている場合は、空文字列 "" を返します。

[PARAM] maxlen:

読み込む長さの上限を整数で指定します。

[PARAM] outbuf:

文字列で指定します。IO#read_nonblock は読み込んだデータを outbuf に破壊的に格納し、 返り値は outbuf となります。outbuf は一旦 maxlen 長に拡張(あるいは縮小)されたあと、 実際に読み込んだデータのサイズになります。read(2) システムコールが 0 を返した場合は、空文字列になります。

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

[EXCEPTION] Errno::EXXX:

read(2) システムコールの結果としてエラーが起きた場合に発生します。

[EXCEPTION] EOFError:

read(2) システムコールが 0 を返した場合に発生します。これは、IO が既に EOF に達していることを意味します。

readbyte -> Integer

IO から1バイトを読み込み整数として返します。 既に EOF に達していれば EOFError が発生します。

[EXCEPTION] EOFError:

既に EOF に達している場合に発生します。

readchar -> Integer

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

IO#getc との違いは EOF での振る舞いのみです。

[EXCEPTION] EOFError:

EOF に到達した時に発生します。

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

f = File.new("testfile")
f.readchar                   #=> 84
f.readchar                   #=> 104
f.read
f.readchar                   #=> EOFError

[SEE_ALSO] IO#getc

readline(rs = $/) -> String

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

読み込んだ文字列を変数 $_ にセットします。IO#gets との違いは EOF での振る舞いのみです。

[PARAM] rs:

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

[EXCEPTION] EOFError:

EOF に到達した時に発生します。

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

f = File.new("oneline_file")
f.readline                      #=> "This is line one\n"
$_                              #=> "This is line one\n"
f.readline                      #=> EOFError
$_                              #=> nil

[SEE_ALSO] $/, IO#gets

readlines(rs = $/) -> [String]

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

[PARAM] rs:

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

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

[SEE_ALSO] $/, IO#gets

readpartial(maxlen, outbuf = "") -> String

IO から長さ maxlen を上限として読み込み、文字列として返します。 即座に得られるデータが存在しないときにはブロックしてデータの到着を待ちます。 即座に得られるデータが 1byte でも存在すればブロックしません。

既に EOF に達していれば EOFError が発生します。 ただし、maxlen に 0 が指定されている場合は、空文字列 "" を返します。

readpartial はブロックを最小限に抑えることによって、 パイプ、ソケット、端末などのストリームに対して適切に動作するよう設計されています。 readpartial がブロックするのは次の全ての条件が満たされたときだけです。

• IO オブジェクト内のバッファが空
• ストリームにデータが到着していない
• ストリームが EOF になっていない

これらの条件が満たされる場合、何らかのデータが到着するか EOF になるまで readpartial はブロックします。

readpartial の結果は以下のようになります。

1. バッファが空でなければ、そのバッファのデータを読み込んで返します。
2. ストリームにデータがあれば、ストリームからデータを読み込んで返します。
3. ストリームが EOF になっていれば、例外 EOFError を発生させます。

例えば、パイプに対しては次のように動作します。

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 エラーは内部で発生したとしても通知されず、データが到着するまでブロックし続けます。

[PARAM] maxlen:

読み込む長さの上限を整数で指定します。

[PARAM] outbuf:

文字列で指定します。IO#readpartial は読み込んだデータを outbuf に破壊的に格納し、 返り値は outbuf となります。outbuf は一旦 maxlen 長に拡張(あるいは縮小)されたあと、 実際に読み込んだデータのサイズになります。IO が既に EOF に達していれば、空文字列になります。

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

[EXCEPTION] EOFError:

IO が既に EOF に達していれば発生します。

recv(maxlen, flags = 0) -> String

ソケットからデータを受け取り、文字列として返します。 maxlen は受け取る最大の長さを指定します。 flags については recv(2) を参照してください。flags の デフォルト値は 0 です。flags の指定に必要な定数は Socket クラスで定義されています。(例: Socket::MSG_PEEK)

内部で呼び出す recv(2) が 0 を返した場合、このメソッドは "" を返します。 この意味はソケットによって異なります。 たとえば TCP では EOF を意味しますし、 UDP では空のパケットを読み込んだことを意味します。

[PARAM] maxlen:

受け取る文字列の最大の長さを指定します。

[PARAM] flags:

recv(2) を参照してください。

[EXCEPTION] IOError:

[EXCEPTION] Errno::EXXX:

recvfrom(2) がエラーになった場合などに発生します。

例:

s1, s2 = UNIXSocket.pair
s1.write "a"
s1.close
p s2.recv(10, Socket::MSG_PEEK)   #=> "a"
p s2.recv(10)                     #=> "a"
p s2.recv(10)                     #=> ""

recv_nonblock(maxlen, flags = 0) -> String

ソケットをノンブロッキングモードに設定した後、 recvfrom(2) でソケットからデータを受け取ります。

引数、返り値は BasicSocket#recv と同じです。

recvfrom(2) がエラーになった場合、 EAGAIN, EINTR を含め例外 Errno::EXXX が発生します。

[PARAM] maxlen:

受け取る文字列の最大の長さを指定します。

[PARAM] flags:

recv(2) を参照してください。

[EXCEPTION] IOError:

[EXCEPTION] Errno::EXXX:

recvfrom(2) がエラーになった場合などに発生します。

reopen(io) -> self

自身を指定された io に繋ぎ換えます。

クラスも io に等しくなることに注意してください。 IO#pos, IO#lineno などは指定された io と等しくなります。

[PARAM] io:

自身を繋ぎ換えたい IO オブジェクトを指定します。

[EXCEPTION] IOError:

指定された io が close されている場合に発生します。

reopen(path) -> self

reopen(path, mode) -> self

path で指定されたファイルにストリームを繋ぎ換えます。

第二引数を省略したとき self のモードをそのまま引き継ぎます。 IO#pos, IO#lineno などはリセットされます。

[PARAM] path:

パスを表す文字列を指定します。

[PARAM] mode:

パスを開く際のモードを文字列で指定します。

[EXCEPTION] Errno::EXXX:

失敗した場合に発生します。

[SEE_ALSO] Kernel.#open

rewind -> 0

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

[EXCEPTION] IOError:

既に close されている場合に発生します。

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

ファイルポインタを whence の位置から offset だけ移動させます。 offset 位置への移動が成功すれば 0 を返します。

[PARAM] offset:

ファイルポインタを移動させるオフセットを整数で指定します。

[PARAM] whence:

値は以下のいずれかです。

• IO::SEEK_SET: ファイルの先頭から (デフォルト)
• IO::SEEK_CUR: 現在のファイルポインタから
• IO::SEEK_END: ファイルの末尾から

[EXCEPTION] Errno::EXXX:

ファイルポインタの移動に失敗した場合に発生します。

[EXCEPTION] IOError:

既に close されていた場合に発生します。

f = File.new("testfile")
f.seek(-13, IO::SEEK_END)   #=> 0
f.readline                  #=> "And so on...\n"

[SEE_ALSO] IO#sysseek

send(mesg, flags, dest_sockaddr = nil) -> Fixnum

ソケットを介してデータを送ります。flags に関しては send(2) を参照してください。connect していないソケット に対しては送り先である dest_sockaddr を指定する必要があります。実際に送っ たデータの長さを返します。

dest_sockaddr には「ソケットアドレス構造体を pack した文字列」 を指定します。

データの送信に失敗した場合は例外 Errno::EXXX が発生します。

[PARAM] mesg:

送信するデータを文字列で指定します。

[PARAM] flags:

send(2) の flags を参照してください。

[PARAM] dest_sockaddr:

「ソケットアドレス構造体を pack した文字列」を指定します。

[EXCEPTION] Errno::EXXX:

データの送信に失敗した場合に発生します。

例:

s = UDPSocket.new
sockaddr = Socket.sockaddr_in("discard", "localhost")
s.send("The king has donkey ears!", 0, sockaddr)

setsockopt(level, optname, optval) -> 0

ソケットのオプションを設定します。setsockopt(2) を参照してください。

level, optname には Socket::SOL_SOCKET や Socket::SO_REUSEADDR といった整数値を用います。

optval には文字列、整数、真偽値(true or false)を渡すことができます。 文字列の場合には setsockopt(2) にはその文字列と 長さが渡されます。整数の場合はintへのポインタが渡されます。 true/falseの場合は0/1という整数と解釈され、そのメモリ領域の intポインタを渡します。

[PARAM] level:

setsockopt(2) の level を参照してください。

[PARAM] optname:

setsockopt(2) の option_name を参照してください。

[PARAM] optval:

設定値

[EXCEPTION] Errno::EXXX:

オプションの設定に失敗した場合発生します。

[SEE_ALSO] BasicSocket#getsockopt

shutdown(how = Socket::SHUT_RDWR) -> 0

ソケットの以降の接続を終了させます。

how の値によって以下のように接続が終了します。

• Socket::SHUT_RD: それ以降の受信が拒否されます
• Socket::SHUT_WR: それ以降の送信が拒否されます
• Socket::SHUT_RDWR: それ以降の送信、受信ともに拒否されます

how を省略すると Socket::SHUT_RDWR を指定したことになります。 shutdown(2) を参照してください。

[PARAM] how:

接続の終了の仕方を Socket::SHUT_RD, Socket::SHUT_WR, Socket::SHUT_RDWR などで指定します。

[EXCEPTION] Errno::EXXX:

ソケットの以降の接続を終了操作が失敗した場合に発生します。

[EXCEPTION] ArgumentError:

how に範囲外の整数を入力した場合に発生します。

[EXCEPTION] SecurityError:

セーフレベルが 4 以上で、ソケットに汚染マークがついていない場合発生します。

stat -> File::Stat

ファイルのステータスを含む File::Stat オブジェクトを生成して 返します。

[EXCEPTION] Errno::EXXX:

ステータスの読み込みに失敗した場合に発生します。

[EXCEPTION] IOError:

既に close されていた場合に発生します。

[SEE_ALSO] File#lstat, File.stat, File.lstat

sync -> bool

現在の出力が同期モードならば true を返します。そうでない場合は false を返します。

[EXCEPTION] IOError:

既に close されていた場合に発生します。

sync=(newstate)

自身を同期モードに設定すると、出力関数の呼出毎にバッファがフラッシュされます。

[PARAM] newstate:

自身を同期モードに設定するかを boolean で指定します。

[EXCEPTION] IOError:

既に close されていた場合に発生します。

sysread(maxlen, outbuf = "") -> String

read(2) を用いて入力を行ない、入力されたデータを 含む文字列を返します。stdio を経由しないので gets や getc や eof? などと混用すると思わぬ動作 をすることがあります。

既に EOF に達していれば EOFError が発生します。ただし、maxlen に 0 が指定されている場合は、空文字列 "" を返します。

[PARAM] maxlen:

入力のサイズを整数で指定します。

[PARAM] outbuf:

出力用のバッファを文字列で指定します。IO#sysread は読み込んだデータを その文字列オブジェクトに上書きして返します。指定した文字列オブジェクト があらかじめ maxlen 長の領域であれば、余計なメモリの割当てが行われません。 指定した文字列の長さが maxlen と異なる場合、その文字列は一旦 maxlen 長に 拡張(あるいは縮小)されたあと、実際に読み込んだデータのサイズになります。

[EXCEPTION] IOError:

自身が読み込み用にオープンされていなければ発生します。

[EXCEPTION] EOFError:

IO が既に EOF に達していれば発生します。

[EXCEPTION] Errno::EXXX:

データの読み込みに失敗した場合に発生します。

第二引数を指定した 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

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

[PARAM] offset:

ファイルポインタを移動させるオフセットを整数で指定します。

[PARAM] whence:

値は以下のいずれかです。

• IO::SEEK_SET: ファイルの先頭から (デフォルト)
• IO::SEEK_CUR: 現在のファイルポインタから
• IO::SEEK_END: ファイルの末尾から

[EXCEPTION] IOError:

読み込み用にバッファリングされた IO に対して実行すると発生します。 既に close されていた場合にも発生します。

[EXCEPTION] Errno::EXXX:

移動に失敗した場合に発生します。

[SEE_ALSO] IO#seek

syswrite(string) -> Integer

write(2) を用いて string を出力します。 string が文字列でなければ to_s による文字列化を試みます。 実際に出力できたバイト数を返します。

stdio を経由しないので他の出力メソッドと混用すると思わぬ動作 をすることがあります。

[PARAM] string:

自身に書き込みたい文字列を指定します。

[EXCEPTION] IOError:

自身が書き込み用にオープンされていなければ発生します。

[EXCEPTION] Errno::EXXX:

出力に失敗した場合に発生します。

to_io -> self

self を返します。

ungetc(char) -> nil

指定された char を読み戻します。 2バイト以上の読み戻しは保証されません。

[PARAM] char:

読み戻したい1バイト文字に対応する Fixnum を指定します。

[EXCEPTION] IOError:

読み戻しに失敗した場合に発生します。また、自身が読み込み用にオープンされていない時、 自身がまだ一度も read されていない時に発生します。

f = File.new("testfile")   #=> #<File:testfile>
c = f.getc                 #=> 84
f.ungetc(c)                #=> nil
f.getc                     #=> 84

write(str) -> Integer

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

IO#syswrite を除く全ての出力メソッドは、最終的に "write" という名のメソッドを呼び出すので、このメソッドを置き換える ことで出力関数の挙動を変更することができます。

[PARAM] str:

自身に書き込みたい文字列を指定します。

[EXCEPTION] IOError:

自身が書き込み用にオープンされていなければ発生します。

[EXCEPTION] Errno::EXXX:

出力に失敗した場合に発生します。

write_nonblock(string) -> Integer

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

write(2) が成功した場合、書き込んだ長さを返します。 EAGAIN, EINTR などは例外 Errno::EXXX として呼出元に報告されます。 書き込んだバイト数(つまり返り値)は String#bytesize の 値より小さい可能性があります。

[PARAM] string:

自身に書き込みたい文字列を指定します。

[EXCEPTION] IOError:

自身が書き込み用にオープンされていなければ発生します。

[EXCEPTION] Errno::EXXX:

write(2) が失敗した場合に発生します。

SEEK_CUR -> Fixnum

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

SEEK_END -> Fixnum

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

SEEK_SET -> Fixnum

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