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

名前

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

書式

       #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);

       #include <ftw.h>

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

   glibc 向けの機能検査マクロの要件 (feature_test_macros(7)  参照):

       nftw(): _XOPEN_SOURCE >= 500

説明

       nftw()   walks through the directory tree that is located under the directory dirpath, and
       calls fn() once for each entry in the tree.  By default, directories  are  handled  before
       the files and subdirectories they contain (preorder traversal).

       To  avoid  using  up  all of the calling process's file descriptors, nopenfd specifies the
       maximum number of directories that nftw()  will hold open simultaneously.  When the search
       depth  exceeds  this, nftw()  will become slower because directories have to be closed and
       reopened.  nftw()  uses at most one file descriptor for each level in the directory tree.

       For each entry found in the tree, nftw()  calls  fn()  with  four  arguments:  fpath,  sb,
       typeflag,  and  ftwbuf.   fpath is the pathname of the entry, and is expressed either as a
       pathname relative to the calling process's current working directory at the  time  of  the
       call  to  nftw(),  if  dirpath  was  expressed  as  a relative pathname, or as an absolute
       pathname, if dirpath was expressed as an absolute pathname.  sb is a pointer to  the  stat
       structure returned by a call to stat(2) for fpath.

       The typeflag argument passed to fn()  is an integer that has one of the following values:

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

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

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

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

       FTW_NS The stat(2)  call failed on fpath, which is not  a  symbolic  link.   The  probable
              cause  for  this is that the caller had read permission on the parent directory, so
              that the filename fpath could be seen, but did not have execute permission, so that
              the  file  could not be reached for stat(2).  The contents of the buffer pointed to
              by sb are undefined.

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

       FTW_SLN
              fpath is a symbolic link pointing to a nonexistent  file.   (This  occurs  only  if
              FTW_PHYS  is  not  set.)   In  this  case  the sb argument passed to fn()  contains
              information returned by performing lstat(2)  on the "dangling" symbolic link.  (But
              see BUGS.)

       The  fourth  argument (ftwbuf)  that nftw()  supplies when calling fn()  is a pointer to a
       structure of type FTW:

           struct FTW {
               int base;
               int level;
           };

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

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

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

       The flags argument of nftw()  is formed by ORing zero or more of the following flags:

       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()  が呼び出されることは決してない。

   ftw()
       ftw()  is an older function that offers a subset of  the  functionality  of  nftw().   The
       notable differences are as follows:

       *  ftw()   has no flags argument.  It behaves the same as when nftw() is called with flags
          specified as zero.

       *  The callback function, fn(), is not supplied with a fourth argument.

       *  The range of values that is passed via the  typeflag  argument  supplied  to  fn()   is
          smaller: just FTW_F, FTW_D, FTW_DNR, FTW_NS, and (possibly)  FTW_SL.

返り値

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

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

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

バージョン

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

属性

       この節で使用されている用語の説明については、 attributes(7) を参照。

       ┌─────────────────┬───────────────┬─────────────┐
       │インターフェース属性          │
       ├─────────────────┼───────────────┼─────────────┤
       │nftw()           │ Thread safety │ MT-Safe cwd │
       ├─────────────────┼───────────────┼─────────────┤
       │ftw()            │ Thread safety │ MT-Safe     │
       └─────────────────┴───────────────┴─────────────┘

準拠

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

注意

       POSIX.1-2008  notes  that  the results are unspecified if fn does not preserve the current
       working directory.

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

       In some implementations (e.g., glibc), ftw()  will never  use  FTW_SL,  on  other  systems
       FTW_SL  occurs only for symbolic links that do not point to an existing file, and again on
       other systems ftw()  will use FTW_SL for each symbolic link.  If fpath is a symbolic  link
       and  stat(2)  failed, POSIX.1-2008 states that it is undefined whether FTW_NS or FTW_SL is
       passed in typeflag.  For predictable results, use nftw().

バグ

       According to POSIX.1-2008, when the typeflag argument passed to fn() contains FTW_SLN, the
       buffer  pointed  to  by  sb  should  contain  information about the dangling symbolic link
       (obtained by calling lstat(2)  on the link).  Early glibc versions correctly followed  the
       POSIX  specification  on  this  point.  However, as a result of a regression introduced in
       glibc 2.4, the contents of the buffer pointed to by sb  were  undefined  when  FTW_SLN  is
       passed  in  typeflag.   (More precisely, the contents of the buffer were left unchanged in
       this case.)  This regression was eventually  fixed  in  glibc  2.30,  so  that  the  glibc
       implementation (once more) follows the POSIX specification.

       以下のプログラムは、一つ目のコマンドライン引数を名前に持つパス以下の  ディレクトリツリーを
       探索する。引数が指定されなかった場合は、 カレントディレクトリ以下を探索する。 各々のファイ
       ルについて様々の情報が表示される。      二番目のコマンドライン引数に文字を指定することで、
       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 ",
                   (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);

           if (tflag == FTW_NS)
               printf("-------");
           else
               printf("%7jd", (intmax_t) sb->st_size);

           printf("   %-40s %d %s\n",
                   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 プロジェクトのリリース 5.10 の一部である。プロジェクトの
       説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。