module OpenSSL::Buffering (Ruby 2.6.0 リファレンスマニュアル)

要約

OpenSSL::SSL::SSLSocket にバッファリング付きIO機能を提供するモジュールです。

IO クラスと同様のメソッドを提供しています。

内部的には sysread, syswrite, sysread_nonblock, syswrite_nonblock, sysclose といった OpenSSL::SSL::SSLSocket が提供するメソッドを利用し、 OpenSSL::SSL::SSLSocket がラップしているソケットをバッファ経由でデータを暗号化してやりとりを行います。

IO との違い

このクラスは IO クラスと同様のメソッドを提供していますが、以下の点で異なります。これらは今後のバージョンで変更(改善) される可能性があります。

gets や readlines など行読み込みメソッドの引数(行区切り文字列の指定) の意味が異なります。例えば "" で連続改行を区切りとみなすモードはなく nil を渡すとエラーとなります
read_nonblock が書き込み不可能で例外を発生させたり、 write_nonblock が読み込み不可能で例外を発生させたりします。これは暗号化通信でのデータの送信には双方向のメッセージのやりとりが必要な場合があるためです。
1.9 では encoding 関連を設定しません
1.9 で each_byte が String をブロックに渡します

インスタンスメソッド

self << s -> self[permalink][rdoc][edit]

文字列 s を書き込みます。

IO#<< と同様です。

[PARAM] s:: 出力する文字列

close -> nil[permalink][rdoc][edit]

接続を閉じます。

OpenSSL::Buffering#flush を呼んでから閉じます。

each(eol=$/) {|line| ... } -> ()[permalink][rdoc][edit]

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

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

IO#each と同様ですが、区切り文字列に "" を渡した場合や、nil を渡したときの意味が異なり、これらの場合は正しく動作しません。

[PARAM] eol:: 行区切り文字列/正規表現

each_byte {|ch| ... } -> ()[permalink][rdoc][edit]

現在の読み込み位置から 1 バイトずつ読み込み、それを文字列としてブロックの引数として呼び出します。

IO#each_byte と同様です。

eof? -> bool[permalink][rdoc][edit]

eof -> bool

相手からの通信が終端に達したら true を返します。

IO#eof? と同様です。

flush -> ()[permalink][rdoc][edit]

内部バッファに残っているデータをすべて出力し、バッファをフラッシュします。

IO#flush と同様です。

バッファがすべて出力されるまでブロックします。

getc -> String | nil[permalink][rdoc][edit]

バッファから1文字読み込み、それ返します。

読み込みが終端に到達した場合は nil を返します。

IO#getc と同様です。

gets(eol=$/, limit=nil) -> String | nil[permalink][rdoc][edit]

通信路から一行読み込んで、それを返します。

行区切りは eol で指定した文字列/正規表現になります。

最大 limit バイトの文字列を返します。1 行がそれより長い場合はそこで切られます。limit が nil の場合は eol に到達するまで読み込みます。

読み込みが終端に到達した場合は nil を返します。

IO#gets と同様ですが、区切り文字列に "" を渡した場合や、nil を渡したときの意味が異なり、これらの場合は正しく動作しません。

[PARAM] eol:: 行区切り文字列/正規表現
[PARAM] limit:: 最大の読み込みバイト数

print(*args) -> nil[permalink][rdoc][edit]

args を順に出力します。

args の各要素を to_s で文字列に変換して出力します。 IO#print とほぼ同様ですが、引数を省略した場合に $_ を出力する機能はありません。

[PARAM] args:: 出力するオブジェクト

printf(format, *args) -> nil[permalink][rdoc][edit]

format に従い引数 args を文字列に変換して出力します。

IO#printf と同様です。

[PARAM] format:: 出力フォーマット文字列
[PARAM] arg:: 出力するオブジェクト

[SEE_ALSO] Kernel.#printf

puts(*objs) -> nil[permalink][rdoc][edit]

各オブジェクトを出力し、それぞれの後に改行を出力します。

IO#puts と同様です。

[PARAM] objs:: 出力したいオブジェクト

read(length=nil, buf=nil) -> String | nil[permalink][rdoc][edit]

文字列を通信路から読み込み、返します。

読み込みが終端に到達している場合は nil を返します。

length で読み込むバイト数を指定します。 length に 0 を渡した場合は空文字列を返します。 length に nil を渡した場合(省略した場合)は最後までのデータを読み込みます。

bufに文字列を渡した場合はその領域が出力用のバッファとして利用されます。

IO#read と同様です。

[PARAM] length:: 読み込むバイト数
[PARAM] buf:: 読み込みバッファ

read_nonblock(maxlen, buf) -> String[permalink][rdoc][edit]

通信路から maxlen バイトを上限としてデータを読み込み、文字列として返します。

即座に得られるデータが 1byte でも存在すればブロックしません。内部バッファが空でない場合はバッファのデータを返します。即座に得られるデータが存在しないときには例外が発生します。例外が発生した場合、内部のソケットが利用可能になってから再びこのメソッドを呼んでください。

基本的には IO#read_nonblock と同様です。しかし以下のような違いもあります。

このメソッドはソケットが書き込み不可能(IO::WaitWritable)という理由で例外を発生させる可能性があります。暗号プロトコルの関係上データの読み込みになんらかのデータの送受信が必要になる場合があるからです。

