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

class File + IO

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

要約

ファイルアクセスのためのクラスです。

通常 Kernel.#open または File.open を使って生成します。 IO クラスがインクルードしている File::Constants は File クラスに関係する定数を格納したモジュールです。また File::Stat は stat 構造体( stat(2) 参照)を表すクラスです。

特異メソッド

absolute_path(file_name, dir_string=nil) -> String

file_name を絶対パスに変換した文字列を返します。

相対パスの場合はカレントディレクトリを基準とします。 dir_string を渡した場合はそのディレクトリを基準とします。

File.expand_path と異なり、 file_name 先頭が "~" である場合それは展開されません。普通のディレクトリ名として処理されます。

p Dir.getwd                      #=> "/home/matz/work/bar"
p ENV["HOME"]                    #=> "/home/matz"
p File.absolute_path("..")         #=> "/home/matz/work"
p File.absolute_path("..", "/tmp") #=> "/"
p File.absolute_path("~")          #=> "/home/matz/work/bar/~"
p File.absolute_path("~foo")       #=> "/home/matz/work/bar/~foo"

[SEE_ALSO] File.expand_path

atime(filename) -> Time

最終アクセス時刻を返します。

[PARAM] filename:: ファイル名を表す文字列か IO オブジェクトを指定します。
[EXCEPTION] Errno::EXXX:: ファイルの時刻の取得に失敗した場合に発生します。

basename(filename, suffix = "") -> String

filename の一番後ろのスラッシュに続く要素を返します。もし、引数 suffix が与えられて、かつそれが filename の末尾に一致するなら、それを取り除いたものを返します。

p File.basename("ruby/ruby.c")          #=> "ruby.c"
p File.basename("ruby/ruby.c", ".c")    #=> "ruby"
p File.basename("ruby/ruby.c", ".*")    #=> "ruby"
p File.basename("ruby/ruby.exe", ".*")  #=> "ruby"
p File.basename("ruby/y.tab.c", ".*")   #=> "y.tab"

File.basename の動作は basename(3) に従います。

p File.basename("foo/bar/")      # => "bar"

[PARAM] filename:: ファイル名を表す文字列を指定します。
[PARAM] suffix:: サフィックスを文字列で与えます。'.*' という文字列を与えた場合、'*' はワイルドカードとして働き '.' を含まない任意の文字列にマッチします。

[SEE_ALSO] File.dirname, File.extname

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

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

length を省略するとファイルの末尾まで読み込みます。

ファイルを開くときの mode は "rb:ASCII-8BIT" です。

[SEE_ALSO] IO.read

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

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

offset を指定するとその位置までシークします。

offset を指定しないと、書き込みの末尾でファイルを切り捨てます。

[PARAM] path:: ファイル名文字列
[PARAM] string:: 書き込む文字列
[PARAM] offset:: 書き込み開始位置

[SEE_ALSO] IO.write

blockdev?(path) -> bool

FileTest.#blockdev? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

chardev?(path) -> bool

FileTest.#chardev? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

chmod(mode, *filename) -> Integer

ファイルのモードを mode に変更します。モードを変更したファイルの数を返します。

[PARAM] filename:: ファイル名を表す文字列を指定します。
[PARAM] mode:: chmod(2) と同様に整数で指定します。
[EXCEPTION] Errno::EXXX:: モードの変更に失敗した場合に発生します。

chown(owner, group, *filename) -> Integer

ファイルのオーナーとグループを変更します。スーパーユーザだけがファイルのオーナーとグループを変更できます。変更を行ったファイルの数を返します。

[PARAM] filename:: ファイル名を表す文字列を指定します。
[PARAM] owner:: chown(2) と同様に数値で指定します。nil または -1 を指定することで、オーナーを現在のままにすることができます。
[PARAM] group:: chown(2) と同様に数値で指定します。nil または -1 を指定することで、グループを現在のままにすることができます。
[EXCEPTION] Errno::EXXX:: 変更に失敗した場合に発生します。

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

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

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

コピー元の src が IO オブジェクトの場合は、src のオフセットからファイル名の場合はファイルの最初からコピーを開始します。コピー先の dst に関しても同様です。

dst にファイル名を指定し、そのファイルが存在しない場合、ファイルは作成されます。ファイルが存在する場合は長さ 0 に切り詰められます。

src が IO オブジェクトでかつ src_offset が指定されている場合、 src のオフセット(src.pos)は変更されません。

[PARAM] src:: コピー元となる IO オブジェクトかファイル名を指定します。
[PARAM] dst:: コピー先となる IO オブジェクトかファイル名を指定します。
[PARAM] copy_length:: コピーする長さをバイト単位で指定します。最大 copy_length までコピーされます。 nil を指定した場合、コピーする長さに制限はありません。
[PARAM] src_offset:: コピーを始めるオフセットを数値で指定します。

ctime(filename) -> Time

状態が最後に変更された時刻を返します。状態の変更とは chmod などによるものです。

[PARAM] filename:: ファイル名を表す文字列か IO オブジェクトを指定します。
[EXCEPTION] Errno::EXXX:: ファイルの時刻の取得に失敗した場合に発生します。

delete(*filename) -> Integer

unlink(*filename) -> Integer

ファイルを削除します。削除したファイルの数を返します。削除に失敗した場合は例外 Errno::EXXX が発生します。

このメソッドは通常ファイルの削除用で、ディレクトリの削除には Dir.rmdir を使います。

[PARAM] filename:: ファイル名を表す文字列を指定します。
[EXCEPTION] Errno::EXXX:: 失敗した場合に発生します。

