Ruby 1.9.2 リファレンスマニュアル > ライブラリ一覧 > fileutilsライブラリ > FileUtilsモジュール

module FileUtils

クラスの継承リスト: FileUtils

要約

基本的なファイル操作を集めたモジュールです。

オプションの説明

引数 options で使用できるオプションの説明です。メソッドごとに使用できるオプションは決まっています。不正なオプションを与えると ArgumentError が発生します。

:noop: 真を指定すると実際の処理は行いません。
:preserve: 真を指定すると更新時刻と、可能なら所有ユーザ・所有グループもコピーします。
:verbose: 真を指定すると詳細を出力します。
:mode: パーミッションを8進数で指定します。
:force: 真を指定すると作業中すべての StandardError を無視します。
:nocreate: 真を指定するとファイルを作成しません。
:dereference_root: 真を指定すると src についてだけシンボリックリンクの指す内容をコピーします。偽の場合はシンボリックリンク自体をコピーします。
:remove_destination: 真を指定するとコピーを実行する前にコピー先を削除します。
:secure: 真を指定するとファイルの削除に FileUtils.#remove_entry_secure を使用します。
:mtime: 時刻を Time か、起算時からの経過秒数を数値で指定します。

特異メソッド: collect_method commands have_option? options options_of
モジュール関数: cd chdir chmod chmod_R chown chown_R cmp compare_file identical? compare_stream copy cp copy_entry copy_file copy_stream cp_r getwd pwd install link ln ln_s symlink ln_sf makedirs mkdir_p mkpath mkdir move mv remove rm remove_dir remove_entry remove_entry_secure remove_file rm_f safe_unlink rm_r rm_rf rmtree rmdir touch uptodate?
定数: METHODS OPT_TABLE

特異メソッド

collect_method(opt) -> Array[permalink][rdoc]

与えられたオプションを持つメソッド名の配列を返します。

[PARAM] opt:: オプション名をシンボルで指定します。

FileUtils.collect_method(:preserve) # => ["cp", "cp_r", "copy", "install"]

commands -> Array[permalink][rdoc]

何らかのオプションを持つメソッド名の配列を返します。

FileUtils.commands  # => ["chmod", "cp", "cp_r", "install", ...]

have_option?(mid, opt) -> bool[permalink][rdoc]

mid というメソッドが opt というオプションを持つ場合、真を返します。そうでない場合は、偽を返します。

[PARAM] mid:: メソッド名を指定します。
[PARAM] opt:: オプション名を指定します。

options -> Array[permalink][rdoc]

オプション名の配列を返します。

FileUtils.options  #=> ["noop", "force", "verbose", "preserve", "mode"]

options_of(mid) -> Array[permalink][rdoc]

与えられたメソッド名で使用可能なオプション名の配列を返します。

[PARAM] mid:: メソッド名を指定します。

FileUtils.options(:rm)  # => ["noop", "verbose", "force"]

モジュール関数

cd(dir, options = {}) -> nil[permalink][rdoc]

cd(dir, options = {}) {|dir| .... } -> nil

chdir(dir, options = {}) -> nil

chdir(dir, options = {}) {|dir| .... } -> nil

プロセスのカレントディレクトリを dir に変更します。

ブロックとともに呼び出された時はブロック終了後に元のディレクトリに戻ります。

[PARAM] dir:: ディレクトリを指定します。
[PARAM] options:: :verbose が指定できます。 FileUtils/オプションの説明

例:

FileUtils.cd('/', {:verbose => true})   # chdir and report it

chmod(mode, list, options = {}) -> Array[permalink][rdoc]

ファイル list のパーミッションを mode に変更します。

[PARAM] mode:: パーミッションを8進数で指定します。
[PARAM] list:: ファイルのリストを指定します。対象のファイルが一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:: :noop と :verbose が指定可能です。 FileUtils/オプションの説明
[RETURN]: list を配列として返します。

例:

