Provided by: manpages-ja-dev_0.5.0.0.20210215+dfsg-1_all bug

名前

       ftw, nftw - ファイルツリーを歩きまわる

書式

       #include <ftw.h>

       int ftw(const char *dirpath,
               int (*fn) (const char *fpath, const struct stat *sb,
                          int typeflag),
               int nopenfd);

       #define _XOPEN_SOURCE 500   /* feature_test_macros(7) 参照 */
       #define _XOPEN_SOURCE 500
       #include <ftw.h>

       int nftw(const char *dirpath,
               int (*fn) (const char *fpath, const struct stat *sb,
                          int typeflag, struct FTW *ftwbuf),
               int nopenfd, int flags);

説明

       ftw()   は、 dirpath で指定されたディレクトリ以下のディレクトリツリー全体を歩きまわり、 ツ
       リー中でエントリーが見付かるごとに、 fn()  を呼び出す。 デフォルトでは、ディレクトリそのも
       のが、そのディレクトリにあるファイルや  サブディレクトリよりも先に処理される (行きがけ順探
       索; preorder traversal)。

       呼び出し元プロセスが利用可能なファイルディスクリプターを使い切って  しまわないようにするた
       め、  ftw() が同時にオープンするディレクトリの最大数を nopenfd で指定することができる。 探
       索の深さがこの値を越えると、  一つのディレクトリを閉じてから他のディレクトリをオープンし直
       すこと  になるので、 ftw()  の動作は遅くなる。 ftw() は、ディレクトリツリーの階層 1 レベル
       につき、 最大でも一つのファイルディスクリプターしか使用しない。

       ディレクトリツリーで見つかったエントリー毎に、 ftw()  は fpath, sb, typeflag の  3つを引き
       数として  fn()  を呼び出す。 fpath はエントリーのパス名である。 dirpath が相対パス名で指定
       された場合には、 fpathftw()   が呼び出された時点の呼び出し元プロセスのカレントワーキン
       グディレクトリ  からの相対パス名となる。  dirpath が絶対パス名で指定された場合には、 fpath
       は絶対パス名となる。 sbfpath に対する stat(2)  の呼び出しで返される stat  構造体へのポ
       インターである。 typeflag は整数で、以下の値のいずれか一つである:

       FTW_F  fpath が通常のファイルである

       FTW_D  fpath がディレクトリである

       FTW_DNR
              fpath が読み込みできないディレクトリである

       FTW_NS stat(2)  の呼び出しがシンボリックリンクでない fpath で失敗した。 これのよくある原因
              は、呼び出し元が親ディレクトリに対する読み込み許可を持っており、  ファイル名  fpath
              を見ることができたが、実行許可は持っておらず、  そのため stat(2) ではそのファイルに
              到達できなかった、というものである。

              fpath がシンボリックリンクで、かつ stat(2)  が失敗した場合、 FTW_NSFTW_SL  (後
              述)  のどちらが  typeflag に渡されるかは未定義であると、POSIX.1-2001 には書かれてい
              る。

       ツリーの探索を止めたい場合は、 fn()  が 0 以外の値を返せば良い (この値は ftw()  自身の戻り
       値となる)。 それ以外の場合は ftw()  はツリー全体の探索を続け、すべてのツリーを探索し終えた
       ところで 0 を返す。探索中に (malloc(3)  の失敗などの) エラーが起こると -1 を返す。

       ftw()  は動的なデータ構造を用いるので、ツリー探索を安全に中断する唯一の方法は 0 以外の値を
       fn() の返り値とすることである。割り込みを扱うには、 例えば発生した割り込みをマークしておい
       て、 0 以外の値を返すようにする シグナルによりメモリーリークを起こさずに探索を終了できるよ
       うにするには、  シグナルハンドラーで fn() がチェックするグローバルなフラグをセットするよう
       にすればよい。 プログラムを終了させる場合以外は、 longjmp(3)  を使用しないこと。

   nftw()
       関数 nftw()  は ftw()  と同じだが、引き数 flags が追加される点と、 fn()  の引き数に ftwbuf
       が追加される点が異なる。

       この flags 引き数は下記のフラグの 0 個以上の論理和を取ったものである:

       FTW_ACTIONRETVAL (glibc 2.3.3 以降)
              このフラグは  glibc 固有である。 このフラグをセットすると、 nftw()  の fn()  の返り
              値の扱いが変わる。 fn() は以下の値のいずれか一つを返す必要がある。

              FTW_CONTINUE
                     nftw()  は通常通り処理を続ける。

              FTW_SKIP_SIBLINGS
                     fn()  がこの値を返した場合、処理中のエントリーの兄弟  (同じ階層のエントリー)
                     の処理はスキップされ、親ディレクトリで続きの処理が行われる。

              FTW_SKIP_SUBTREE
                     fn()   が呼び出されたエントリーがディレクトリ  (typeflagFTW_D)  の場合
                     に、この値を返すと fn() の引き数として渡されたディレクトリ内のエントリーの処
                     理が行われなくなる。  nftw()  は処理中のディレクトリの兄弟 (同じ階層のエント
                     リー) から処理を続ける。

              FTW_STOP
                     nftw () は、返り値 FTW_STOP ですぐに復帰する。

              他の返り値は将来新しい動作に対応付けられる可能性がある。 fn()  は上記のリストにある
              値以外を返さないようにすべきである。

              <ftw.h>FTW_ACTIONRETVAL の定義が有効にするためには、 (「どの」ヘッダーファイル
              をインクルードするよりも前に)   機能検査マクロ  _GNU_SOURCE  を定義しなければならな
              い。

       FTW_CHDIR
              セットされると、ディレクトリの内容を処理する前に  そのディレクトリに  chdir(2)   す
              る。このフラグは、 fpath が属すディレクトリで何らかの動作を実行する必要がある場合に
              便利である。 (このフラグを指定しても fnfpath 引き数で渡されるパス名には影響しな
              い。)

       FTW_DEPTH
              セットされると、帰りがけ順探索 (post-order traversal) を行う。 つまり、ディレクトリ
              そのものを引き数とした  fn() 呼出しは、そのディレクトリに含まれるファイルとサブディ
              レクトリに  対する処理の「後で」行われる  (デフォルトでは、ディレクトリ自身の処理は
              ディレクトリ内のエントリー より「前に」行なわれる)。

       FTW_MOUNT
              セットされると、同じファイルシステムの中だけを探索対象とする  (つまり、マウントポイ
              ントをまたぐことはない)。

       FTW_PHYS
              セットされると、シンボリックリンクを辿らない (おそらくこちらが 通常望ましい動作だろ
              う)。セットされていないとシンボリックリンクを  辿るが、同じファイルが二回報告される
              ことはない。

              FTW_PHYS がセットされずに FTW_DEPTH  がセットされると、自分自身に対するシンボリック
              リンクを配下に持つ ディレクトリに対して fn()  が呼び出されることは決してない。

       ディレクトリツリーのエントリー毎に、  nftw()  は 4つの引き数で fn()  を呼び出す。 fpathsbftw()  と同じである。 typeflag には、 ftw()   で取り得る値のいずれか、または以下の値
       のいずれかが渡される:

       FTW_DP fpath  がディレクトリで、かつ  flagsFTW_DEPTH  が指定されていた (FTW_DEPTHflags に指定されていなかった場合、 ディレクトリに対しては常に typeflagFTW_Dfn() が呼び出される)。 fpath 配下のファイルとサブディレクトリは全て処理が終わってい
              る。

       FTW_SL fpath がシンボリックリンクで、かつ FTW_PHYSflags に セットされていた。

       FTW_SLN
              fpath がシンボリックリンクで、存在しないファイルを指している  (これがセットされるの
              は FTW_PHYS がセットされていない場合だけである)。

       nftw()  が fn()  を呼び出す際に渡す 4つめの引き数は FTW 型の構造体である。

           struct FTW {
               int base;
               int level;
           };

       base  は、ファイル名 (basename 要素) の、 fpath で渡されるパス名の中でのオフセットである。
       level はディレクトリツリーでの fpath の深さを示す。深さはディレクトリツリーのトップ (root)
       からの 相対値である (dirpath は深さ 0 である)。

