名前¶

File::Find - ディレクトリツリーを辿る

概要¶

    use File::Find;
    find(\&wanted, @directories_to_search);
    sub wanted { ... }

    use File::Find;
    finddepth(\&wanted, @directories_to_search);
    sub wanted { ... }

    use File::Find;
    find({ wanted => \&process, follow => 1 }, '.');

説明¶

これらは、Unix の find と同様、ディレクトリツリーを検索して 見つかったそれぞれのファイルに対して作業を行うためのものです。 File::Find は二つの関数 find と finddepth をエクスポートします。 これらは似たような動作をしますがわずかな違いがあります。

find

  find(\&wanted,  @directories);
  find(\%options, @directories);

find() does a depth-first search over the given @directories in the order they are given. For each file or directory found, it calls the &wanted subroutine. (See below for details on how to use the &wanted function). Additionally, for each directory found, it will chdir() into that directory and continue the search, invoking the &wanted function on each file or subdirectory in the directory.

find() は、@directories で指定されたディレクトリを、 指定された順序で、深さ優先探索を実行します。 発見されたファイルやディレクトリ毎に、&wanted サブルーチンを呼び出します。 (&wanted 関数の使い方に関する詳細については後述します)。 さらに、それぞれのディレクトリを発見すると、 そのディレクトリに chdir() して検索を続行し、 そのディレクトリのそれぞれのファイルやサブディレクトリに対して &wanted 関数を起動します。

finddepth

  finddepth(\&wanted,  @directories);
  finddepth(\%options, @directories);

finddepth() works just like find() except that it invokes the &wanted function for a directory after invoking it for the directory's contents. It does a postorder traversal instead of a preorder traversal, working from the bottom of the directory tree up where find() works from the top of the tree down.

finddepth() は find() と同様に動作しますが、 あるディレクトリの内容について &wanted 関数を起動した 後に ディレクトリに対して起動します。 これは、前順走査ではなく後順走査を行います; find() がディレクトリツリーの上から下に動作するのに対して、 これは下から上に動作します。

%options¶

find() の最初の引数は、&wanted 関数へのコードリファレンスか、 それぞれのファイルに対して行われる操作を記述したハッシュリファレンスです。 コードリファレンスは後述する "The wanted function" に記述されています。

ハッシュで可能なキーは以下のものです:

wanted

The value should be a code reference. This code reference is described in "The wanted function" below. The &wanted subroutine is mandatory.

値はコードリファレンスである必要があります。 このコードリファレンスは後述する "The wanted function" に記述されています。 &wanted サブルーチンは必須です。

bydepth

Reports the name of a directory only AFTER all its entries have been reported. Entry point finddepth() is a shortcut for specifying { bydepth => 1 } in the first argument of find().

ディレクトリ名を、その全てのエントリが報告された「後」に報告します。 エントリポイント finddepth() は find() の最初の引数に { bydepth => 1 } を指定したもののショートカットです。

preprocess

The value should be a code reference. This code reference is used to preprocess the current directory. The name of the currently processed directory is in $File::Find::dir. Your preprocessing function is called after readdir(), but before the loop that calls the wanted() function. It is called with a list of strings (actually file/directory names) and is expected to return a list of strings. The code can be used to sort the file/directory names alphabetically, numerically, or to filter out directory entries based on their name alone. When follow or follow_fast are in effect, preprocess is a no-op.

値はコードリファレンスである必要があります。 このコードリファレンスは現在のディレクトリを前処理にするために使われます。 現在処理しているディレクトリの名前は $File::Find::dir にあります。 この前処理関数は readdir() を呼び出した後、 wanted() 関数を呼び出すループの前に呼び出されます。 これは文字列のリスト (内容はファイル/ディレクトリの名前) で呼び出され、 文字列のリストを返すことを想定されます。 コードは、ファイル/ディレクトリ名をアルファベット順や数値順にソートしたり、 ディレクトリエントリを名前だめを基にしてフィルタリングしたりするために 使われます。 follow か follow_fast が有効の場合、preprocess は何もしません。

