名前

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

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 がディレクトリで、かつ flags で FTW_DEPTH が指定されていた (FTW_DEPTH が flags に指定されていなかった場合、 ディレクトリに対しては常に typeflag が FTW_D で fn() が呼び出される)。 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_PHYS が flags に セットされていた。

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_CHDIR

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

FTW_DEPTH

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

FTW_MOUNT

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

FTW_PHYS

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

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

返り値

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

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

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

バージョン

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

属性

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

準拠

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