返り値

       これらの関数は、成功すると 0 を、エラーが発生すると -1 を返す。

       fn()   が  0 以外を返した場合、ディレクトリツリーの探索を終了し、 fn()  が返した値を ftw()
       や nftw()  の結果として返す。

       nftw()  が FTW_ACTIONRETVAL フラグ付きで呼ばれた場合、ツリーの探索を終了させるために  fn()
       が使用できる、非 0 の値は FTW_STOP だけであり、 この値は nftw()  の返り値として返される。

バージョン

       nftw() は バージョン 2.1 以降の glibc で利用できる。

準拠

       POSIX.1-2001, SVr4, SUSv1.  POSIX.1-2008 は ftw()  を廃止予定としている。

注意

       POSIX.1-2001 の注記によると、 fn がカレントワーキングディレクトリを保持しなかった場合の 結
       果は規定されていないとされている。

       nftw()  関数と、 ftw()  における FTW_SL は、SUSv1 で導入された。

       ftw()  で FTW_SL を一切使わないシステムや、 存在しないファイルを指しているシンボリックリン
       クの場合にのみ   FTW_SL   を使うシステム、また  ftw()   が全てのシンボリックリンクに対して
       FTW_SL を使うシステムもある。 予測可能な動作をさせるためには、 nftw()  を使うこと。

       「stat できるがディレクトリではないオブジェクト」 (ファイル, シンボリックリンク, fifo  等)
       に対しては、すべて FTW_F が返される。

       FTW_ACTIONRETVAL は glibc 固有である。

       以下のプログラムは、一つ目のコマンドライン引き数を名前に持つパス以下の  ディレクトリツリー
       を探索する。引き数が指定されなかった場合は、  カレントディレクトリ以下を探索する。  各々の
       ファイルについて様々の情報が表示される。  二番目のコマンドライン引き数に文字を指定すること
       で、 nftw()  を呼び出す際に flags 引き数に渡す値を制御することができる。

   プログラムのソース
       #define _XOPEN_SOURCE 500
       #include <ftw.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>
       #include <stdint.h>

       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], 'd') != NULL)
               flags |= FTW_DEPTH;
           if (argc > 2 && strchr(argv[2], 'p') != NULL)
               flags |= FTW_PHYS;

           if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
                   == -1) {
               perror("nftw");
               exit(EXIT_FAILURE);
           }
           exit(EXIT_SUCCESS);
       }

関連項目

       stat(2), fts(3), readdir(3)

この文書について

       この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部  である。プロジェクト
       の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。