directory?(path) -> bool

FileTest.#directory? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

dirname(filename) -> String

filename の一番後ろのスラッシュより前を文字列として返します。スラッシュを含まないファイル名に対しては "."(カレントディレクトリ)を返します。

p File.dirname("dir/file.ext")    # => "dir"
p File.dirname("file.ext")        # => "."

File.dirname の動作は dirname(3) に従います。

p File.dirname("foo/bar/")      # => "foo"
p File.dirname("foo//bar")      # => "foo"

[PARAM] filename:: ファイル名を表す文字列を指定します。

[SEE_ALSO] File.basename, File.extname

executable?(path) -> bool

FileTest.#executable? と同じです。

[PARAM] path:: パスを表す文字列を指定します。

executable_real?(path) -> bool

FileTest.#executable_real? と同じです。

[PARAM] path:: パスを表す文字列を指定します。

exist?(path) -> bool

exists?(path) -> bool

FileTest.#exist? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

expand_path(path, default_dir = '.') -> String

path を絶対パスに展開した文字列を返します。 path が相対パスであれば default_dir を基準にします。

先頭の ~ はホームディレクトリ(環境変数 HOME が使われます)に、 ~USER はそのユーザのホームディレクトリに展開されます。

p Dir.getwd                      #=> "/home/matz/work/foo"
p ENV["HOME"]                    #=> "/home/matz"
p File.expand_path("..")         #=> "/home/matz/work"
p File.expand_path("..", "/tmp") #=> "/"
p File.expand_path("~")          #=> "/home/matz"
p File.expand_path("~foo")       #=> "/home/foo"

[PARAM] path:: パスを表す文字列を指定します。
[PARAM] default_dir:: path が相対パスであれば default_dir を基準に展開されます。

extname(filename) -> String

ファイル名 filename の拡張子部分(最後の "." に続く文字列)を返します。ディレクトリ名に含まれる "." や、ファイル名先頭の "." は拡張子の一部としては見なされません。filename に拡張子が含まれない場合は空文字列を返します。

p File.extname("foo/foo.txt")     # => ".txt"
p File.extname("foo/foo.tar.gz")  # => ".gz"
p File.extname("foo/bar")         # => ""
p File.extname("foo/.bar")        # => ""
p File.extname("foo.txt/bar")     # => ""
p File.extname(".foo")            # => ""

[PARAM] filename:: ファイル名を表す文字列を指定します。

[SEE_ALSO] File.basename, File.dirname

file?(path) -> bool

FileTest.#file? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

fnmatch(pattern, path, flags = 0) -> bool

fnmatch?(pattern, path, flags = 0) -> bool

ファイル名のパターンマッチ fnmatch(3) を行います。 path が pattern にマッチすれば真を返します。そうでない場合には false を返します。

[PARAM] pattern:

パターンを文字列で指定します。ワイルドカードとして `*', `?', `[]' が使用できます。Dir.glob とは違って `{}' や `**/' は使用できません。

    %w(foo foobar bar).each {|f|
      p File.fnmatch("foo*", f)
    }
    # => true
         true
         false

[PARAM] path:

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

[PARAM] flags:

パターンマッチの動作を以下で述べる定数の論理和で指定します。 flags のデフォルト値は0(フラグ指定なし)です。

引数 flags に指定できる定数は以下のとおりです。これらの定数は File::Constants で定義されていますが、 File クラスの親クラスの IO が File::Constants をインクルードしているので、これらの定数は File::FNM_NOESCAPE などとして参照可能です。

FNM_NOESCAPE

エスケープ文字 `\' を普通の文字とみなします。

デフォルトでは \ を伴う任意の文字はその文字にマッチしますが、このフラグをつけると、\ が普通の文字として扱われます。

  p File.fnmatch('\a', 'a')                       # => true
  p File.fnmatch('\a', '\a', File::FNM_NOESCAPE)  # => true

前者で * は、エスケープされているので "*" そのものにマッチします。

  p File.fnmatch('\*', 'a')                       # => false
  p File.fnmatch('\*', '\a', File::FNM_NOESCAPE)  # => true

単体の \ は、このフラグの有無に関わらず \ にマッチします。 (シングルクォート文字列中では \\ は、\ であることに注意)

  p File.fnmatch('\\', '\\')                      # => true
  p File.fnmatch('\\', '\\', File::FNM_NOESCAPE)  # => true

FNM_PATHNAME

ワイルドカード `*', `?', `[]' が `/' にマッチしなくなります。シェルのパターンマッチにはこのフラグが使用されています。

  p File.fnmatch('*', '/', File::FNM_PATHNAME)   # => false
  p File.fnmatch('?', '/', File::FNM_PATHNAME)   # => false
  p File.fnmatch('[/]', '/', File::FNM_PATHNAME) # => false

FNM_CASEFOLD

アルファベットの大小文字を区別せずにパターンマッチを行います。

  p File.fnmatch('A', 'a', File::FNM_CASEFOLD)   # => true

FNM_DOTMATCH

