名称

ftw, nftw — ファイルツリーを横断 (歩き回る) する

書式

#include < ftw.h>

int
ftw( const char *path, int (*fn)(const char *, const struct stat *, int), int maxfds);

int
nftw( const char *path, int (*fn)(const char *, const struct stat *, int, struct FTW *), int maxfds, int flags);

解説

ftw() と nftw() 関数は path をルート (根) としてディレクトリの階層構造を横断 (歩き回る) します。階層構造の各オブジェクト毎に、これらの関数は fn で指された関数を呼び出します。 ftw() 関数はオブジェクトの名前、オブジェクトに対応する stat 構造体へのポインタと整数フラグを含む ヌル文字 で終了する文字列へのポインタをこの関数に渡します。 nftw() 関数は前述の引数と < ftw.h> (下記で示します) によって定義された FTW 構造体へのポインタを渡します:

struct FTW { 
    int base; /* パス名中の basename のオフセット */ 
    int level; /* 出発点と相対的なディレクトリの深さ */ 
};

fn に渡されたフラグのためのあり得る値は次の通りです:

FTW_F

通常のファイル。

FTW_D

前の順序で訪問されるディレクトリ。

FTW_DNR

読み込むことができないディレクトリ。ディレクトリの中に降りられません。

FTW_DP

後の順序で訪問されるディレクトリ ( nftw() のみ)。

FTW_NS

stat(2) 情報が利用可能でないファイル。 stat 構造体の内容は未定義です。

FTW_SL

シンボリックリンク。

FTW_SLN

実在しないターゲットのシンボリックリンク ( nftw() のみ)。

ftw() 関数は前の順序でツリーを横断します。すなわち、ディレクトリの中身の前にそのディレクトリを処理します。

maxfds 引数は、ツリーを横断している間にオープンされた状態にしておくファイル記述子の最大の数を指定します。この実装では効果がありません。

nftw() 関数には、次のあり得る値の追加 flags 引数があります:

FTW_PHYS

物理的な歩き回りで、シンボリックリンクをたどりません。

FTW_MOUNT

歩きはマウントポイントに交差しません。

FTW_DEPTH

後の順序でディレクトリを処理します。ディレクトリの中身がディレクトリ自体の前に訪問されます。デフォルトで、 nftw() は前の順序でツリーを横断します。

FTW_CHDIR

それを読み込む前に、ディレクトリを変更します。デフォルトで、 nftw() は開始するディレクトリを変更します。カレントワーキングディレクトリは nftw() が返る前に元の位置に復元されます。

戻り値

ツリーの横断が成功するなら、 ftw() と nftw() 関数は 0 を返します。 fn によって指された関数が 0 以外を返すなら、 ftw() と nftw() はツリーの処理を止めて、 fn から返される値を返します。両方の関数はエラーが検出されたなら、-1 を返します。

エラー

ftw() と nftw() 関数は、失敗すると、ライブラリ関数の close(2), open(2), stat(2), malloc(3), opendir(3) と readdir(3) で明記されたエラーのいずれかが errno に設定されます。 FTW_CHDIR フラグが設定されるなら、 nftw() 関数は、失敗すると、 chdir(2) で明記されたエラーのいずれかが errno に設定されます。さらに、どちらの関数も、失敗すると、次を errno に設定するかもしれません:

[ EINVAL]

maxfds 引数が 1 未満です。

関連項目

chdir(2), close(2), open(2), stat(2), fts(3), malloc(3), opendir(3), readdir(3)

規格

ftw() と nftw() 関数は IEEE Std 1003.1-2001 (“POSIX.1”) に適合しています。

歴史

これらの機能は、 AT&T System V Release 3 UNIX ではじめて登場しました。それらの最初の FreeBSD での登場は、 FreeBSD 5.3 です。

バグ

maxfds 引数は現在、無視されます。