FTS

Section: C Library Functions (3)
索引 jman

BSD mandoc

索引

名称

fts - ファイルの階層を横断する

索引

ライブラリ

Lb libc

索引

書式

In sys/types.h In sys/stat.h In fts.h Ft FTS * Fn fts_open char * const *path_argv int options int (*compar)(const FTSENT **, const FTSENT **) Ft FTSENT * Fn fts_read FTS *ftsp Ft FTSENT * Fn fts_children FTS *ftsp int options Ft int Fn fts_set FTS *ftsp FTSENT *f int options Ft int Fn fts_close FTS *ftsp

索引

解説

は、 UNIX ファイル階層を横断するための関数です。簡単に説明すると、 Fn fts_open 関数はファイル階層の ``ハンドル'' を戻します。このハンドルは、その他の関数に指定できます。 Fn fts_read 関数は、ファイル階層の 1 つのファイルを表す構造体のポインタを戻します。 Fn fts_children 関数は、構造体のリンクリストへのポインタを戻します。各構造体は、その階層のあるディレクトリに含まれるファイル 1 つを表します。一般に、ディレクトリは、正順 (いずれの子にアクセスする前) と逆順 (すべての子にアクセスした後) の 2 回アクセスされます。ファイルは 1 回アクセスされます。シンボリックリンクを無視した、階層への ``論理的な'' アクセス、シンボリックリンクをたどる、階層への物理的なアクセス、階層へのアクセス命令、階層の一部の切り離しや再アクセスが可能です。

インクルードファイル Aq Pa fts.h には、2 つの構造体が定義されて (かつ、typedef 型定義もされて) います。 1 つは、ファイル階層そのものを表す構造体 Fa FTS です。もう 1 つは、ファイル階層のファイル 1 つを表す構造体 Fa FTSENT です。通常は、ファイル階層のファイルすべてについて、構造体 Fa FTSENT が 1 つ戻されます。このマニュアルページでは、 ``ファイル'' と ``Fa FTSENT 構造体 '' は、ほぼ同じ意味を持ちます。 Fa FTSENT 構造体には、少なくとも以下に示すフィールドを含みます。それぞれのフィールドについては、後で詳しく説明します。

typedef struct _ftsent {
        u_short fts_info;               /* flags for FTSENT structure */
        char *fts_accpath;              /* access path */
        char *fts_path;                 /* root path */
        u_short fts_pathlen;            /* strlen(fts_path) */
        char *fts_name;                 /* file name */
        u_short fts_namelen;            /* strlen(fts_name) */
        short fts_level;                /* depth (-1 to N) */
        int fts_errno;                  /* file errno */
        long fts_number;                /* local numeric value */
        void *fts_pointer;              /* local address value */
        struct ftsent *fts_parent;      /* parent directory */
        struct ftsent *fts_link;        /* next file structure */
        struct ftsent *fts_cycle;       /* cycle structure */
        struct stat *fts_statp;         /* stat(2) information */
} FTSENT;

これらのフィールドは、以下のように定義されています。

Fa fts_info

戻された Fa FTSENT 構造体とそれが表すファイルを記述します。以下のうち 1 つの値を取ります。エラーのないディレクトリ (FTS_D ) を除けば、すべてのエントリは終端です。つまり、再アクセスされることはなく、子がアクセスされることもありません。

FTS_D: 正順でアクセスされるディレクトリです。
FTS_DC: ツリーでの循環の原因となるディレクトリです。 ( Fa FTSENT 構造体の Fa fts_cycle フィールドにも同様にこの情報が入ります。)
FTS_DEFAULT: 他のどの Fa fts_info の値でも明確に表さないファイルタイプを表す Fa FTSENT 構造体です。
FTS_DNR: 読み込めないディレクトリです。これはエラーリターンで、 Fa fts_errno フィールドにエラーの原因を表す値が設定されます。
FTS_DOT: Fn fts_open にファイル名として指定されていない、 `.' や、 `..' という名前を持つファイルです ( FTS_SEEDOT を参照)。
FTS_DP: 逆順でアクセスされるディレクトリです。正順 (つまり、 Fa fts_info フィールドに FTS_D が設定された場合) で戻ってきた時は、 Fa FTSENT 構造体の内容は変更されていません。
FTS_ERR: これはエラーリターンであり、 Fa fts_errno フィールドにエラーの原因が設定されます。
FTS_F: 通常ファイルです。
FTS_NS: stat(2) で情報が取得できないファイルです。 Fa fts_statp フィールドの内容は未定義になります。これはエラーリターンであり、 Fa fts_errno フィールドにエラーの原因を表す値が設定されます。
FTS_NSOK: stat(2) での情報取得を要求しないファイルです。 Fa fts_statp フィールドの内容は不定になります。
FTS_SL: シンボリックリンクです。
FTS_SLNONE: ターゲットが存在しないシンボリックリンクです。 Fa fts_statp フィールドの内容は、そのシンボリックリンク自体のファイル特性情報を参照します。

