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

module FileUtils

クラスの継承リスト: FileUtils

Abstract

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

オプションの説明

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

:noop

真を指定すると実際の処理は行いません。

:preserve

真を指定すると更新時刻と、可能なら所有ユーザ・所有グループもコピーします。

:verbose

真を指定すると詳細を出力します。

:mode

パーミッションを8進数で指定します。

:force

真を指定すると作業中すべての StandardError を無視します。

:nocreate

真を指定するとファイルを作成しません。

:dereference_root

真を指定すると src についてだけシンボリックリンクの指す 内容をコピーします。偽の場合はシンボリックリンク自体をコピーします。

:remove_destination

真を指定するとコピーを実行する前にコピー先を削除します。

:secure

真を指定するとファイルの削除に FileUtils.#remove_entry_secure を使用します。

:mtime

時刻を Time か、起算時からの経過秒数を数値で指定します。

モジュール関数

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

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

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

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

例:

FileUtils.cd('/', {:verbose => true})   # chdir and report it
chmod(mode, list, options = {}) -> Array

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

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

例:

FileUtils.chmod(0644, ['my.rb', 'your.rb'])
FileUtils.chmod(0755, 'somecommand')
FileUtils.chmod(0755, '/usr/bin/ruby', {:verbose => true})
chmod_R(mode, list, options = {}) -> Array

ファイル 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

ファイル 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

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

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

[PARAM] io_a:
IO オブジェクト。
[PARAM] io_b:
IO オブジェクト。
cp(src, dest, options = {}) -> ()
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) -> ()

ファイル 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) -> ()

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

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

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

[PARAM] src:
read メソッドを持つオブジェクト。
[PARAM] dest:
write メソッドを持つオブジェクト。
cp_r(src, dest, options = {}) -> ()

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

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

install(src, dest, options = {})

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 = {}) -> ()
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 = {}) -> ()
symlink(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_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 = {}) -> ()

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 = {}) -> String | Array
mkpath(list, options = {}) -> String | Array
makedirs(list, options = {}) -> String | 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]
list を返します。
mkdir(dir, options = {}) -> ()

ディレクトリ 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 = {}) -> ()
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 = {}) -> ()
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) -> ()

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

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

ファイル 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) -> ()

ファイル 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) -> ()

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

[PARAM] path:
削除するファイル。
[PARAM] force:
真のときは削除中に発生した StandardError を無視します。
rm_f(list, options = {}) -> ()
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 = {}) -> ()

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

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

注意

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

例:

FileUtils.rm_r(Dir.glob('/tmp/*'))

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

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

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

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

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

注意

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

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

rmdir(dir, options = {}) -> ()

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

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

例:

FileUtils.rmdir('somedir')
FileUtils.rmdir(%w(somedir anydir otherdir))
# does not remove directory really, outputing message.
FileUtils.rmdir('somedir', {:verbose => true, :noop => true})
touch(list, options = {}) -> ()

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

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

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

例:

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

追加されるメソッド

ruby(*args) { ... } [added by rake]

与えられた引数で Ruby インタプリタを実行します。

[PARAM] args:
Ruby インタプリタに与える引数を指定します。

例:

ruby %{-pe '$_.upcase!' <README}
safe_ln(*args) [added by rake]

安全にリンクを作成します。

リンクの作成に失敗した場合はファイルをコピーします。

[PARAM] args:
FileUtils.#cp, FileUtils.#ln に渡す引数を指定します。

[SEE_ALSO] FileUtils.#cp, FileUtils.#ln

sh(*cmd) {|result, status| ... } [added by rake]

与えられたコマンドを実行します。

与えられた引数が複数の場合、シェルを経由しないでコマンドを実行します。

[PARAM] cmd:
引数の解釈に関しては Kernel.#exec を参照してください。

例:

sh %{ls -ltr}

sh 'ls', 'file with spaces'

# check exit status after command runs
sh %{grep pattern file} do |ok, res|
  if ! ok
    puts "pattern not found (status = #{res.exitstatus})"
  end
end

[SEE_ALSO] Kernel.#exec, Kernel.#system

split_all(path) -> Array [added by rake]

与えられたパスをディレクトリごとに分割します。

[PARAM] path:
分割するパスを指定します。

例:

split_all("a/b/c") =>  ['a', 'b', 'c']

Methods

Classes