内部のソケットが読み込み/書き込み可能である場合でも、このメソッドが文字列を得られず、例外が発生する場合があります。というのは、暗号プロトコルによっては(とくにブロック暗号では) 通信データをある程度の大きさのブロック単位で暗号化/復号化するためです。

[PARAM] maxlen:: 読み込む長さの上限(整数)
[PARAM] buf:: 読み込みバッファ
[EXCEPTION] EOFError:: 読み込みが既に終端に到達している場合に発生します
[EXCEPTION] OpenSSL::SSL::SSLError:: ソケットが読み込み/書き込み可能状態になるのを待つ必要がある場合に発生します。読み込み可能状態を待つ必要がある場合には IO::WaitReadable を、書き込み可能状態を待つ必要がある場合には IO::WaitWritable を、それぞれ extend した例外オブジェクトが生成されます。

readchar -> String[permalink][rdoc][edit]

バッファから1文字読み込み、それ返します。

読み込みが終端に到達している場合は例外 EOFError を返します。

IO#readchar と同様です。

[EXCEPTION] EOFError:: 読み込みが終端に到達した場合に発生します。

readline(eol=$/) -> String[permalink][rdoc][edit]

通信路から一行読み込んで、それを返します。

行区切りは eol で指定した文字列/正規表現になります。

読み込みが終端に到達した場合は例外 EOFError を発生します。

IO#readline と同様ですが、区切り文字列に "" を渡した場合や、nil を渡したときの意味が異なり、これらの場合は正しく動作しません。

[PARAM] eol:: 行区切り文字列/正規表現
[EXCEPTION] EOFError:: 読み込みが終端に到達した場合に発生します。

readlines(eol=$/) -> [String][permalink][rdoc][edit]

データを通信路から末端まで全て読み込んで、各行を要素として持つ配列を返します。

行区切りは eol で指定した文字列/正規表現になります。

IO#readlines と同様ですが、区切り文字列に "" を渡した場合や、nil を渡したときの意味が異なり、これらの場合は正しく動作しません。

[PARAM] eol:: 行区切り文字列/正規表現

readpartial(maxlen, buf=nil) -> String | nil[permalink][rdoc][edit]

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

IO#readpartial と同様です。

[PARAM] maxlen:: 読み込む長さの上限(整数)
[PARAM] buf:: 読み込みバッファ
[EXCEPTION] EOFError:: 読み込みが既に終端に到達している場合に発生します

sync -> bool[permalink][rdoc][edit]

出力が同期モードなら true を返します。

[SEE_ALSO] OpenSSL::Buffering#sync=

sync=(sync)[permalink][rdoc][edit]

出力の同期モードを設定します。

true に設定すると同期モードになり、 OpenSSL::Buffering#write_nonblock と OpenSSL::SSL::SSLSocket#syswrite を除くすべての書き込み (OpenSSL::Buffering#write, OpenSSL::Buffering#print など) はバッファリングされずに出力されます。

false に設定すると書き込みはバッファリングされます。

[PARAM] sync:: 設定するモード(真偽値)

[SEE_ALSO] OpenSSL::Buffering#sync

ungetc(char) -> ()[permalink][rdoc][edit]

指定した文字 char をバッファに読み戻します。

char には String か Integer を渡します。

IO#ungetc と同様です。

[PARAM] char:: 読み戻す文字

write(str) -> Integer[permalink][rdoc][edit]

str を出力します。

書き込んだデータの長さを返します。

IO#write と同様です。

[PARAM] str:: 出力する文字列

write_nonblock(s) -> Integer[permalink][rdoc][edit]

文字列 s をノンブロッキングモードで書き込みます。

成功した場合、書き込んだバイト数を返します。

1 バイトも書くことができず、ソケットの状態が変化するのを待つ必要がある場合は例外を発生させます。例外が発生した場合、内部のソケットが利用可能になってから再びこのメソッドを呼んでください。

ただし内部バッファに書き込んでいないデータが残っている場合は、まずバッファの内容をすべて出力してします。この時点でブロックする可能性があります。

基本的には IO#write_nonblock と同様です。しかし以下のような違いもあります。

このメソッドはソケットが読み込み不可能(IO::WaitReadable) という理由で例外を発生させる可能性があります。暗号プロトコルの関係上データの書き込みになんらかのデータの送受信が必要になる場合があるからです。

内部のソケットが読み込み/書き込み可能である場合でも、このメソッドで文字列を書き込めず、例外が発生する場合があります。というのは、暗号プロトコルによっては(とくにブロック暗号では) 通信データをある程度の大きさのブロック単位で暗号化/復号化するためです。

[PARAM] s:: 出力する文字列
[EXCEPTION] OpenSSL::SSL::SSLError:: ソケットが読み込み/書き込み可能状態になるのを待つ必要がある場合に発生します。読み込み可能状態を待つ必要がある場合には IO::WaitReadable を、書き込み可能状態を待つ必要がある場合には IO::WaitWritable を、それぞれ extend した例外オブジェクトが生成されます。

定数

BLOCK_SIZE -> Integer[permalink][rdoc][edit]: 内部のバッファのサイズを返します。

要約

IO との違い

目次

インスタンスメソッド

定数