man fts_read (3): ファイル階層をたどる

Other Alias

fts, fts_open, 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 でコンパイルする場合など)、安全ではない。

この文書について

この man ページは Linux man-pages プロジェクトのリリース 3.65 の一部である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。

書式

説明