postprocess

The value should be a code reference. It is invoked just before leaving the currently processed directory. It is called in void context with no arguments. The name of the current directory is in $File::Find::dir. This hook is handy for summarizing a directory, such as calculating its disk usage. When follow or follow_fast are in effect, postprocess is a no-op.

値はコードリファレンスである必要があります。 これは現在処理しているディレクトリを離れる直前に起動されます。 これは引数なしで無効コンテキストで呼び出されます。 現在のディレクトリの名前は $File::Find::dir にあります。 このフックは、ディスク使用量を計算するような、ディレクトリを要約するのに 便利です。 follow か follow_fast が有効の場合、postprocess は何もしません。

follow

Causes symbolic links to be followed. Since directory trees with symbolic links (followed) may contain files more than once and may even have cycles, a hash has to be built up with an entry for each file. This might be expensive both in space and time for a large directory tree. See follow_fast and follow_skip below. If either follow or follow_fast is in effect:

Causes symbolic links to be followed. シンボリックリンクを持つ(辿る)ディレクトリツリーは複数回 ファイルを含むことがあり、循環している可能性もあるので、 それぞれのファイルのためのエントリで組み立てられたハッシュが必要です。 これは大きなディレクトリツリーに対しては容量と時間を消費します。 後述する follow_fast と follow_skip を参照してください。 follow か follow_fast が有効の場合:

• It is guaranteed that an lstat has been called before the user's wanted() function is called. This enables fast file checks involving _. Note that this guarantee no longer holds if follow or follow_fast are not set.

  ユーザーの wanted() 関数が呼び出される前に lstat が呼び出されることが保証されています。 これは _ に関する高速なファイルチェックを有効にします。 この保証は follow や follow_fast が設定されていない場合は もはや有効ではないことに注意してください。

• There is a variable $File::Find::fullname which holds the absolute pathname of the file with all symbolic links resolved. If the link is a dangling symbolic link, then fullname will be set to undef.

  全てのシンボリックリンクが解決されたファイルの完全パス名を保持する $File::Find::fullname 変数があります。 リンクが壊れたシンボリックリンクの場合、fullname は undef に設定されます。

This is a no-op on Win32.

これは Win32 では何もしません。

follow_fast