Fa fts_accpath

カレントディレクトリからファイルにアクセスするためのパスです。

Fa fts_path

横断のルートからの、ファイルの相対パスです。このパスには、 Fn fts_open に指定したパスが接頭語として含まれます。

Fa fts_pathlen

Fa fts_path が参照する文字列の長さです。

Fa fts_name

ファイルの名前です。

Fa fts_namelen

Fa fts_name が参照する文字列の長さです。

Fa fts_level

このファイルが見つかった場所の、この横断における深さです。この深さは -1 から N までの番号が付けられます。横断の開始点の親 (またはルート) を表す Fa FTSENT 構造体には、番号 FTS_ROOTPARENTLEVEL (-1) が付されます。ルートの Fa FTSENT 構造体には、番号 FTS_ROOTLEVEL (0) が付されます。

Fa fts_errno

関数 Fn fts_children もしくは Fn fts_read が構造体 Fa FTSENT を戻すに際し、 Fa fts_info フィールドに FTS_DNR FTS_ERR FTS_NS のいずれかが設定された状態の場合は、 Fa fts_errno フィールドは、エラーの原因を示す外部変数 errno の値を含みます。その他の場合、 Fa fts_errno フィールドの内容は未定義です。

Fa fts_number

このフィールドは、アプリケーションプログラムで使用するためのもので、関数群はこのフィールドを変更しません。このフィールドは 0 で初期化されています。

Fa fts_pointer

このフィールドは、アプリケーションプログラムで使用するためのもので、関数群はこのフィールドを修正しません。このフィールドは NULL で初期化されています。

Fa fts_parent

このファイルがメンバとなっているディレクトリのように、現在着目しているファイルのすぐ上の階層にあるファイルを参照する Fa FTSENT 構造体のポインタです。初期エントリポイントの親構造体も提供されますが、 Fa fts_level フィールド、 Fa fts_number フィールド、 Fa fts_pointer フィールドの初期化しか保証されません。

Fa fts_link

Fn fts_children 関数から戻ると、 Fa fts_link フィールドは、ディレクトリのメンバを表す、ナル終端されたリンクリストの中の次の構造体を指します。その他の場合、 Fa fts_link フィールドの内容は未定義です。

Fa fts_cycle

ディレクトリ 2 つの間のハードリンクや、ディレクトリを指すシンボリックリンクにより、あるディレクトリが階層構造の中で循環の原因となっている場合 ( FTS_DC 参照)、この構造体の Fa fts_cycle フィールドは、この階層構造の中で、現在の Fa FTSENT 構造体と同じファイルを参照する Fa FTSENT 構造体を指します。その他の場合、 Fa fts_cycle フィールドの内容は未定義です。

Fa fts_statp

ファイルの stat(2) の情報を指すポインタです。

ファイル階層にある全ファイルのすべてのパスに対し、1 つのバッファを使用します。このため、 Fa fts_path フィールドと Fa fts_accpath フィールドは、 NUL 終端されている ことが保証されるのは、 Fn fts_read が最後に戻したファイルのみです。他の Fa FTSENT 構造体が表すファイルを参照するために、このフィールドを使用するためには、その Fa FTSENT 構造体の Fa fts_pathlen フィールドに含まれる情報でパスバッファを修正する必要があります。 Fn fts_read をさらに呼び出す前に、このような修正を元に戻しておく必要があります。 Fa fts_name フィールドは、常に NUL 終端されています。

索引

FTS_OPEN

関数 Fn fts_open は、横断対象の論理ファイル階層を構成する 1 つ以上のパスを指定する文字型ポインタの配列を指すポインタを取ります。配列は、 NULL ポインタで終わっている必要があります。

