Provided by: manpages-ja-dev_0.5.0.0.20210215+dfsg-1_all 
名前
fts, fts_open, fts_read, fts_children, fts_set, fts_close - ファイル階層をたどる
書式
#include <sys/types.h>
#include <sys/stat.h>
#include <fts.h>
FTS *fts_open(char * const *path_argv, int options,
int (*compar)(const FTSENT **, const FTSENT **));
FTSENT *fts_read(FTS *ftsp);
FTSENT *fts_children(FTS *ftsp, int options);
int fts_set(FTS *ftsp, FTSENT *f, int options);
int fts_close(FTS *ftsp);
説明
fts 関数群は、ファイル階層をたどるために提供されている。 簡単に概略すると次のようになる。 fts_open() 関
数は、他の fts 関数群に渡すための、ファイル階層の「ハンドル」を返す。 fts_read() 関数は、ファイル階層中
にある 1 つのファイルを記述する構造体へのポインターを返す。 fts_children() 関数は、階層中のディレクトリ
にあるファイルを記述する構造体の リンクリストへのポインターを返す。 一般にディレクトリは、 preorder (正方
向：下の階層のディレクトリをたどる前) と postorder (逆方向：下の階層のディレクトリをすべてたどった後) と
いう、 異なる方向で 2 回たどられる。ファイルは 1 回たどられる。 ディレクトリ階層を「論理的に」(シンボリッ
クリングが指すファイルを見て) 辿ることも、 物理的に (シンボリックリンク自身を見て) 辿ることも可能である。
また、階層中の移動の道筋を指示すること・ 余分なものを取り除くこと・階層の一部を再びたどることが可能であ
る。
2 つの構造体がインクルードファイル <fts.h> で定義されている (さらに typedef されている)。 1 つ目は、ファ
イル階層そのものを表現する FTS 構造体である。 2 つ目は、ファイル階層中のファイルを表現する FTSENT 構造体
である。 FTSENT 構造体は通常、ファイル階層中のすべてのファイルに対して返される。 この man ページでは、「
ファイル」と 「FTSENT 構造体」を一般に読み変えることができる。 FTSENT 構造体は、少なくとも次のような
フィールドを持っており、 以下でより詳しく説明されている。
typedef struct _ftsent {
unsigned short fts_info; /* FTSENT 構造体のためのフラグ */
char *fts_accpath; /* アクセスパス */
char *fts_path; /* ルートパス */
short fts_pathlen; /* fts_path の長さ */
char *fts_name; /* ファイル名 */
short fts_namelen; /* fts_name の長さ */
short fts_level; /* 深さ (-1 〜 N) */
int fts_errno; /* ファイルのエラー番号 */
long fts_number; /* ローカルな番号 */
void *fts_pointer; /* ローカルなアドレス番号 */
struct ftsent *fts_parent; /* 親ディレクトリ */
struct ftsent *fts_link; /* 次のファイル構造体 */
struct ftsent *fts_cycle; /* 循環している構造体 */
struct stat *fts_statp; /* stat(2) の情報 */
} FTSENT;
これらのフィールドは、次のように定義されている。
fts_info このフィールドは、返された FTSENT 構造体とファイルを説明する以下のフラグのいずれかを表してい
る。 エラーのないディレクトリ (FTS_D), の場合は例外として、それ以外のすべてのエントリーは終端
である。 つまり、エントリーは再びたどられることもなく、 それより下の階層がたどられることもな
い。
FTS_D preorder でたどられるディレクトリ。
FTS_DC ツリーの中で循環しているディレクトリ。 (FTSENT 構造体の fts_cycle フィールドも同
様に埋められる。)
FTS_DEFAULT ファイルタイプを表現する FTSENT 構造体が、 fts_info の他のいずれかの値で明示的に
説明されていない。
FTS_DNR 読み込みができないディレクトリ。 これはエラーの場合の返り値であり、 何がエラーを
起こしたかを示すために fts_errno フィールドが設定される。
FTS_DOT fts_open() へのファイル名として指定されなかった "." または ".." という名前のファ
イル (FTS_SEEDOT を参照すること)。
FTS_DP postorder でたどられるディレクトリ。 FTSENT 構造体の内容は、preorder のときに返さ
れた状態 (つまり、 fts_info フィールドが FTS_D に設定されている状態) から変更され
ない。
FTS_ERR これはエラーの場合の返り値であり、 fts_errno フィールドは、何がエラーを起こしたか
を示す値に設定される。
FTS_F 通常のファイル。
FTS_NS stat(2) 情報が得られなかったファイル。 fts_statp フィールドの内容は定義されな
い。 これはエラーの場合の返り値であり、 fts_errno フィールドは、何がエラーを起こ
したかを示す値に設定される。
FTS_NSOK stat(2) 情報が要求されなかったファイル。 fts_statp フィールドの内容は定義されな
い。
FTS_SL シンボリックリンク。
FTS_SLNONE リンク先の存在しないシンボリックリンク。 fts_statp フィールドの内容は、シンボリッ
クリンクそのもののファイル特性情報を参照する。
fts_accpath 現在のディレクトリからファイルにアクセスするためのパス。
fts_path 階層をたどるときのルートからみたファイルの相対的なパス。 このパスには、 fts_open() に指定し
たパスがプレフィックスとして含まれる。
fts_pathlen fts_path で参照される文字列の長さ。
fts_name ファイルの名前。
fts_namelen fts_name で参照される文字列の長さ。
fts_level 階層をたどって、このファイルがみつかった深さ。 -1 〜 N の数値で表される。 階層をたどるときの
出発点 (ルート) の親ディレクトリを表す FTSENT 構造体では -1 となる。 また、ルート自身の
FTSENT 構造体では 0 になる。
fts_errno 関数 fts_children() と fts_read() から返される FTSENT 構造体の fts_info フィールドが
FTS_DNR, FTS_ERR, FTS_NS に設定されている場合、 fts_errno フィールドにはエラーの原因を示す外
部変数 errno の値が入る。 それ以外の場合、 fts_errno フィールドの内容は定義されない。
fts_number このフィールドは、アプリケーションプログラムから使用するために提供され、 fts 関数群では変更さ
れない。 このフィールドは 0 で初期化される。
fts_pointer このフィールドは、アプリケーションプログラムから使用するために提供され、 fts 関数群では変更さ
れない。 このフィールドは NULL で初期化される。
fts_parent 現在のファイルのすぐ上の階層にあるファイル (つまり、現在のファイルがメンバーになっているディ
レクトリ) を参照する FTSENT 構造体へのポインター。 最初の出発点に対しても、親となる構造体は与
えられる。 しかし、 fts_level, fts_number, fts_pointer フィールドのみの初期化しか保証されな
い。
fts_link fts_children() から返される場合、 fts_link フィールドはディレクトリメンバーのヌル終端された
リンクリストの形式で、 次の構造体を指し示す。 それ以外の場合、 fts_link フィールドは定義され
ない。
fts_cycle 2 つのディレクトリにハードリンクが張られているため、 または、シンボリックリンクがあるディレク
トリを指しているために、 ディレクトリが循環する階層構造を作っている場合 (FTS_DC を参照)、 構
造体の fts_cycle フィールドは、階層中で現在の FTSENT 構造体と同じファイルを参照している
FTSENT 構造体を指し示す。 それ以外の場合、 fts_cycle フィールドは定義されない。
fts_statp このファイルの stat(2) 情報へのポインター。
ファイル階層中のすべてのファイルのパスに対して、 ただ 1 つのバッファーが使われる。 したがって、 fts_path
と fts_accpath フィールドは、 fts_read() によって返された最も新しいファイルに対して「のみ」ヌル終端される
ことが保証される。 これらのフィールドを、他の FTSENT 構造体で表現されるファイルを参照するために使うには、
FTSENT 構造体の fts_pathlen フィールドにある情報を使ってパスのバッファーを修正する必要がある。 これらの修
正は、さらに fts_read() を呼び出そうとする場合には、元に戻しておかなければならない。 fts_name フィールド
は、常に NUL 終端される。
fts_open()
fts_open() 関数は、文字列ポインターの配列へのポインターを引き数に取る。 この文字列ポインターは、論理ファ
イル階層をつくる 1 つ以上のパスの名前になる。 配列は、 null ポインターで終端されなければならない。
多くのオプションがあり、少なくとも 1 つ (FTS_LOGICAL または FTS_PHYSICAL) が指定されなければならない。
オプションは以下の値の論理和をとって選択する。
FTS_COMFOLLOW
このオプションは、 FTS_LOGICAL の指定にかかわらず、 ルートパスに指定されたシンボリックリンク
をすぐにたどらせる。
FTS_LOGICAL このオプションは、 fts ルーチンにシンボリックリンクそのものではなく、 シンボリックリンクが指
しているファイルの FTSENT 構造体を返させる。 このオプションが設定された場合、 FTSENT 構造体
がアプリケーションに返されるような シンボリックリンクのみが、存在しないファイルを参照してい
る。 FTS_LOGICAL または FTS_PHYSICAL のどちらかを、 fts_open() 関数に与えなければ「ならな
い」。
FTS_NOCHDIR パフォーマンスの最適化のため、 fts 関数群はファイル階層をたどるときディレクトリを変える。 こ
れには、階層をたどっている間は アプリケーションがある特定のディレクトリにいるということに 依
存できない、という副作用がある。 FTS_NOCHDIR オプションで最適化を無効にすると、 fts 関数群は
現在のディレクトリを変更しない。 FTS_NOCHDIR が指定され、かつ fts_open() の引き数として絶対
パス名が与えられたとき以外、アプリケーションは、 自らカレントディレクトリを変更したり、 ファ
イルにアクセスしたりすべきではない、という点に注意すること。
FTS_NOSTAT デフォルトでは、返された FTSENT 構造体は、たどられた各ファイルについてのファイル特徴情報 (
statp フィールド) を参照する。 このオプションは、 fts 関数群が fts_info フィールドを
FTS_NSOK に設定し statp の内容を定義されないままにすることを許すことにより、 パフォーマンス
の最適化に必要なものを緩和する。
FTS_PHYSICAL このオプションは、 fts ルーチンにシンボリックリンクが指しているファイルではなく、 シンボリッ
クリンク自身の FTSENT 構造体を返させる。 このオプションが設定されると、階層中のすべてのシン
ボリックリンクの FTSENT 構造体がアプリケーションに返される。 FTS_LOGICAL または FTS_PHYSICAL
のどちらかを fts_open() 関数に与えなければ「ならない」。
FTS_SEEDOT デフォルトでは、 fts_open() のパス引き数として指定されない限り、ファイル階層中にある "." ま
たは ".." という名前のファイルは無視される。 このオプションは、 fts ルーチンにこれらのファ
イルの FTSENT 構造体を返させる。
FTS_XDEV このオプションは、 fts が下り始めのファイルとは異なるデバイス番号を持っている ディレクトリに
下りるのを阻止する。
引き数 compar() は、階層をたどる順番を決めるのに使われるユーザー定義関数を指定する。 この関数は、引き数
として FTSENT 構造体のポインターのポインターを 2 つとり、 1 番目の引き数で参照されているファイルが 2 番目
の引き数で参照されているファイルより 前にある場合は負の値・同じ場合はゼロ・後にある場合は正の値を 返さな
ければならない。 FTSENT 構造体の fts_accpath, fts_path, fts_pathlen フィールドは、この比較に「絶対」使っ
てはいけない。 fts_info フィールドが FTS_NS または FTS_NSOK に設定される場合、 fts_statp フィールドはこれ
らのどちらでもない。 compar() 引き数が NULL の場合、ディレクトリをたどる順番は、ルートパスについては
path_argv のなかでリストされた順番で、 その他のファイルについてはディレクトリ内でリストされた順番となる。
fts_read()
fts_read() 関数は、階層中のファイルを記述する FTSENT 構造体へのポインターを返す。 (読み込み可能で、循環
していない) ディレクトリは、 1 回は preorder で、もう 1 回は postorder で、少なくとも 2 回たどられる。 他
のファイルは、少なくとも 1 回たどられる。 (ディレクトリ間のハードリンクによって 循環やシンボリックリンク
へのシンボリックリンクが起こらない場合、 ファイルは 2 回以上、ディレクトリは 3 回以上たどられる。)
階層中のすべてのメンバーが返された場合、 fts_read() は NULL を返し、外部変数 errno を 0 にする。 階層中
のファイルに関係しないエラーが起こった場合、 fts_read() は NULL を返し、 errno をエラーに対応した値にす
る。 階層中のファイルに関係したエラーが起こった場合、 FTSENT 構造体へのポインターが返され、 errno は設定
される場合と設定されない場合がある (fts_info を参照すること)。
fts_read() によって返される FTSENT 構造体は、同じファイル階層ストリームへの fts_close() の呼出しの後に上
書きされる。 また、同じファイル階層ストリームへの fts_read() の呼出しの後でも、構造体がディレクトリを表現
していない限り上書きされる。 この場合、 fts_read() 関数によって postorder で FTSENT 構造体が返された後、
fts_read() の呼出しがあるまで、 これらの構造体は上書きされない。
fts_children()
fts_children() 関数は、 FTSENT 構造体へのポインターを返す。 この構造体は、( fts_read() で最も新しく返さ
れた FTSENT 構造体で表現されるディレクトリにあるファイルの) ヌル終端されたリンクリストの最初のエントリー
を記述する。 このリストは、 FTSENT 構造体の fts_link フィールドを使ってリンクされ、 ユーザー指定の比較関
数がある場合は、それで順序づけられる。 fts_children() の呼出しを繰り返すことで、 このリンクリストは再生
成される。
特別な場合として、 fts_read() がファイル階層について呼ばれていない場合、 fts_children() は fts_open()
に指定された論理ディレクトリ (つまり、 fts_open() に指定された引き数) の中にあるファイルへのポインターを
返す。 それ以外の場合で、 fts_read() によって最も新しく返された FTSENT 構造体が preorder でたどられた
ディレクトリでない場合や 何も含んでいないディレクトリの場合は、 fts_children() は NULL を返し、 errno を
0 にする。 エラーが起こった場合、 fts_children() は NULL を返し、 errno をエラーに対応した値にする。
fts_children() によって返される FTSENT 構造体は、同じファイル階層ストリームへの fts_children(),
fts_close(), fts_read() の呼出しの後に上書きされる場合がある。
option は、次の値に設定できる。
FTS_NAMEONLY ファイル名のみが必要とされている。 返された構造体のリンクリストの fts_name, fts_namelen
フィールド以外の すべてのフィールドの内容は定義されない。
fts_set()
関数 fts_set() は、ユーザーアプリケーションが ストリーム ftsp のファイル f について更なる処理を決定する
こと許す。 fts_set() 関数は、成功した場合は 0 を、エラーが起こった場合は -1 を返す。 option は、次の値の
いずれか 1 つに設定されなければならない。
FTS_AGAIN ファイルを再びたどる。すべてのファイルタイプが再びたどられる。 次の fts_read() の呼出しによ
り、参照されているファイルが返される。 構造体の fts_stat, fts_info フィールドはこの時に初期
化されるが、他のフィールドは変更されない。 このオプションは、 fts_read() によって最も新しく
返されたファイルについてのみ意味を持つ。 通常は、postorder でディレクトリをたどる場合に使用
し、 その下の階層と同様に、 ディレクトリを (preorder と postorder の両方で) 再びたどらせる。
FTS_FOLLOW 参照されてるファイルは、シンボリックリンクでなければならない。 参照されているファイルが
fts_read() によって最も新しく返されたものである場合、次の fts_read() の呼出しでは、シンボ
リックリンクそのものではなく、 シンボリックリンクが指している先を反映するように fts_info,
fts_statp を再び初期化したファイルが返される。 ファイルが fts_children() によって最も新しく
返されたものの 1 つである場合、 fts_read() によって返されたとき、構造体の fts_info,
fts_statp フィールドは、シンボリックリンクそのものではなく、 シンボリックリンクが指している
先を反映する。 どちらの場合でも、シンボリックリンクが指している先がないときは、 返された構造
体のフィールドは変更されず、 fts_info フィールドが FTS_SLNONE に設定される。
リンク先がディレクトリの場合、 ファイルが preorder で返された後、下の階層のすべてファイルが
返され、 その後で postorder で返される。
FTS_SKIP このファイルの下の階層はたどられない。 このファイルは、 fts_children() または fts_read() の
どちらかによって最も新しく返されたものの 1 つである。
fts_close()
fts_close() 関数は、ファイル階層ストリーム ftsp を閉じる。そして、現在のディレクトリを ftsp を開くために
fts_open() が呼ばれたディレクトリに復元する。 fts_close() 関数は、成功した場合は 0 を、エラーが起こった
場合は -1 を返す。
エラー
関数 fts_open() が失敗した場合、 errno は、ライブラリ関数 open(2) と malloc(3) に対して指定されるエラー
に設定される。
関数 fts_close() が失敗した場合、 errno は、ライブラリ関数 chdir(2) と close(2) に対して指定されるエ
ラーに設定される。
関数 fts_read() と fts_children() が失敗した場合、 errno は、ライブラリ関数 chdir(2), malloc(3),
opendir(3), readdir(3), stat(2) に対して指定されるエラーに設定される。
更に、 fts_children(), fts_open(), fts_set() が失敗した場合、 errno が次の値にされる。
EINVAL オプションが無効であった。
バージョン
これらの関数は、Linux では glibc2 から使用可能である。
準拠
4.4BSD.
バグ
このマニュアルページで説明した API はいずれも、 LFS API を使うプログラムをコンパイルする場合 (例え
ば、-D_FILE_OFFSET_BITS=64 でコンパイルする場合など)、安全ではない。
関連項目
find(1), chdir(2), stat(2), ftw(3), qsort(3)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告
に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。
Linux 2014-03-18 FTS(3)