This is similar to follow except that it may report some files more than once. It does detect cycles, however. Since only symbolic links have to be hashed, this is much cheaper both in space and time. If processing a file more than once (by the user's wanted() function) is worse than just taking time, the option follow should be used.

これは follow に似ていますが、これはあるファイルを複数回 報告することがあります。 しかしこれは循環を検出します。 シンボリックリンクのみをハッシュする必要があるので、これは空間と時間に 関してより安価です。 (ユーザーの wanted() 関数によって) ファイルを複数回処理することが 単に時間が掛かるよりも悪い場合、follow オプションが使われるべきです。

This is also a no-op on Win32.

これも Win32 では何もしません。

follow_skip

follow_skip==1, which is the default, causes all files which are neither directories nor symbolic links to be ignored if they are about to be processed a second time. If a directory or a symbolic link are about to be processed a second time, File::Find dies.

デフォルトである follow_skip==1 なら、 ディレクトリでもシンボリックリンクでもない、 2 回目に処理されようとされている全てのファイルは無視されます。 ディレクトリやシンボリックリンクが 2 回目に処理されようとしている場合、File::Find は die します。

follow_skip==0 causes File::Find to die if any file is about to be processed a second time.

follow_skip==0 なら、2 回目に処理されようとしている場合、 どんなファイルでも File::Find は die します。

follow_skip==2 causes File::Find to ignore any duplicate files and directories but to proceed normally otherwise.

follow_skip==2 なら、File::Find はファイルやディレクトリの 重複を無視して、さもなければ通常通り処理します。

dangling_symlinks

If true and a code reference, will be called with the symbolic link name and the directory it lives in as arguments. Otherwise, if true and warnings are on, warning "symbolic_link_name is a dangling symbolic link\n" will be issued. If false, the dangling symbolic link will be silently ignored.

真でコードリファレンスなら、シンボリックリンク名とそれがあるディレクトリを 引数として呼び出されます。 それ以外の真なら、警告 "symbolic_link_name is a dangling symbolic link\n" が出力されます。 偽なら、壊れているシンボリックリンクは暗黙に無視されます。

no_chdir

Does not chdir() to each directory as it recurses. The wanted() function will need to be aware of this, of course. In this case, $_ will be the same as $File::Find::name.

再帰するときにそれぞれのディレクトリに対して chdir() しません。 もちろん wanted() 関数はこれに対応する必要があります。 この場合、$_ は $File::Find::name と同じになります。

untaint

If find is used in taint-mode (-T command line switch or if EUID != UID or if EGID != GID) then internally directory names have to be untainted before they can be chdir'ed to. Therefore they are checked against a regular expression untaint_pattern. Note that all names passed to the user's wanted() function are still tainted. If this option is used while not in taint-mode, untaint is a no-op.

find が (-T コマンドラインオプションか EUID != UID または EGID != GID で) 汚染チェックモードで使われると、 内部でディレクトリ名は chdir される前に汚染解除される必要があります。 従ってこれらは正規表現 untaint_pattern でチェックされます。 ユーザーの wanted() 関数に渡される全ての名前は 汚染されたままであることに注意してください。 汚染チェックモードでないときにこのオプションが使われると、 untaint は何もしません。

untaint_pattern

See above. This should be set using the qr quoting operator. The default is set to qr|^([-+@\w./]+)$|. Note that the parentheses are vital.

前述の通りです。 これは qr クォート演算子を使って設定されるべきです。 デフォルトは qr|^([-+@\w./]+)$| に設定されています。 かっこは不可欠であることに注意してください。

untaint_skip

If set, a directory which fails the untaint_pattern is skipped, including all its sub-directories. The default is to 'die' in such a case.

設定されると、 untaint_pattern に失敗したディレクトリは、そのサブディレクトリと共に 読み飛ばされます。 デフォルトでは、このような場合は 'die' します。

wanted 関数¶

wanted() はそれぞれのファイルとディレクトリに対して あなたがしたい何らかの検証を行います。 その名前にも関わらず、wanted() は一般的なコールバック関数で、 ファイルが「求められている」("wanted") かどうかを File::Find に伝えるもの ではありません 。 実際、その返り値は無視されます。

wanted 関数は引数を取りませんが、代わりにいくつかの変数を通して 処理を行います。

$File::Find::dir is the current directory name,

($File::Find::dir は現在のディレクトリ名)

$_ is the current filename within that directory

($_ はそのディレクトリの中の現在のファイル名)

$File::Find::name is the complete pathname to the file.

($File::Find::name はファイルの完全なパス名)

前述の変数は全てローカル化されていて、wanted 関数の外側の データに影響を与えることなく変更できます。

例えば、/some/path/foo.ext を調べるときは、次のようになります:

    $File::Find::dir  = /some/path/
    $_                = foo.ext
    $File::Find::name = /some/path/foo.ext

no_chdir が指定されていない限り、この関数が呼び出されるときに、 $File::Find::dir に chdir() されています。 ディレクトリの変更が有効の場合、 ルートディレクトリ (/) は $File::Find::dir, '/', $_ を連結したものが $File::Find::name と文字通り同じではないので、 特別な場合であることに注意してください。 次の表は全てのパターンをまとめています:

              $File::Find::name  $File::Find::dir  $_
 default      /                  /                 .
 no_chdir=>0  /etc               /                 etc
              /etc/x             /etc              x

 no_chdir=>1  /                  /                 /
              /etc               /                 /etc
              /etc/x             /etc              /etc/x

follow や follow_fast が有効なら、$File::Find::fullname もあります。 bydepth が指定されていない限り、 この関数はツリーを削るための $File::Find::prune を設定します。 follow や follow_fast が指定されていない限り、 互換性 (find.pl, find2perl) のために、 追加で以下のグローバル変数も利用可能です: $File::Find::topdir, $File::Find::topdev, $File::Find::topino, $File::Find::topmode, $File::Find::topnlink

このライブラリは find2perl ツールに有用です; これは次のようにすると:

    find2perl / -name .nfs\* -mtime +7 \
        -exec rm -f {} \; -o -fstype nfs -prune

以下のようなものを出力します:

    sub wanted {
        /^\.nfs.*\z/s &&
        (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_)) &&
        int(-M _) > 7 &&
        unlink($_)
        ||
        ($nlink || (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_))) &&
        $dev < 0 &&
        ($File::Find::prune = 1);
    }