FileUtils.chmod(0644, %w(my.rb your.rb his.rb her.rb)
FileUtils.chmod(0755, 'somecommand')
FileUtils.chmod(0755, '/usr/bin/ruby', :verbose => true

chmod_R(mode, list, options = {}) -> Array[permalink][rdoc]

ファイル list のパーミッションを再帰的に mode へ変更します。

[PARAM] mode:: パーミッションを8進数で指定します。
[PARAM] list:: ファイルのリストを指定します。対象のファイルが一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:: :noop と :verbose が指定可能です。 FileUtils/オプションの説明
[RETURN]: list を配列として返します。

例:

FileUtils.chmod_R(0700, '/tmp/removing')

chown(user, group, list, options = {}) -> Array[permalink][rdoc]

ファイル list の所有ユーザと所有グループを user と group に変更します。

user, group に nil または -1 を渡すとその項目は変更しません。

[PARAM] user:: ユーザー名か uid を指定します。nil/-1 を指定すると変更しません。
[PARAM] group:: グループ名か gid を指定します。nil/-1 を指定すると変更しません。
[PARAM] list:: ファイルのリストを指定します。対象のファイルが一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:: :noop と :verbose が指定可能です。 FileUtils/オプションの説明
[RETURN]: list を配列として返します。

例:

FileUtils.chown 'root', 'staff', '/usr/local/bin/ruby'
FileUtils.chown nil, 'bin', Dir.glob('/usr/bin/*'), :verbose => true

chown_R(user, group, list, options = {}) -> Array[permalink][rdoc]

list 以下のファイルの所有ユーザと所有グループを user と group へ再帰的に変更します。

user, group に nil または -1 を渡すとその項目は変更しません。

[PARAM] user:: ユーザー名か uid を指定します。nil/-1 を指定すると変更しません。
[PARAM] group:: グループ名か gid を指定します。nil/-1 を指定すると変更しません。
[PARAM] list:: ファイルのリストを指定します。対象のファイルが一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:: :noop と :verbose が指定可能です。 FileUtils/オプションの説明
[RETURN]: list を配列として返します。

例:

FileUtils.chown 'root', 'staff', '/usr/local/bin/ruby'
FileUtils.chown nil, 'bin', Dir.glob('/usr/bin/*'), :verbose => true

FileUtils.chown_R 'www', 'www', '/var/www/htdocs'
FileUtils.chown_R 'cvs', 'cvs', '/var/cvs', :verbose => true

cmp(file_a, file_b) -> bool[permalink][rdoc]

compare_file(file_a, file_b) -> bool

identical?(file_a, file_b) -> bool

ファイル a と b の内容が同じなら真を返します。

[PARAM] file_a:: ファイル名。
[PARAM] file_b:: ファイル名。

例:

FileUtils.cmp('somefile', 'somefile')  #=> true
FileUtils.cmp('/bin/cp', '/bin/mv')    #=> maybe false.

compare_stream(io_a, io_b) -> bool[permalink][rdoc]

IO オブジェクト io_a と io_b の内容が同じなら真を返します。

[PARAM] io_a:: IO オブジェクト。
[PARAM] io_b:: IO オブジェクト。

cp(src, dest, options = {}) -> ()[permalink][rdoc]

copy(src, dest, options = {}) -> ()

ファイル src を dest にコピーします。

src にファイルが一つだけ与えられた場合、 dest がディレクトリならdest/src にコピーします。 dest が既に存在ししかもディレクトリでないときは上書きします。

src にファイルが複数与えられた場合、 file1 を dest/file1 にコピー、file2 を dest/file2 にコピー、というように、ディレクトリ dest の中にファイル file1、file2 …を同じ名前でコピーします。dest がディレクトリでない場合は例外 Errno::ENOTDIR が発生します。

[PARAM] src:: コピー元。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:: コピー先のファイルかディレクトリです。
[PARAM] options:: :preserve, :noop, :verbose が指定できます。 FileUtils/オプションの説明
[EXCEPTION] Errno::ENOTDIR:: src が複数のファイルかつ、dest がディレクトリでない場合に発生します。

例:

FileUtils.cp 'eval.c', 'eval.c.org'
FileUtils.cp(['cgi.rb', 'complex.rb', 'date.rb'], '/usr/lib/ruby/1.8')
FileUtils.cp(%w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.8', {:verbose => true})

copy_entry(src, dest, preserve = false, dereference_root = false) -> ()[permalink][rdoc]

ファイル src を dest にコピーします。

src が普通のファイルでない場合はその種別まで含めて完全にコピーします。 src がディレクトリの場合はその中身を再帰的にコピーします。

[PARAM] src:: コピー元。
[PARAM] dest:: コピー先。
[PARAM] preserve:: preserve が真のときは更新時刻と、可能なら所有ユーザ・所有グループもコピーします。
[PARAM] dereference_root:: dereference_root が真のときは src についてだけシンボリックリンクの指す内容をコピーします。偽の場合はシンボリックリンク自体をコピーします。

copy_file(src, dest, preserve = false, dereference_root = true) -> ()[permalink][rdoc]

ファイル src の内容を dest にコピーします。

[PARAM] src:: コピー元。
[PARAM] dest:: コピー先。
[PARAM] preserve:: preserve が真のときは更新時刻と、可能なら所有ユーザ・所有グループもコピーします。
[PARAM] dereference_root:: dereference_root が真のときは src についてだけシンボリックリンクの指す内容をコピーします。偽の場合はシンボリックリンク自体をコピーします。

copy_stream(src, dest) -> ()[permalink][rdoc]

src を dest にコピーします。 src には read メソッド、dest には write メソッドが必要です。

[PARAM] src:: read メソッドを持つオブジェクト。
[PARAM] dest:: write メソッドを持つオブジェクト。

cp_r(src, dest, options = {}) -> ()[permalink][rdoc]

src を dest にコピーします。src がディレクトリであったら再帰的にコピーします。その際 dest がディレクトリなら dest/src にコピーします。

[PARAM] src:: コピー元。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:: コピー先のファイルかディレクトリです。
[PARAM] options:: :preserve, :noop, :verbose, :dereference_root, :remove_destination が指定できます。 FileUtils/オプションの説明

例:

# installing ruby library "mylib" under the site_ruby
FileUtils.rm_r(site_ruby + '/mylib', {:force => true})
FileUtils.cp_r('lib/', site_ruby + '/mylib')
# other sample
FileUtils.cp_r(%w(mail.rb field.rb debug/), site_ruby + '/tmail')
FileUtils.cp_r(Dir.glob('*.rb'), '/home/taro/lib/ruby',
               {:noop => true, :verbose => true})

pwd -> String[permalink][rdoc]

getwd -> String

プロセスのカレントディレクトリを文字列で返します。

install(src, dest, options = {}) -> ()[permalink][rdoc]

src と dest の内容が違うときだけ src を dest にコピーします。

[PARAM] src:: コピー元。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:: コピー先のファイルかディレクトリです。
[PARAM] options:: :preserve, :noop, :verbose, :mode が指定できます。 FileUtils/オプションの説明

例:

FileUtils.install('ruby', '/usr/local/bin/ruby', {:mode => 0755, :verbose => true})
FileUtils.install('lib.rb', '/usr/local/lib/ruby/site_ruby', {:verbose => true})

ln(src, dest, options = {}) -> ()[permalink][rdoc]

link(src, dest, options = {}) -> ()

src へのハードリンク dest を作成します。

src が一つの場合、 dest がすでに存在しディレクトリであるときは dest/src を作成します。 dest がすでに存在しディレクトリでないならば例外 Errno::ENOTDIR が発生します。ただし :force オプションを指定したときは dest を上書きします。

src が複数の場合、 src[0] へのハードリンク dest/src[0]、src[1] へのハードリンク dest/src[1] …を作成します。 dest がディレクトリでない場合は例外 Errno::ENOTDIR が発生します。

[PARAM] src:: リンク元。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:: リンク作成先のファイルかディレクトリです。
[PARAM] options:: :force, :noop, :verbose が指定できます。 FileUtils/オプションの説明
[EXCEPTION] Errno::ENOTDIR:: dest がディレクトリでない場合に発生します。

例:

FileUtils.ln('gcc', 'cc', {:verbose => true})
FileUtils.ln('/usr/bin/emacs21', '/usr/bin/emacs')
FileUtils.cd('/bin')
FileUtils.ln(%w(cp mv mkdir), '/usr/bin')

ln_s(src, dest, options = {}) -> ()[permalink][rdoc]

symlink(src, dest, options = {}) -> ()

src へのシンボリックリンク dest を作成します。

src が複数の場合、 src[0] へのシンボリックリンク dest/src[0]、src[1] へのシンボリックリンク dest/src[1] …を作成します。 dest がディレクトリでない場合は例外 Errno::ENOTDIR が発生します。

[PARAM] src:: リンク元。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:: リンク作成先のファイルかディレクトリです。
[PARAM] options:: :force, :noop, :verbose が指定できます。 FileUtils/オプションの説明
[EXCEPTION] Errno::ENOTDIR:: dest がディレクトリでない場合に発生します。

例:

FileUtils.ln_s('/usr/bin/ruby', '/usr/local/bin/ruby')
FileUtils.ln_s('verylongsourcefilename.c', 'c', {:force => true})
FileUtils.ln_s(Dir.glob('bin/*.rb'), '/home/aamine/bin')

ln_sf(src, dest, options = {}) -> ()[permalink][rdoc]

src へのシンボリックリンク dest を作成します。

ln_s(src, dest, :force => true) と同じです。

[PARAM] src:: リンク元。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:: リンク作成先のファイルかディレクトリです。
[PARAM] options:: :force, :noop, :verbose が指定できます。 FileUtils/オプションの説明
[EXCEPTION] Errno::ENOTDIR:: dest がディレクトリでない場合に発生します。

[SEE_ALSO] FileUtils.#ln_s

mkdir_p(list, options = {}) -> Array[permalink][rdoc]

mkpath(list, options = {}) -> Array

makedirs(list, options = {}) -> Array

ディレクトリ dir とその親ディレクトリを全て作成します。

例えば、

FileUtils.mkdir_p('/usr/local/lib/ruby')

は以下の全ディレクトリを (なければ) 作成します。

/usr
/usr/local
/usr/local/bin
/usr/local/bin/ruby

[PARAM] list:: 作成するディレクトリ。一つの場合は文字列でも指定できます。二つ以上指定する場合は配列で指定します。
[PARAM] options:: :mode, :noop, :verbose が指定できます。 FileUtils/オプションの説明
[RETURN]: ディレクトリ名文字列の配列を返します。

mkdir(dir, options = {}) -> ()[permalink][rdoc]

ディレクトリ dir を作成します。

[PARAM] dir:: 作成するディレクトリ。
[PARAM] options:: :mode, :noop, :verbose が指定できます。 FileUtils/オプションの説明

例:

FileUtils.mkdir('test')
FileUtils.mkdir(%w( tmp data ))
FileUtils.mkdir('notexist', {:noop => true})  # does not create really

mv(src, dest, options = {}) -> ()[permalink][rdoc]

move(src, dest, options = {}) -> ()

ファイル src を dest に移動します。

src が一つの場合、 dest がすでに存在しディレクトリであるときは src を dest/src へ移動します。 dest がすでに存在しディレクトリでないときは src は dest を上書きします。

src が複数の場合、 src[0] を dest/src[0]、src[1] を dest/src[1] へ移動します。 dest がディレクトリでない場合は例外 Errno::ENOTDIR が発生します。

[PARAM] src:: 元のファイル。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:: 移動先のファイル、またはディレクトリ。
[PARAM] options:: :force, :noop, :verbose, :secure が指定できます。 FileUtils/オプションの説明

例:

FileUtils.mv('badname.rb', 'goodname.rb')
FileUtils.mv('stuff.rb', 'lib/ruby', {:force => true})
FileUtils.mv(['junk.txt', 'dust.txt'], "#{ENV['HOME']}/.trash")
FileUtils.mv(Dir.glob('test*.rb'), 'test', {:noop => true, :verbose => true} )

rm(list, options = {}) -> ()[permalink][rdoc]

remove(list, options = {}) -> ()

list で指定された対象を消去します。

[PARAM] list:: 削除する対象。一つの場合は文字列も指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:: :force, :noop, :verbose が指定できます。 FileUtils/オプションの説明

例:

FileUtils.rm('junk.txt')
FileUtils.rm(Dir.glob('*~'))
FileUtils.rm('NotExistFile', {:force => true})    # never raises exception

remove_dir(path, force = false) -> ()[permalink][rdoc]

ディレクトリ path を削除します。

[PARAM] path:: 削除するディレクトリ。
[PARAM] force:: 真のときは削除中に発生した StandardError を無視します。

remove_entry(path, force = false) -> ()[permalink][rdoc]

ファイル path を削除します。path がディレクトリなら再帰的に削除します。

このメソッドにはローカル脆弱性が存在します。詳しくは FileUtils.#remove_entry_secure の項を参照してください。

[PARAM] path:: 削除するパス。
[PARAM] force:: 真のときは削除中に発生した StandardError を無視します。

例:

FileUtils.remove_entry '/tmp/ruby.tmp.08883'

[SEE_ALSO] FileUtils.#remove_entry_secure

remove_entry_secure(path, force = false) -> ()[permalink][rdoc]

ファイル path を削除します。path がディレクトリなら再帰的に削除します。

FileUtils.#rm_r および FileUtils.#remove_entry には TOCTTOU (time-of-check to time-of-use)脆弱性が存在します。このメソッドはそれを防ぐために新設されました。 FileUtils.#rm_r および FileUtils.#remove_entry は以下の条件が満たされるときにはセキュリティホールになりえます。

親ディレクトリが全ユーザから書き込み可能 (/tmp を含む)
path 以下のいずれかのディレクトリが全ユーザから書き込み可能
システムがシンボリックリンクを持つ

この脆弱性を防ぐため、remove_entry_secure は削除前に path 以下のディレクトリのオーナーとパーミッションを変更し、上記の条件を回避します。ただし remove_entry_secure は親ディレクトリが以下の条件を満たすことを仮定しています。

UNIX システムおよびそれに類する環境では、sticky ビットが立っていること。
全ユーザが書き込み可能であるのは、直接の親ディレクトリのみであること。例えば、/var/tmp のパーミッションが 1777 であるのは問題ありませんが、その場合 / や /var が全ユーザから書き込み可能であってはなりません。

この条件が満たされない場合 remove_entry_secure は安全ではありません。

[PARAM] path:: 削除するパス。
[PARAM] force:: 真のときは削除中に発生した StandardError を無視します。

remove_file(path, force = false) -> ()[permalink][rdoc]

ファイル path を削除します。

[PARAM] path:: 削除するファイル。
[PARAM] force:: 真のときは削除中に発生した StandardError を無視します。

rm_f(list, options = {}) -> ()[permalink][rdoc]

safe_unlink(list, options = {}) -> ()

FileUtils.rm(list, :force => true) と同じです。

FileUtils/オプションの説明

[PARAM] list:: 削除する対象。一つの場合は文字列も指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:: :noop, :verbose が指定できます。 :force がセットされた場合は作業中すべての StandardError を無視します。

[SEE_ALSO] FileUtils.#rm

rm_r(list, options = {}) -> ()[permalink][rdoc]

ファイルまたはディレクトリ list を再帰的に消去します。

[PARAM] list:: 削除する対象。一つの場合は文字列も指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:: :force, :noop, :verbose, :secure が指定できます。 FileUtils/オプションの説明

注意

このメソッドにはローカル脆弱性が存在します。この脆弱性を回避するには :secure オプションを使用してください。詳しくは FileUtils.#remove_entry_secure の項を参照してください。

例:

FileUtils.rm_r(Dir.glob('/tmp/*'))
FileUtils.rm_r(Dir.glob('/tmp/*'), :secure => true)

[SEE_ALSO] FileUtils.#rm, FileUtils.#remove_entry_secure

rm_rf(list, options = {}) -> ()[permalink][rdoc]

rmtree(list, options = {}) -> ()

ファイルまたはディレクトリ list を再帰的に消去します。

rm_r(list, {:force => true}) と同じです。

[PARAM] list:: 削除する対象。一つの場合は文字列も指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:: :noop, :verbose, :secure が指定できます。 FileUtils/オプションの説明

注意

[SEE_ALSO] FileUtils.#rm, FileUtils.#rm_r, FileUtils.#remove_entry_secure

rmdir(dir, options = {}) -> ()[permalink][rdoc]

ディレクトリ dir を削除します。

[PARAM] dir:: 削除するディレクトリを指定します。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:: :noop, :verbose が指定できます。 FileUtils/オプションの説明
[EXCEPTION] Errno::ENOTEMPTY:: 削除するディレクトリが空でない場合に発生します。

例:

FileUtils.rmdir('somedir')
FileUtils.rmdir(%w(somedir anydir otherdir))
# 実際にはディレクトリの削除は行わずにメッセージ出力のみ
FileUtils.rmdir('somedir', {:verbose => true, :noop => true})

touch(list, options = {}) -> ()[permalink][rdoc]

list で指定されたファイルの最終変更時刻 (mtime) とアクセス時刻 (atime) を変更します。

list で指定されたファイルが存在しない場合は空のファイルを作成します。

[PARAM] list:: 対象のファイル。一つの場合は文字列も指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:: :mtime, :nocreate, :noop, :verbose が指定できます。 FileUtils/オプションの説明

例:

FileUtils.touch('timestamp')
FileUtils.touch('timestamp', :mtime => Time.now)
FileUtils.touch(Dir.glob('*.c'))

uptodate?(newer, older_list, options = nil) -> bool[permalink][rdoc]

newer が、older_list に含まれるすべてのファイルより新しいとき真。存在しないファイルは無限に古いとみなされます。

[PARAM] newer:: ファイルを一つ指定します。
[PARAM] older_list:: ファイル名の配列を指定します。
[PARAM] options:: どのようなオプションも指定することはできません。
[EXCEPTION] ArgumentError:: options にオプションを指定した場合に発生します。

例:

FileUtils.uptodate?('hello.o', ['hello.c', 'hello.h']) or system('make')

定数

METHODS -> Array[permalink][rdoc]: このモジュールで定義されている公開メソッドの配列を返します。
OPT_TABLE -> Hash[permalink][rdoc]: 内部で使用します。

module FileUtils

要約

オプションの説明

目次

特異メソッド

モジュール関数

注意

注意

定数