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