ワイルドカード `*', `?', `[]' が先頭の `.' にマッチするようになります。

  p File.fnmatch('*', '.', File::FNM_DOTMATCH)           # => true
  p File.fnmatch('?', '.', File::FNM_DOTMATCH)           # => true
  p File.fnmatch('[.]', '.', File::FNM_DOTMATCH)         # => true
  p File.fnmatch('foo/*', 'foo/.', File::FNM_DOTMATCH)   # => true

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 オブジェクトを生成して返します。

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

オプション引数

このメソッドは以下のオプションを利用できます。

:mode mode引数と同じ意味です
:external_encoding 外部エンコーディング。"-" はデフォルト外部エンコーディングの別名です。
:internal_encoding 内部エンコーディング。"-" はデフォルト内部エンコーディングの別名です。nilなら変換しません。
:encoding "extenc:intenc" の形で外部/内部エンコーディングを指定します。
:textmode 真を渡すと mode の "t" と同じ意味になります。
:binmode 真を渡すと mode の "b" と同じ意味になります。
:autoclose 偽を渡すと close時/GCでのファイナライザ呼出時に fd を close しません。

また、String#encode で説明されている :invalid => :replace などの変換オプションも指定することができます。外部エンコーディングから内部エンコーディングへの変換をするときに用いられます。

[PARAM] fd:: ファイルディスクリプタである整数を指定します。
[PARAM] mode:: Kernel.#open と同じ形式で IO のモードを指定します。File::Constants::RDONLY などの定数(数値)でモードを指定できます。詳細は組み込み関数 Kernel.#open を参照してください。 mode は省略可能で、省略時のデフォルトのモードは、 fcntl(2) で F_GETFL フラグが利用できる環境では第一引数で指定した fd のモードを引き継ぎ、利用できない環境では "r" になります。
[PARAM] opt:: オプション引数
[EXCEPTION] Errno::EXXX:: IO オブジェクトの生成に失敗した場合に発生します。

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

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

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

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

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

[PARAM] path:: ファイル名を表す文字列か "|コマンド名" を指定します。
[PARAM] rs:: 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
[EXCEPTION] Errno::EXXX:: path のオープンに失敗した場合、発生します。

[SEE_ALSO] $/

ftype(filename) -> String

ファイルのタイプを表す文字列を返します。

文字列は以下のうちのいずれかです。File.lstat(filename).ftype と同じです。シンボリックリンクに対して "link" を返します。

"file"
"directory"
"characterSpecial"
"blockSpecial"
"fifo"
"link"
"socket"
"unknown"

[PARAM] filename:: ファイル名を表す文字列を指定します。
[EXCEPTION] Errno::EXXX:: 情報の取得に失敗した場合に発生します。

grpowned?(path) -> bool

FileTest.#grpowned? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

identical?(filename1, filename2) -> bool

FileTest.#identical? と同じです。

[PARAM] filename1:: パスを表す文字列か IO オブジェクトを指定します。
[PARAM] filename2:: パスを表す文字列か IO オブジェクトを指定します。

join(*item) -> String

File::SEPARATORを間に入れて文字列を連結します。

[item, item, ...].join(File::SEPARATOR)

と同じです。DOSISH 対応で環境依存になる予定です。

[PARAM] item:: 連結したいディレクトリ名やファイル名を文字列で与えます。

lchmod(mode, *filename) -> Integer

File.chmod と同様ですが、シンボリックリンクに関してリンクそのもののモードを変更します。

[PARAM] filename:: ファイル名を表す文字列を指定します。
[PARAM] mode:: chmod(2) と同様に整数で指定します。
[EXCEPTION] NotImplementedError:: lchmod(2) を実装していないシステムでこのメソッドを呼び出すと発生します。
[EXCEPTION] Errno::EXXX:: モードの変更に失敗した場合に発生します。

lchown(owner, group, *filename) -> Integer

File#chown と同様ですが、シンボリックリンクに関してリンクそのもののオーナー、グループを変更します。

[PARAM] filename:: ファイル名を表す文字列を指定します。
[PARAM] owner:: chown(2) と同様に数値で指定します。nil または -1 を指定することで、オーナーを現在のままにすることができます。
[PARAM] group:: chown(2) と同様に数値で指定します。nil または -1 を指定することで、グループを現在のままにすることができます。
[EXCEPTION] NotImplementedError:: lchown(2) を実装していないシステムでこのメソッドを呼び出すと発生します。

link(old, new) -> 0

old を指す new という名前のハードリンクを生成します。old はすでに存在している必要があります。ハードリンクに成功した場合は 0 を返します。

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

[PARAM] old:: ファイル名を表す文字列を指定します。
[PARAM] new:: ファイル名を表す文字列を指定します。
[EXCEPTION] Errno::EXXX:: 失敗した場合に発生します。

lstat(filename) -> File::Stat

File.statと同様ですが、シンボリックリンクに関してリンクそのものの情報を File::Stat として返します。lstat(2) を実装していないシステムでは、File.stat と同じです。

[PARAM] filename:: ファイル名を表す文字列を指定します。
[EXCEPTION] Errno::EXXX:: 情報の取得に失敗した場合に発生します。

[SEE_ALSO] IO#stat, File#lstat

mtime(filename) -> Time

最終更新時刻を返します。

[PARAM] filename:: ファイル名を表す文字列か IO オブジェクトを指定します。
[EXCEPTION] Errno::EXXX:: ファイルの時刻の取得に失敗した場合に発生します。

new(path, mode = "r", perm = 0666) -> File

open(path, mode = "r", perm = 0666) -> File

open(path, mode = "r", perm = 0666) {|file| ... } -> object

path で指定されるファイルをオープンし、File オブジェクトを生成して返します。

path が整数の場合はファイルディスクリプタとして扱い、それに対応する File オブジェクトを生成して返します。IO.open と同じです。ブロックを指定して呼び出した場合は、File オブジェクトを引数としてブロックを実行します。ブロックの実行が終了すると、ファイルは自動的にクローズされます。ブロックの実行結果を返します。

[PARAM] path:: ファイルを文字列で指定します。整数を指定した場合はファイルディスクリプタとして扱います。
[PARAM] mode:: モードを文字列か定数の論理和で指定します。Kernel.#open と同じです。
[PARAM] perm:: ファイルを生成する場合のファイルのパーミッションを整数で指定します。Kernel.#open と同じです。
[EXCEPTION] Errno::EXXX:: ファイルのオープンに失敗した場合に発生します。

owned?(path) -> bool

FileTest.#owned? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

path(filename) -> String

指定されたファイル名を文字列で返します。filename が文字列でない場合は、to_path メソッドを呼びます。

[PARAM] filename:: ファイル名を表す文字列か to_path メソッドが定義されたオブジェクトを指定します。

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 オブジェクトを要素とする配列を返します。

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

ブロックが渡された場合は、そのブロックに2つの IO オブジェクトが渡され、ブロックの返り値がこのメソッドの返り値となります。ブロック終了時に IO オブジェクトがもし close されていないならば close します(close されていてるオブジェクトはそのままです)。

得られる2つの IO オブジェクトのエンコーディングを引数で指定することができます。

[PARAM] enc_str:: 読み込み側の外部エンコーディングを文字列で指定します。文字列がコロンを挟んだ二つのエンコーディング名 "A:B" である場合最初のものが外部エンコーディング、次が内部エンコーディングを意味します。
[PARAM] ext_enc:: 読み込み側の外部エンコーディングを Encoding オブジェクトで指定します。
[PARAM] int_enc:: 読み込み側の内部エンコーディングを Encoding オブジェクトで指定します。
[PARAM] opt:: エンコーディングなどを設定するオプション引数(see IO.new)
[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"

pipe?(path) -> bool

FileTest.#pipe? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

popen(command, mode = "r", opt={}) -> IO

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

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

command が文字列の場合は、シェルを経由して子プロセスを実行します。 command が配列の場合は、シェルを経由せずに子プロセスを実行します。

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 参照して下さい。
[PARAM] opt:: エンコーディングなどを設定するオプション引数(see IO.new)
[EXCEPTION] Errno::EXXX:: パイプ、あるいは子プロセスの生成に失敗した場合に発生します。

popen("-", mode = "r", opt={}) -> IO

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"

[PARAM] mode:: オープンする IO ポートのモードを指定します。mode の詳細は Kernel.#open 参照して下さい。
[PARAM] opt:: エンコーディングなどを設定するオプション引数(see IO.new)
[EXCEPTION] Errno::EXXX:: パイプ、あるいは子プロセスの生成に失敗した場合に発生します。

read(path, opt = {}) -> String | nil

read(path, length = nil, opt = {}) -> String | nil

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

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

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

引数 length が指定された場合はバイナリ読み込みメソッド、そうでない場合はテキスト読み込みメソッドとして動作します。

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

[PARAM] path:: ファイル名を表す文字列か "|コマンド名" を指定します。
[PARAM] length:: 読み込む長さを整数で指定します。nil であるか省略した場合には、EOF まで読み込みます。
[PARAM] offset:: 読み込みを始めるオフセットを整数で指定します。
[PARAM] opt:: ファイル path を open する時に使われるオプションを Hash で指定します。
[EXCEPTION] Errno::EXXX:: path のオープン、offset 位置への設定、ファイルの読み込みに失敗した場合に発生します。
[EXCEPTION] ArgumentError:: length が負の場合に発生します。

引数 opt で有効なキーと値は以下のとおりです。キーはいずれも Symbol オブジェクトです。

:encoding: 読み込んだ文字列のエンコーディングを指定します。読み込む長さを指定した場合はこれは無視されます。
:mode: IO.open のモードを指定します。 "r" で始まる文字列である必要があります。
:open_args: 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

readable?(path) -> bool

FileTest.#readable? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

readable_real?(path) -> bool

FileTest.#readable_real? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

readlines(path, rs = $/, opts={})

readlines(path, limit, opts={})

readlines(path, rs, limit, opts={})

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

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

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

limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で切れないように余分に読み込む場合があります。

opts でファイルを開くときのオプションを指定します。エンコーディングなどを指定できます。 File.open と同様なのでそちらを参照してください。

[PARAM] path:: ファイル名を表す文字列か "|コマンド名" を指定します。
[PARAM] rs:: 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
[PARAM] limit:: 最大の読み込みバイト数
[PARAM] opts:: ファイルを開くときのオプション引数
[EXCEPTION] Errno::EXXX:: path のオープン、ファイルの読み込みに失敗した場合に発生します。

readlink(path) -> String

シンボリックリンクのリンク先のパスを文字列で返します。

[PARAM] path:: シンボリックリンクを表す文字列を指定します。
[EXCEPTION] Errno::EXXX:: 指定された path がシンボリックリンクでない場合や、リンクの読み取りに失敗した場合に発生します。

realdirpath(pathname, basedir = nil) -> String

与えられた pathname に対応する絶対パスを返します。

pathname の最後のコンポーネントは存在していなくても例外は発生しません。

[PARAM] pathname:: ファイル名を指定します。
[PARAM] basedir:: ベースディレクトリを指定します。省略するとカレントディレクトリを使用します。
[EXCEPTION] Errno::ENOENT:: ファイルが存在しない場合に発生します。

realpath(pathname, basedir = nil) -> String

与えられた pathname に対応する絶対パスを返します。

pathname の全てのコンポーネントは存在しなければなりません。

[PARAM] pathname:: ファイル名を指定します。
[PARAM] basedir:: ベースディレクトリを指定します。省略するとカレントディレクトリを使用します。
[EXCEPTION] Errno::ENOENT:: ファイルが存在しない場合に発生します。

rename(from, to) -> 0

ファイルの名前を変更します。ディレクトリが異なる場合には移動も行います。rename(2) を参照してください。移動先のファイルが存在する時には上書きされます。

ファイルの移動に成功した場合 0 を返します。失敗した場合は例外 Errno::EXXX が発生します。

[PARAM] from:: ファイルの名前を文字列で与えます。
[PARAM] to:: 新しいファイル名を文字列で与えます。
[EXCEPTION] Errno::EXXX:: 失敗した場合に発生します。

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
}

setgid?(path) -> bool

FileTest.#setgid? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

setuid?(path) -> bool

FileTest.#setuid? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

size(path) -> Integer

FileTest.#size と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

size?(path) -> bool

FileTest.#size? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

socket?(path) -> bool

FileTest.#socket? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

split(pathname) -> [String]

pathname を dirname とbasename に分割して、2 要素の配列を返します。

[File.dirname(pathname), File.basename(pathname)]

と同じです。

[PARAM] pathname:: パス名を表す文字列を指定します。

stat(filename) -> File::Stat

filename の情報を含む File::Stat オブジェクトを生成して返します。

[PARAM] filename:: ファイル名を表す文字列を指定します。
[EXCEPTION] Errno::EXXX:: 情報の取得に失敗した場合に発生します。

[SEE_ALSO] IO#stat, File#lstat

sticky?(path) -> bool

FileTest.#sticky? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

symlink(old, new) -> 0

old への new という名前のシンボリックリンクを生成します。

シンボリックリンクの作成に成功すれば 0 を返します。失敗した場合は例外 Errno::EXXX が発生します。

[PARAM] old:: ファイル名を表す文字列を指定します。
[PARAM] new:: シンボリックリンクを表す文字列を指定します。
[EXCEPTION] Errno::EXXX:: 失敗した場合に発生します。

symlink?(path) -> bool

FileTest.#symlink? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

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

truncate(path, length) -> 0

path で指定されたファイルのサイズを最大 length バイトにします。

サイズの変更に成功すれば 0 を返します。失敗した場合は例外 Errno::EXXX が発生します。

[PARAM] path:: パスを表す文字列を指定します。
[PARAM] length:: 変更したいサイズを整数で与えます。
[EXCEPTION] Errno::EXXX:: 失敗した場合に発生します。

try_convert(obj) -> IO | nil

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

IO.try_convert(STDOUT)     # => STDOUT
IO.try_convert("STDOUT")   # => nil

umask -> Integer

現在の umask の値を返します。

[SEE_ALSO] umask(2)

umask(umask) -> Integer

umask を変更します。変更前の umask の値を返します。

[PARAM] umask:: 設定したい umask の値を整数で指定します。

[SEE_ALSO] umask(2)

utime(atime, mtime, *filename) -> Integer

ファイルの最終アクセス時刻と更新時刻を変更します。変更したファイルの数を返します。変更に失敗した場合は例外 Errno::EXXX が発生します。

[PARAM] filename:: ファイル名を表す文字列を指定します。
[PARAM] atime:: 最終アクセス時刻を Time か、起算時からの経過秒数を数値で指定します。
[PARAM] utime:: 更新時刻を Time か、起算時からの経過秒数を数値で指定します。
[EXCEPTION] Errno::EXXX:: 変更に失敗した場合に発生します。

world_readable?(path) -> Integer | nil

path が全てのユーザから読めるならばそのファイルのパーミッションを表す整数を返します。そうでない場合は nil を返します。

整数の意味はプラットフォームに依存します。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

例:

m = File.world_readable?("/etc/passwd")
"%o" % m                               # => "644"

world_writable?(path) -> bool

path が全てのユーザから書き込めるならば、そのファイルのパーミッションを表す整数を返します。そうでない場合は nil を返します。

整数の意味はプラットフォームに依存します。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

例:

m = File.world_writable?("/tmp")
"%o" % m                               #=> "777"

writable?(path) -> bool

FileTest.#writable? と同じです。

[PARAM] path:: パスを表す文字列を指定します。

writable_real?(path) -> bool

FileTest.#writable_real? と同じです。

[PARAM] path:: パスを表す文字列を指定します。

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

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

offset を指定するとその位置までシークします。

offset を指定しないと、書き込みの末尾でファイルを切り捨てます。

引数最後のハッシュはファイルを開くときに使われます。エンコーディングなどを指定することができます。詳しくは IO.open を見てください。

[PARAM] path:: ファイル名文字列
[PARAM] string:: 書き込む文字列
[PARAM] offset:: 書き込み開始位置
[PARAM] opt:: ファイルを開くときのオプション引数

[SEE_ALSO] IO.binwrite

zero?(path) -> bool

FileTest.#zero? と同じです。

[PARAM] path:: パスを表す文字列か IO オブジェクトを指定します。

インスタンスメソッド

self << object -> self

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

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

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

[PARAM] object:: 出力したいオブジェクトを与えます。
[EXCEPTION] Errno::EXXX:: 出力に失敗した場合に発生します。

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

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

advice には以下のいずれかのシンボルを指定します。

:normal - デフォルト
:sequential - データは前から順にアクセスされる
:random - データはランダムアクセスされる
:willneed - データはこの直後にアクセスされる
:dontneed - データは直後にはアクセスしない
:noreuse - データは一度しかアクセスされない

これらの advice が具体的に何をするのかはプラットフォーム依存です。

ここでいう「データ」は offset と len で特定することができます。 len が 0 ならば、offset からファイル末尾までを指定したことになります。デフォルトでは offset と len がともに 0 なので、ファイル全体を指定したことになります。

posix_fadvise をサポートしていないプラットフォーム上では何もしません。

[PARAM] advice:: アクセスパターンを表すシンボル
[PARAM] offset:: パターンを指定するデータの先頭位置
[PARAM] len:: パターンを指定するデータの長さ
[EXCEPTION] IOError:: ストリームが既に閉じられているときに発生する例外
[EXCEPTION] Errno::EBADF:: ファイルデスクリプタが不正であるときに発生する例外
[EXCEPTION] Errno::EINVAL:: advice が不正
[EXCEPTION] Errno::ESPIPE:: ファイルデスクリプタが FIFO か pipe を指している場合に発生する例外(Linux はこの場合には Errno::EINVAL を発生する)
[EXCEPTION] RangeError:: offset,lenが有効範囲から出ている場合に発生する例外

atime -> Time

最終アクセス時刻を Time オブジェクトとして返します。

[EXCEPTION] IOError:: 自身が close されている場合に発生します。
[EXCEPTION] Errno::EXXX:: ファイルの時刻の取得に失敗した場合に発生します。

[SEE_ALSO] File#lstat, File#ctime, File#mtime

autoclose=(bool)

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

フラグが設定されているオブジェクトは close時/GCでのファイナライザ呼出時にファイルデスクリプタを close します。設定されていない場合は close しません。

[PARAM] bool:: 真偽値でフラグを設定します

[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

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

[SEE_ALSO] IO#autoclose=

binmode -> self

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

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

[EXCEPTION] Errno::EXXX:: モードの変更に失敗した場合に発生します。

binmode? -> bool

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

bytes -> Enumerator

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

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

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

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

each_char -> Enumerator

chars -> Enumerator

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

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

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

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

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

chmod(mode) -> 0

ファイルのモードを指定された mode に変更します。

モードの変更に成功した場合は 0 を返します。失敗した場合は例外 Errno::EXXX が発生します。

[PARAM] mode:: chmod(2) と同様に整数で指定します。
[EXCEPTION] IOError:: 自身が close されている場合に発生します。
[EXCEPTION] Errno::EXXX:: 失敗した場合に発生します。

例:

f = File.new("out", "w");
f.chmod(0644)   #=> 0

chown(owner, group) -> 0

ファイルのオーナーとグループを変更します。

適切な権限があればファイルのオーナーとグループを変更できます。所有者の変更に成功した場合は 0 を返します。変更に失敗した場合は例外 Errno::EXXX が発生します。

[PARAM] owner:: chown(2) と同様に数値で指定します。nil または -1 を指定することで、オーナーを現在のままにすることができます。
[PARAM] group:: chown(2) と同様に数値で指定します。nil または -1 を指定することで、グループを現在のままにすることができます。
[EXCEPTION] IOError:: 自身が close されている場合に発生します。
[EXCEPTION] Errno::EXXX:: 変更に失敗した場合に発生します。

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_on_exec=(bool)

自身に close-on-exec フラグを設定します。

このフラグをセットすると exec(2) 時にそのファイルデスクリプタを close します。

[SEE_ALSO] fcntl(2)

[PARAM] bool:: 自身の close-on-exec フラグを true か false で指定します。

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

自身に 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

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

[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: close に失敗した場合に発生します。

close_write -> nil

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

[EXCEPTION] IOError:: 自身が書き込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: close に失敗した場合に発生します。

closed? -> bool

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

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

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

each_codepoint -> Enumerator

codepoints -> Enumerator

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

ブロックの引数にはコードポイントを表す整数が渡されます。

ブロックを省略した場合には、Enumerator を返します。

ctime -> Time

状態が最後に変更された時刻を Time オブジェクトとして返します。状態の変更とは chmod などによるものです。

[EXCEPTION] IOError:: 自身が close されている場合に発生します。
[EXCEPTION] Errno::EXXX:: ファイルの時刻の取得に失敗した場合に発生します。

[SEE_ALSO] File#lstat, File#atime, File#mtime

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

each_byte -> Enumerator

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

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

バイナリ読み込みメソッドとして動作します。

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

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

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

lines(limit) {|line| ... } -> self

lines(rs, limit) {|line| ... } -> self

lines(rs = $/) -> Enumerator

lines(limit) -> Enumerator

lines(rs, limit) -> Enumerator

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

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

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

limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で切れないように余分に読み込む場合があります。

[PARAM] rs:: 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
[PARAM] limit:: 最大の読み込みバイト数
[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。

[SEE_ALSO] $/, IO#gets

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:: 自身が読み込み用にオープンされていなければ発生します。

external_encoding -> Encoding | nil

IO の外部エンコーディングを返します。外部エンコーディングが指定されていない場合は nil を返します。

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 されている場合に発生します。

fdatasync -> 0 | nil

IO のすべてのバッファされているデータを直ちにディスクに書き込みます。

fdatasync(2) をサポートしていない OS 上では代わりに IO#fsync を呼びだします。

IO#fsync との違いは fdatasync(2) を参照してください。

[EXCEPTION] NotImplementedError:: fdatasync(2) も fsync(2) もサポートされていない OS で発生します。

fileno -> Integer

to_i -> Integer

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

[EXCEPTION] IOError:: 既に close されている場合に発生します。

flock(operation) -> 0 | false

ファイルをロックします。

ロックを取得するまでブロックされます。ロックの取得に成功した場合は 0 を返します。 File::LOCK_NB (ノンブロッキング) を指定すると、本来ならブロックされる場合にブロックされずに false を返すようになります。

[PARAM] operation:: ロックに対する操作の種類を示す定数を指定します。どのような定数が利用可能かは以下を参照して下さい。
[EXCEPTION] IOError:: 自身が close されている場合に発生します。
[EXCEPTION] Errno::EXXX:: operation に不正な整数を与えた場合などに発生します。

引数 operation に有効な定数は以下の通りです。定数は File::Constants で定義されていますが、 File クラスの親クラスの IO が File::Constants をインクルードしているので、これらの定数は File::LOCK_SH などとして参照可能です。

LOCK_SH: 共有ロック。複数のプロセスが同時にロックを共有できます。システムによってはロック対象のファイルは読み込みモード ("r", "r+" など)でオープンされている必要があります。そのようなシステムでは読み込み可能でないファイルに対するロックは例外 Errno::EXXX が発生するかもしれません。
LOCK_EX: 排他ロック。同時にはただひとつのプロセスだけがロックを保持できます。システムによってはロック対象のファイルは書き込みモード ("w", "r+" など)でオープンされている必要があります。そのようなシステムでは書き込み可能でないファイルに対するロックは例外 Errno::EXXX が発生するかもしれません。
LOCK_UN: アンロック。この明示的なアンロック以外に、ファイルのcloseやRubyインタプリタの終了 (プロセスの終了)によっても自動的にロック状態は解除されます。
LOCK_NB: ノンブロックモード。 File::LOCK_SH | File::LOCK_NB のように他の指定と or することで指定します。この指定がない場合、ブロックされる条件での flock の呼び出しはロックが解除されるまでブロックされます。

File::LOCK_NB の指定がある場合、ブロックされる条件での flock は false を返します。

「ブロックされる条件」とは以下のいずれかです。

他のプロセスが排他ロックをすでに行っている場合にロックを行う
他のプロセスがロックしている状態で排他ロックを行う

例1:

# 書き込みロック(write lock)を使用してカウンタを更新。
# ロック前にファイルを切り詰めてしまうので、
# モードに"w"を使ってはいけません。
File.open("counter", File::RDWR|File::CREAT, 0644) {|f|
  f.flock(File::LOCK_EX)
  value = f.read.to_i + 1
  f.rewind
  f.write("#{value}\n")
  f.flush
  f.truncate(f.pos)
}

# 読み込みロック(read lock)を使用してカウンタを読み込み。
File.open("counter", "r") {|f|
  f.flock(File::LOCK_SH)
  p f.read
}

例2:

f = File.open("/tmp/foo", "w")

f.flock(File::LOCK_EX)
puts "locked by process1"

fork {
  f = File.open("/tmp/foo", "r")
  f.flock(File::LOCK_SH)
  puts "locked by process2"
  sleep 5
  puts "unlocked by process2"
}

sleep 5

f.flock(File::LOCK_UN)
puts "unlocked by process1"
sleep 1 # <- 子プロセスが確実に先にロックするための sleep
f.flock(File::LOCK_EX)
puts "re-locked by process1"

=> locked by process1
   unlocked by process1
   locked by process2
   unlocked by process2
   re-locked by process1

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 -> String | nil

IO ポートから外部エンコーディングに従い 1 文字読み込んで返します。 EOF に到達した時には nil を返します。

テキスト読み込みメソッドとして動作します。 IO#readchar との違いは EOF での振る舞いのみです。

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

例:

[SEE_ALSO] IO#readchar

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

gets(limit) -> String | nil

gets(rs, limit) -> String | nil

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

テキスト読み込みメソッドとして動作します。読み込んだ文字列を変数 $_ にセットします。 IO#readline との違いは EOF での振る舞いのみです。

limit で最大の読み込みバイト数を指定します。ただしファイルのエンコーディングがマルチバイトエンコーディングである場合には読み込んだ文字列がマルチバイト文字の途中で切れないように数バイト余分に読み込む場合があります。

[PARAM] rs:: 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
[PARAM] limit:: 最大の読み込みバイト数
[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

internal_encoding -> Encoding | nil

IO の内部エンコーディングを返します。内部エンコーディングが指定されていない場合は nil を返します。

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] $.

lstat -> File::Stat

ファイルの状態を含む File::Stat オブジェクトを生成して返します。シンボリックリンクに関してリンクそのものの情報を返します。 lstat(2) を実装していないシステムでは、IO#statと同じです。

[EXCEPTION] Errno::EXXX:: 失敗した場合に発生します。
[EXCEPTION] IOError:: 自身が close されている場合に発生します。

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

mtime -> Time

最終更新時刻を Time オブジェクトとして返します。

[EXCEPTION] IOError:: 自身が close されている場合に発生します。
[EXCEPTION] Errno::EXXX:: ファイルの時刻の取得に失敗した場合に発生します。

[SEE_ALSO] File#lstat, File#atime, File#ctime

path -> String

to_path -> String

オープン時に使用したパスを文字列で返します。

File.new("testfile").path               #=> "testfile"
File.new("/tmp/../tmp/xxx", "w").path   #=> "/tmp/../tmp/xxx"

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 バイト読み込んで、その文字列を返します。

引数 length が指定された場合はバイナリ読み込みメソッド、そうでない場合はテキスト読み込みメソッドとして動作します。既に EOF に達していれば nil を返します。ただし、length に nil か 0 が指定されている場合は、空文字列 "" を返します。例えば、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 例外として呼出元に報告されます。

発生した例外がErrno::EAGAIN、 Errno::EWOULDBLOCK である場合は、その例外オブジェクトに IO::WaitReadable が Object#extend されます。

なお、バッファが空でない場合は、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 -> String

IO ポートから 1 文字読み込んで返します。 EOF に到達した時には EOFError が発生します。

テキスト読み込みメソッドとして動作します。 IO#getc との違いは EOF での振る舞いのみです。

[EXCEPTION] EOFError:: EOF に到達した時に発生します。
[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。

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

readline(limit) -> String

readline(rs, limit) -> String

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

テキスト読み込みメソッドとして動作します。読み込んだ文字列を変数 $_ にセットします。IO#gets との違いは EOF での振る舞いのみです。

limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で切れないように余分に読み込む場合があります。

[PARAM] rs:: 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
[PARAM] limit:: 最大の読み込みバイト数
[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]

readlines(limit) -> [String]

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

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

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

limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で切れないように余分に読み込む場合があります。

[PARAM] rs:: 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
[PARAM] limit:: 最大の読み込みバイト数
[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。

[SEE_ALSO] $/, IO#gets

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

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

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

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

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

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

バッファが空でなければ、そのバッファのデータを読み込んで返します。
ストリームにデータがあれば、ストリームからデータを読み込んで返します。
ストリームが 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 に達していれば発生します。

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

set_encoding(enc_str, opt={}) -> self

set_encoding(ext_enc) -> self

set_encoding(ext_enc, int_enc, opt={}) -> self

IO のエンコーディングを設定します。

引数が "A:B" のようにコロンで区切られた文字列の場合は、 A を外部エンコーディング、 B を内部エンコーディングに指定します。

引数が一つで、上のような形式でない場合には、それが外部エンコーディングと見なされます。

引数が2つの場合はそのそれぞれを外部エンコーディング、内部エンコーディングに設定します。

opt のハッシュで外部エンコーディングを内部エンコーディングに変換する際のオプションを指定します。詳しくは String#encode を参照してください。

[PARAM] enc_str:: エンコーディングを表す文字列を指定します。"A:B" のようにコロンで区切られた文字列を指定した場合 A が外部エンコーディング、B が内部エンコーディングを表します。
[PARAM] ext_enc:: 外部エンコーディングを表す文字列か Encoding オブジェクトを指定します。
[PARAM] int_enc:: 内部エンコーディングを表す文字列か Encoding オブジェクトを指定します。
[PARAM] opt:: エンコーディング変換のオプション

例:

io = File.open(file)
io.set_encoding("ASCII-8BIT", "EUC-JP")

size -> Integer

ファイルのサイズを返します。

例:

File.open("/dev/null") do |f|
  f.size   #=> 0
end

[EXCEPTION] IOError:: 自身が close されている場合に発生します。
[EXCEPTION] Errno::EXXX:: 失敗した場合に発生します。

[SEE_ALSO] File#lstat

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? などと混用すると思わぬ動作をすることがあります。

[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 を返します。

truncate(length) -> 0

ファイルのサイズを最大 length バイトにします。

サイズの変更に成功すれば 0 を返します。失敗した場合は例外 Errno::EXXX が発生します。

[EXCEPTION] IOError:: 自身が書き込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: サイズの変更に失敗した場合に発生します。

ungetbyte(c) -> nil

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

2バイト以上の書き戻しは仕様として保証しません。

このメソッドはバッファを経由しない読み出し(IO#sysread など) には影響しません。

[PARAM] c:: バイト列(文字列)、もしくは0から255までの整数

例:

f = File.new("testfile")   #=> #<File:testfile>
b = f.getbyte              #=> 0x38
f.ungetbyte(b)             #=> nil
f.getbyte                  #=> 0x38

ungetc(char) -> nil

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

[PARAM] char:: 読み戻したい1文字かそのコードポイントを指定します。
[EXCEPTION] IOError:: 読み戻しに失敗した場合に発生します。また、自身が読み込み用にオープンされていない時、自身がまだ一度も read されていない時に発生します。

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 の値より小さい可能性があります。

発生した例外がErrno::EAGAIN、 Errno::EWOULDBLOCK である場合は、その例外オブジェクトに IO::WaitWritable が Object#extend されます。よって IO::WaitWritable を write_nonblock のリトライが必要かの判定に用いることができます。

[PARAM] string:: 自身に書き込みたい文字列を指定します。
[EXCEPTION] IOError:: 自身が書き込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: write(2) が失敗した場合に発生します。

定数

ALT_SEPARATOR -> "\\" | nil: システムのファイルパスのセパレータが SEPARATOR と異なる場合に設定されます。MS-DOS などでは "\\" です。UNIX や Cygwin などでは nil です。
PATH_SEPARATOR -> ";" | "," | ":": PATH 環境変数の要素のセパレータです。UNIX では ":" MS-DOS などでは ";" です。
SEEK_CUR -> Fixnum: IO#seek を参照してください。
SEEK_END -> Fixnum: IO#seek を参照してください。
SEEK_SET -> Fixnum: IO#seek を参照してください。
SEPARATOR -> "/"
Separator -> "/": ファイルパスのセパレータです。ファイルを扱うメソッドにパス名を渡す場合などスクリプト内のパス名は環境によらずこのセパレータで統一されます。値は "/" です。

class File

Ruby 1.9.3 リファレンスマニュアル