.\" Copyright (c) 1993 Michael Haardt (u31b3hs@pool.informatik.rwth-aachen.de) .\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) .\" and copyright (c) 2006 Justin Pryzby .\" and copyright (c) 2006 Michael Kerrisk .\" .\" This is free documentation; you can redistribute it and/or .\" modify it under the terms of the GNU General Public License as .\" published by the Free Software Foundation; either version 2 of .\" the License, or (at your option) any later version. .\" .\" The GNU General Public License's references to "object code" .\" and "executables" are to be interpreted as the output of any .\" document formatting or typesetting system, including .\" intermediate and printed output. .\" .\" This manual is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, .\" USA. .\" .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu) .\" 2006-05-24, Justin Pryzby .\" document FTW_ACTIONRETVAL; include .SH "RETURN VALUE"; .\" 2006-05-24, Justin Pryzby and .\" Michael Kerrisk .\" reorganized and rewrote much of the page .\" 2006-05-24, Michael Kerrisk .\" Added an example program. .\" .\" Japanese Version Copyright (c) 1998 NAKANO Takeo all rights reserved. .\" Translated 1998-04-28, NAKANO Takeo .\" Updated & Modified 1999-09-14, NAKANO Takeo .\" Updated & Modified 2005-11-04, Akihiro MOTOKI .\" Updated 2006-07-26, Akihiro MOTOKI , LDP v2.36 .\" .\" WORD: file descriptor ファイルディスクリプター .\" .TH FTW 3 2010-09-20 "Linux" "Linux Programmer's Manual" .SH 名前 ftw, nftw \- ファイルツリーを歩きまわる .SH 書式 .nf .B #include .sp .BI "int ftw(const char *" dirpath , .BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb , .BI " int " typeflag ), .BI " int " nopenfd ); .sp .BR "#define _XOPEN_SOURCE 500" " /* feature_test_macros(7) 参照 */" .B #define _XOPEN_SOURCE 500 .B #include .sp .BI "int nftw(const char *" dirpath , .BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb , .BI " int " typeflag ", struct FTW *" ftwbuf ), .BI " int " nopenfd ", int " flags ); .fi .SH 説明 .BR ftw () は、 .I dirpath で指定されたディレクトリ以下のディレクトリツリー全体を歩きまわり、 ツリー中でエントリが見付かるごとに、 .IR fn () を呼び出す。 デフォルトでは、ディレクトリそのものが、そのディレクトリにあるファイルや サブディレクトリよりも先に処理される (行きがけ順探索; preorder traversal)。 呼び出し元プロセスが利用可能なファイルディスクリプタを使い切って しまわないようにするため、 .BR ftw () が同時にオープンするディレクトリの最大数を .I nopenfd で指定することができる。 探索の深さがこの値を越えると、 一つのディレクトリを閉じてから他のディレクトリをオープンし直すこと になるので、 .BR ftw () の動作は遅くなる。 .BR ftw () は、ディレクトリツリーの階層 1 レベルにつき、 最大でも一つのファイルディスクリプタしか使用しない。 ディレクトリツリーで見つかったエントリ毎に、 .BR ftw () は .IR fpath , .IR sb , .I typeflag の 3つを引き数として .IR fn () を呼び出す。 .I fpath はエントリのパス名である。 .I dirpath が相対パス名で指定された場合には、 .I fpath は .BR ftw () が呼び出された時点の呼び出し元プロセスのカレントワーキングディレクトリ からの相対パス名となる。 .I dirpath が絶対パス名で指定された場合には、 .I fpath は絶対パス名となる。 .I sb は .I fpath に対する .BR stat (2) の呼び出しで返される .I stat 構造体へのポインタである。 .I typeflag は整数で、以下の値のいずれか一つである: .TP .B FTW_F .I fpath が通常のファイルである .TP .B FTW_D .I fpath がディレクトリである .TP .B FTW_DNR .I fpath が読み込みできないディレクトリである .TP .B FTW_NS シンボリックリンクではない .I fpath に対する .BR stat (2) 呼び出しが失敗した。 .sp .I fpath がシンボリックリンクで、かつ .BR stat (2) が失敗した場合、 .B FTW_NS と .B FTW_SL (後述) のどちらが .I typeflag に渡されるかは未定義であると、POSIX.1-2001 には書かれている。 .PP ツリーの探索を止めたい場合は、 .IR fn () が 0 以外の値を返せば良い (この値は .BR ftw () 自身の戻り値となる)。 それ以外の場合は .BR ftw () はツリー全体の探索を続け、すべてのツリーを探索し終えたところで 0 を返す。探索中に .RB ( malloc (3) の失敗などの) エラーが起こると \-1 を返す。 .PP .BR ftw () は動的なデータ構造を用いるので、ツリー探索を安全に中断する唯一の方法は 0 以外の値を .IR fn () の返り値とすることである。割り込みを扱うには、 例えば発生した割り込みをマークしておいて、 0 以外の値を返すようにする シグナルによりメモリリークを起こさずに探索を終了できるようにするには、 シグナルハンドラで .IR fn () がチェックするグローバルなフラグをセットするようにすればよい。 プログラムを終了させる場合以外は、 .BR longjmp (3) を使用しないこと。 .SS nftw() 関数 .BR nftw () は .BR ftw () と同じだが、引き数 .I flags が追加される点と、 .IR fn () の引き数に .I ftwbuf が追加される点が異なる。 この .I flags 引き数は下記のフラグの 0 個以上の論理和を取ったものである: .TP .BR FTW_ACTIONRETVAL " (glibc 2.3.3 以降)" このフラグは glibc 固有である。 このフラグをセットすると、 .BR nftw () の .IR fn () の返り値の扱いが変わる。 .IR fn () は以下の値のいずれか一つを返す必要がある。 .RS .TP .B FTW_CONTINUE .BR nftw () は通常通り処理を続ける。 .TP .B FTW_SKIP_SIBLINGS .IR fn () がこの値を返した場合、処理中のエントリの兄弟 (同じ階層のエントリ) の処理はスキップされ、親ディレクトリで続きの処理が行われる。 .\" If \fBFTW_DEPTH\fP .\" is set, the entry's parent directory is processed next (with .\" \fIflag\fP set to \fBFTW_DP\fP). .TP .B FTW_SKIP_SUBTREE .IR fn () が呼び出されたエントリがディレクトリ .RI ( typeflag が .BR FTW_D ) の場合に、この値を返すと .IR fn () の引き数として渡されたディレクトリ内のエントリの処理が行われなくなる。 .BR nftw () は処理中のディレクトリの兄弟 (同じ階層のエントリ) から処理を続ける。 .TP .B FTW_STOP .B nftw () は、返り値 .B FTW_STOP ですぐに復帰する。 .PP 他の返り値は将来新しい動作に対応付けられる可能性がある。 .IR fn () は上記のリストにある値以外を返さないようにすべきである。 .I で .B FTW_ACTIONRETVAL の定義が有効にするためには、 (「どの」ヘッダファイルをインクルードするよりも前に) 機能検査マクロ .B _GNU_SOURCE を定義しなければならない。 .RE .TP .B FTW_CHDIR セットされると、ディレクトリの内容を処理する前に そのディレクトリに .BR chdir (2) する。このフラグは、 .I fpath が属すディレクトリで何らかの動作を実行する必要がある場合に 便利である。 .TP .B FTW_DEPTH セットされると、帰りがけ順探索 (post-order traversal) を行う。 つまり、ディレクトリそのものを引き数とした .IR fn () 呼出しは、そのディレクトリに含まれるファイルとサブディレクトリに 対する処理の「後で」行われる (デフォルトでは、ディレクトリ自身の処理はディレクトリ内のエントリ より「前に」行なわれる)。 .TP .B FTW_MOUNT セットされると、同じファイルシステムの中だけを探索対象とする (つまり、マウントポイントをまたぐことはない)。 .TP .B FTW_PHYS セットされると、シンボリックリンクを辿らない (おそらくこちらが 通常望ましい動作だろう)。セットされていないとシンボリックリンクを 辿るが、同じファイルが二回報告されることはない。 .sp .B FTW_PHYS がセットされずに .B FTW_DEPTH がセットされると、自分自身に対するシンボリックリンクを配下に持つ ディレクトリに対して .IR fn () が呼び出されることは決してない。 .LP ディレクトリツリーのエントリ毎に、 .BR nftw () は 4つの引き数で .IR fn () を呼び出す。 .I fpath と .I sb は .BR ftw () と同じである。 .I typeflag には、 .BR ftw () で取り得る値のいずれか、または以下の値のいずれかが渡される: .TP .B FTW_DP .I fpath がディレクトリで、かつ .I flags で .B FTW_DEPTH が指定されていた。 .I fpath 配下のファイルとサブディレクトリは全て処理が終わっている。 .TP .B FTW_SL .I fpath がシンボリックリンクで、かつ \fBFTW_PHYS\fP が \fIflags\fP に セットされていた。 .\" To obtain the definition of this constant from .\" .IR , .\" either .\" .B _BSD_SOURCE .\" must be defined, or .\" .BR _XOPEN_SOURCE .\" must be defined with a value of 500 or more. .TP .B FTW_SLN .I fpath がシンボリックリンクで、存在しないファイルを指している (これがセットされるのは .B FTW_PHYS がセットされていない場合だけである)。 .LP .BR nftw () が .IR fn () を呼び出す際に渡す 4つめの引き数は .I FTW 型の構造体である。 .in +4n .nf struct FTW { int base; int level; }; .fi .in .I base は、ファイル名 (basename 要素) の、 .I fpath で渡されるパス名の中でのオフセットである。 .I level はディレクトリツリーでの .I fpath の深さを示す。深さはディレクトリツリーのトップ (root) からの 相対値である .RI ( dirpath は深さ 0 である)。 .SH 返り値 これらの関数は、成功すると 0 を、エラーが発生すると \-1 を返す。 .IR fn () が 0 以外を返した場合、ディレクトリツリーの探索を終了し、 .IR fn () が返した値を .BR ftw () や .BR nftw () の結果として返す。 .BR nftw () が .B FTW_ACTIONRETVAL フラグ付きで呼ばれた場合、ツリーの探索を終了させるために .IR fn () が使用できる、非 0 の値は .B FTW_STOP だけであり、 この値は .BR nftw () の返り値として返される。 .SH 準拠 POSIX.1-2001, SVr4, SUSv1. POSIX.1-2008 は .BR ftw () を廃止予定としている。 .SH 注意 POSIX.1-2001 の注記によると、 .I fn がカレントワーキングディレクトリを保持しなかった場合の 結果は規定されていないとされている。 .PP .BR nftw () 関数と、 .BR ftw () における .B FTW_SL は、SUSv1 で導入された。 .LP .BR ftw () で .B FTW_SL を一切使わないシステムや、 存在しないファイルを指しているシンボリックリンクの場合にのみ .B FTW_SL を使うシステム、また .BR ftw () が全てのシンボリックリンクに対して .B FTW_SL を使うシステムもある。 予測可能な動作をさせるためには、 .BR nftw () を使うこと。 .LP Linux では、 libc4, libc5, glibc 2.0.6 は 「stat できるがディレクトリではないオブジェクト」 (ファイル, シンボリックリンク, fifo 等) に対してはすべて .B FTW_F を使う。 .BR nftw () 関数は glibc 2.1 以降で利用できる。 .B FTW_ACTIONRETVAL は glibc 固有である。 .SH 例 以下のプログラムは、一つ目のコマンドライン引き数を名前に持つパス以下の ディレクトリツリーを探索する。引き数が指定されなかった場合は、 カレントディレクトリ以下を探索する。 各々のファイルについて様々の情報が表示される。 二番目のコマンドライン引き数に文字を指定することで、 .BR nftw () を呼び出す際に .I flags 引き数に渡す値を制御することができる。 .nf #define _XOPEN_SOURCE 500 #include #include #include #include #include static int display_info(const char *fpath, const struct stat *sb, int tflag, struct FTW *ftwbuf) { printf("%\-3s %2d %7jd %\-40s %d %s\\n", (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" : (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" : (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" : (tflag == FTW_SLN) ? "sln" : "???", ftwbuf\->level, (intmax_t) sb\->st_size, fpath, ftwbuf\->base, fpath + ftwbuf\->base); return 0; /* To tell nftw() to continue */ } int main(int argc, char *argv[]) { int flags = 0; if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL) flags |= FTW_DEPTH; if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL) flags |= FTW_PHYS; if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) == \-1) { perror("nftw"); exit(EXIT_FAILURE); } exit(EXIT_SUCCESS); } .fi .SH 関連項目 .BR stat (2), .BR fts (3), .BR readdir (3)