FTS

名前

書式

#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);

説明

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 フィールドはディレクトリメンバーの NUL 終端されたリンクリストの形式で、 次の構造体を指し示す。 それ以外の場合、 fts_link フィールドは定義されない。

fts_cycle

2 つのディレクトリにハードリンクが張られているため、 または、シンボリックリンクがあるディレクトリを指しているために、 ディレクトリが循環する階層構造を作っている場合 (FTS_DC を参照)、 構造体の fts_cycle フィールドは、階層中で現在の FTSENT 構造体と同じファイルを参照している FTSENT 構造体を指し示す。 それ以外の場合、 fts_cycle フィールドは定義されない。

fts_statp

このファイルの stat(2) 情報へのポインタ。

ファイル階層中のすべてのファイルのパスに対して、 ただ 1 つのバッファーが使われる。 したがって、 fts_path と fts_accpath フィールドは、 fts_read() によって返された最も新しいファイルに対して「のみ」 NULL 終端されることが保証される。 これらのフィールドを、他の FTSENT 構造体で表現されるファイルを参照するために使うには、 FTSENT 構造体の fts_pathlen フィールドにある情報を使ってパスのバッファーを修正する必要がある。 これらの修正は、さらに fts_read() を呼び出そうとする場合には、元に戻しておかなければならない。 fts_name フィールドは、常に NUL 終端される。  

fts_open()

多くのオプションがあり、少なくとも 1 つ (FTS_LOGICAL または FTS_PHYSICAL) が指定されなければならない。 次のオプションが or をとって選択される。

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() は 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_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_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() が失敗した場合、 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

オプションが無効であった。

バージョン

準拠

関連項目

Index

名前

書式

説明

fts_open()

fts_read()

fts_children()

fts_set()

fts_close()

エラー

バージョン

準拠

関連項目