plucky (3) nftw.3.gz

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/ に書かれている。