数多くのオプションがありますが、最低でも次のうち 1 つ ( FTS_LOGICAL か FTS_PHYSICAL を指定する必要があります。オプションは、以下の値の論理和を取ることで選択されます。

FTS_COMFOLLOW: このオプションを指定すると、 FTS_LOGICAL が指定されているかどうかに関わらず、ルートパスとして指定されたシンボリックリンクがすぐにたどられます。
FTS_LOGICAL: このオプションを指定すると、ルーチンは、シンボリックリンクそのものではなく、シンボリックリンクのターゲットの Fa FTSENT 構造体を戻すようになります。このオプションを設定すると、アプリケーションに戻される Fa FTSENT 構造体が指すシンボリックリンクは、存在しないファイルを参照するものだけになります。 Fn fts_open 関数には、 FTS_LOGICAL か FTS_PHYSICAL を指定する必要があります。
FTS_NOCHDIR: パフォーマンスを最適化するため、関数は、ファイル階層のアクセス中にカレントディレクトリを変更します。これには、横断中にどのディレクトリにいるかがアプリケーションで特定できないという副作用があります。 FTS_NOCHDIR オプションはこの最適化を無効にするので、関数はカレントディレクトリを変更しなくなります。 FTS_NOCHDIR を指定していない、もしくは、 Fn fts_open に絶対パス名を引数として指定していない場合は、アプリケーションでカレントディレクトリを変更したり、ファイルにアクセスしたりしないでください。
FTS_NOSTAT: デフォルトでは、戻される Fa FTSENT 構造体は、アクセスしたファイルそれぞれについてファイル特性情報 ( Fa statp フィールド) を参照しています。このオプションは、パフォーマンスを最適化するためにこの要件を緩和し、関数が Fa fts_info フィールドに FTS_NSOK を設定して、 Fa statp フィールドの内容を未定義のままにすることを許可します。
FTS_PHYSICAL: このオプションを指定すると、ルーチンは、シンボリックリンクが指すターゲットファイルではなく、シンボリックリンク自体の Fa FTSENT 構造体を戻すようになります。このオプションを設定すると、階層に存在するすべてのシンボリックリンクの Fa FTSENT 構造体がアプリケーションに戻されます。 Fn fts_open 関数には、 FTS_LOGICAL か FTS_PHYSICAL を指定する必要があります。
FTS_SEEDOT: デフォルトでは、 Fn fts_open のパス引数として指定しない限り、ファイル階層に存在する、 `.' もしくは、 `..' という名前のファイルは無視されます。このオプションを指定することにより、ルーチンは、このようなファイルの Fa FTSENT 構造体を戻すようになります。
FTS_XDEV: このオプションを指定すると、は、下降を始めたファイルと異なるデバイス番号を持つディレクトリに下降しません。

引数 Fn compar は、階層横断の順序決めに使用されるユーザ定義関数を指定します。この関数は、 Fa FTSENT 構造体のポインタを指す 2 つのポインタを引数として取り、最初の引数が参照するファイルが、2 番目の引数が参照するファイルより前に来るか、前でも後ろでもどちらでも構わないか、後ろに来るかによって、それぞれ負の値、0、正の値を戻さねばなりません。この比較では、 Fa FTSENT 構造体の Fa fts_accpath , Fa fts_path , Fa fts_pathlen フィールドを 絶対に 使用してはいけません。 Fa fts_info フィールドに FTS_NS か FTS_NSOK が設定されている場合、 Fa fts_statp フィールドも使用してはなりません。引数 Fn compar が NULL である場合、ディレクトリ横断順序は、ルートパスでは Fa path_argv でリストされる順序に、その他すべての場所では、ディレクトリでリストされている順序になります。

索引

FTS_READ

Fn fts_read 関数は、階層のファイルを表す Fa FTSENT 構造体のポインタを戻します。ディレクトリ (読込み可能で循環の原因とならないもの) は、正順探索時に 1 回と逆順探索時に 1 回、少なくとも 2 回アクセスされます。その他すべてのファイルは、最低 1 回アクセスされます。 (ディレクトリ間のハードリンクで循環の原因とならないもの、またはシンボリックリンクに対するシンボリックリンクは、ファイルの場合、 1 回以上アクセスされる原因となり、ディレクトリの場合、 2 回以上アクセスされたりする原因となることがあります。)

階層のすべてのメンバが戻されると、 Fn fts_read は NULL を戻し、外部変数 errno に 0 を設定します。階層中のファイルと無関係なエラーが発生すると、 Fn fts_read は NULL を戻し、 errno に適切な値を設定します。戻されるファイルに関係するエラーが発生すると、 Fa FTSENT 構造体のポインタが戻され、 errno は設定されたり設定されなかったりします ( Fa fts_info 参照)。

Fn fts_read が戻す Fa FTSENT 構造体は、同じファイル階層ストリームに対して Fn fts_close を呼び出した後、もしくは、その構造体がディレクトリ型ファイルを表していない場合に同じファイル階層ストリームに対して Fn fts_read を呼び出した後、上書きされることがあります。どちらの場合でも、逆順探索の際に Fn fts_read が Fa FTSENT を返した後に Fn fts_read を呼び出すまでは、 Fa FTSENT 構造体は上書きされません。

索引

FTS_CHILDREN

関数 Fn fts_children は、 Fn fts_read が最近戻した Fa FTSENT 構造体が表すディレクトリのファイルの NULL で終わるリンクリストの最初のエントリである Fa FTSENT 構造体のポインタを戻します。リストは、 Fa FTSENT 構造体の Fa fts_link フィールドでリンクされ、ユーザ定義比較関数がある場合は、それで順序付けられます。 Fn fts_children を繰り返し呼び出すと、このリンクリストはそのたびに再作成されます。

特別な場合として、その階層で Fn fts_read がまだ呼び出されていない場合、 Fn fts_children は、 Fn fts_open に指定された論理ディレクトリにあるファイル (すなわち、 Fn ftp_open に指定された引数) を指すポインタを戻します。 Fn fts_read がすでに呼び出されているときに、 Fn fts_read が最近戻した Fa FTSENT 構造体が、正順探索でアクセスされたディレクトリでないか、ディレクトリにファイルが含まれていない場合、 Fn fts_children は NULL を戻し、 errno に 0 を設定します。エラーが発生すると、 Fn fts_children は NULL を戻し、 errno に適切な値を設定します。

Fn fts_children が戻す Fa FTSENT 構造体は、同じファイル階層ストリームを使用した Fn fts_children , Fn fts_close , Fn fts_read の呼び出しの後、上書きされることがあります。

option には、以下の値を設定できます。

FTS_NAMEONLY: ファイルの名前だけが必要であることを示します。戻された構造体のリンクリストに存在するすべてのフィールドの内容は、 Fa fts_name フィールドと Fa fts_namelen フィールドを除いて未定義になります。

索引

FTS_SET

関数 Fn fts_set により、ストリーム Fa ftsp のファイル Fa f に対して、さらに行なう処理をユーザアプリケーションが決めることができます。 Fn fts_set 関数は、問題がなければ 0 を戻し、エラーが発生した場合は -1 を戻します。 option として、以下のうちの 1 つの値を設定する必要があります。

FTS_AGAIN: ファイルを再アクセスします。どのようなファイルタイプのファイルも再アクセスされる可能性があります。その次に Fn fts_read を呼び出すことで、参照されたファイルが戻されます。そのとき、構造体の Fa fts_stat フィールドと Fa fts_info フィールドが再び初期化されますが、その他のフィールドは変更されません。このオプションは、 Fn fts_read が最近戻したファイルに対してのみ意味を持ちます。通常の場合は逆順ディレクトリアクセスに使用します。この場合はディレクトリが正順と逆順の両方で再アクセスされ、その子すべても再アクセスされます。
FTS_FOLLOW: 参照するファイルは、シンボリックリンクである必要があります。参照するファイルが、 Fn fts_read で最近戻されたものである場合、次に Fn fts_read を呼び出すと、 Fa fts_info フィールドと Fa fts_statp フィールドが初期化され、シンボリックリンク自体ではなくシンボリックリンクのターゲットを指した状態でファイルが戻されます。ファイルが Fn fts_children で最近戻されたものである場合、構造体の Fa fts_info フィールドと Fa fts_statp フィールドは、 Fn fts_read で戻されると、シンボリックリンク自体ではなくシンボリックリンクのターゲットを反映します。どちらの場合でも、シンボリックリンクのターゲットが存在しなければ、戻される構造体のフィールドは変更されず、 Fa fts_info フィールドは FTS_SLNONE に設定されます。
リンクのターゲットがディレクトリである場合は、正順探索でのリターン、すべての子孫のリターン、逆順探索のリターンがこの順序で実行されます。
FTS_SKIP: このファイルの子はアクセスされません。ここで指定するファイルとして、 Fn fts_children か Fn fts_read が最近戻したものどちらかが可能です。

索引