前述の int(-M _) の中の _ に関する注意: _ は、直前の stat(), lstat() またはファイルテストからの 情報をキャッシュするマジカルなファイルハンドルです。

次はもう一つの興味深い wanted 関数です。 これは全ての解決できないシンボリックリンクを見つけます:

    sub wanted {
         -l && !-e && print "bogus link: $File::Find::name\n";
    }

このモジュールのよいアプリケーションについては CPAN にある pfind スクリプトも参照してください。

警告¶

プログラムを -w オプション付きで実行したり、 warnings プラグマを使っている場合、 File::Find はいくつかのおかしな状況について警告を出力します。 これらの警告を無効にするには次の文を

    no warnings 'File::Find';

適切なスコープで指定してください。 レキシカルな警告のさらなる情報については perllexwarn を 参照してください。

注意点¶

$dont_use_nlink

You can set the variable $File::Find::dont_use_nlink to 1, if you want to force File::Find to always stat directories. This was used for file systems that do not have an nlink count matching the number of sub-directories. Examples are ISO-9660 (CD-ROM), AFS, HPFS (OS/2 file system), FAT (DOS file system) and a couple of others.

File::Find が常にディレクトリを stat することを強制したい場合、 $File::Find::dont_use_nlink 変数を 1 に設定できます。 これはサブディレクトリの数に一致する nlink カウントを持っていない ファイルシステムに使われます。 例えば ISO-9660 (CD-ROM), AFS, HPFS (OS/2 ファイルシステム), FAT (DOS ファイルシステム) およびその他にいくつかあります。

You shouldn't need to set this variable, since File::Find should now detect such file systems on-the-fly and switch itself to using stat. This works even for parts of your file system, like a mounted CD-ROM.

あなたがこの変数を設定する必要はないはずです; なぜなら File::Find はこのようなファイルシステムをその場で検出して、 stat を使うように自分自身で切り替えるはずだからです。 これは、マウントされた CD-ROM のように、ファイルシステムの一部分であっても 動作します。

If you do set $File::Find::dont_use_nlink to 1, you will notice slow-downs.

$File::Find::dont_use_nlink を 1 に設定すると、 速度低下に気付くでしょう。

symlinks

(シンボリックリンク)

Be aware that the option to follow symbolic links can be dangerous. Depending on the structure of the directory tree (including symbolic links to directories) you might traverse a given (physical) directory more than once (only if follow_fast is in effect). Furthermore, deleting or changing files in a symbolically linked directory might cause very unpleasant surprises, since you delete or change files in an unknown directory.

シンボリックリンクを辿るオプションは危険かも知れないことに注意してください。 (ディレクトリへのシンボリックリンクを含む)ディレクトリツリーの構造に 依存して、(follow_fast が有効の場合にのみ) 与えられた (物理的な) ディレクトリを複数回辿るかもしれません。 さらに、シンボリックにリンクされたディレクトリ内のファイルを削除したり 変更したりすると、とても嬉しくない驚きを引き起こすかも知れません; 知らないディレクトリにあるファイルを削除や変更することになるからです。

バグと注意点¶

finddepth() 関数という名前にもかかわらず、 find() と finddepth() はどちらもディレクトリ階層を 深さ優先探索します。

歴史¶

File::Find は、再帰的に呼び出されると正しくない結果を出力していました。 perl 5.8 の開発中にこのバグは修正されました。 修正された最初のバージョンの File::Find は 1.01 です。

SEE ALSO¶

find, find2perl.