Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all 
名前
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 がディレクトリで、かつ 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_CONTINUE
nftw() は通常通り処理を続ける。
FTW_SKIP_SIBLINGS
fn() がこの値を返した場合、処理中のエントリーの兄弟 (同じ階層のエントリー)
の処理はスキップされ、親ディレクトリで続きの処理が行われる。
FTW_SKIP_SUBTREE
fn() が呼び出されたエントリーがディレクトリ (typeflag が FTW_D) の場合
に、この値を返すと fn() の引数として渡されたディレクトリ内のエントリーの処理
が行われなくなる。 nftw() は処理中のディレクトリの兄弟 (同じ階層のエント
リー) から処理を続ける。
FTW_STOP
nftw () は、返り値 FTW_STOP ですぐに復帰する。
他の返り値は将来新しい動作に対応付けられる可能性がある。 fn() は上記のリストにある
値以外を返さないようにすべきである。
<ftw.h> で FTW_ACTIONRETVAL の定義が有効にするためには、 (「どの」ヘッダーファイル
をインクルードするよりも前に) 機能検査マクロ _GNU_SOURCE を定義しなければならな
い。
FTW_CHDIR
セットされると、ディレクトリの内容を処理する前に そのディレクトリに chdir(2) す
る。このフラグは、 fpath が属すディレクトリで何らかの動作を実行する必要がある場合に
便利である。 (このフラグを指定しても fn の fpath 引数で渡されるパス名には影響しな
い。)
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/ に書かれている。