FTS(3) FreeBSD ライブラリ関数マニュアル FTS(3)
名称
fts − ファイルの階層を横断する |
ライブラリ
標準 C ライブラリ (libc, −lc) |
書式
#include <sys/types.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 は、 UNIX ファイル階層を横断するための関数です。簡単に説明すると、 fts_open() 関数はファイル階層の ‘‘ハンドル’’ を戻します。このハンドルは、 その他の fts 関数に指定できます。 fts_read() 関数は、ファイル階層の 1 つ のファイルを表す構造体のポインタを戻します。 fts_children() 関数は、構造 体のリンクリストへのポインタを戻します。各構造体は、その階層のあるディレ クトリに含まれるファイル 1 つを表します。一般に、ディレクトリは、正順 (い ずれの子にアクセスする前) と逆順 (すべての子にアクセスした後) の 2 回アク セスされます。ファイルは 1 回アクセスされます。シンボリックリンクを無視し た、階層への ‘‘論理的な’’ アクセス、シンボリックリンクをたどる、階層への 物理的なアクセス、階層へのアクセス命令、階層の一部の切り離しや再アクセス が可能です。 インクルードファイル 〈fts.h〉 には、2 つの構造体が定義されて (か つ、typedef 型定義もされて) います。 1 つは、ファイル階層そのものを表す構 造体 FTS です。もう 1 つは、ファイル階層のファイル 1 つを表す構造体 FTSENT です。通常は、ファイル階層のファイルすべてについて、構造体 FTSENT が 1 つ戻されます。このマニュアルページでは、 ‘‘ファイル’’ と ‘‘FTSENT 構 造体’’ は、ほぼ同じ意味を持ちます。 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; これらのフィールドは、以下のように定義されています。 |
fts_info
戻された FTSENT 構造体とそれが表すファイルを記述します。以下 のうち 1 つの値を取ります。エラーのないディレクトリ (FTS_D) を除けば、すべてのエントリは終端です。つまり、再アクセスされ ることはなく、子がアクセスされることもありません。 FTS_D FTS_DC FTS_DEFAULT FTS_DNR FTS_DOT FTS_DP FTS_ERR FTS_F FTS_NS FTS_NSOK FTS_SL FTS_SLNONE fts_accpath fts_path fts_pathlen fts_name fts_namelen fts_level fts_errno fts_number fts_pointer fts_parent fts_link fts_cycle fts_statp ファイル階層にある全ファイルのすべてのパスに対し、1 つのバッファを使用し ます。このため、 fts_path フィールドと fts_accpath フィールドは、 NUL終端 されていることが保証されるのは、 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_NOCHDIR FTS_NOSTAT FTS_PHYSICAL FTS_SEEDOT FTS_XDEV 引数 compar() は、階層横断の順序決めに使用されるユーザ定義関数を指定しま す。この関数は、 FTSENT 構造体のポインタを指す 2 つのポインタを引数として 取り、最初の引数が参照するファイルが、2 番目の引数が参照するファイルより 前に来るか、前でも後ろでもどちらでも構わないか、後ろに来るかによって、そ れぞれ負の値、0、正の値を戻さねばなりません。この比較では、 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 回と逆順探索時に 1 回、少なくとも 2 回アクセスされます。その他すべての ファイルは、最低 1 回アクセスされます。 (ディレクトリ間のハードリンクで循 環の原因とならないもの、またはシンボリックリンクに対するシンボリックリン クは、ファイルの場合、 1 回以上アクセスされる原因となり、ディレクトリの場 合、 2 回以上アクセスされたりする原因となることがあります。) 階層のすべてのメンバが戻されると、 fts_read() は NULL を戻し、外部変数 errno に 0 を設定します。階層中のファイルと無関係なエラーが発生すると、 fts_read() は NULL を戻し、 errno に適切な値を設定します。戻されるファイ ルに関係するエラーが発生すると、 FTSENT 構造体のポインタが戻され、 errno は設定されたり設定されなかったりします ( fts_info 参照)。 fts_read() が戻す FTSENT 構造体は、同じファイル階層ストリームに対して fts_close() を呼び出した後、もしくは、その構造体がディレクトリ型ファイル を表していない場合に同じファイル階層ストリームに対して fts_read() を呼び 出した後、上書きされることがあります。どちらの場合でも、逆順探索の際に fts_read() が FTSENT を返した後に fts_read() を呼び出すまでは、 FTSENT 構 造体は上書きされません。 |
FTS_CHILDREN
関数 fts_children() は、 fts_read() が最近戻した FTSENT 構造体が表すディ レクトリのファイルの NULL で終わるリンクリストの最初のエントリである FTSENT 構造体のポインタを戻します。リストは、 FTSENT 構造体の fts_link フィールドでリンクされ、ユーザ定義比較関数がある場合は、それで順序付けら れます。 fts_children() を繰り返し呼び出すと、このリンクリストはそのたび に再作成されます。 特別な場合として、その階層で fts_read() がまだ呼び出されていない場合、 fts_children() は、 fts_open() に指定された論理ディレクトリにあるファイル (すなわち、 ftp_open() に指定された引数) を指すポインタを戻します。 fts_read() がすでに呼び出されているときに、 fts_read() が最近戻した FTSENT 構造体が、正順探索でアクセスされたディレクトリでないか、ディレクト リにファイルが含まれていない場合、 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() が最近戻したファイルに対しての み意味を持ちます。通常の場合は逆順ディレクトリアクセスに使 用します。この場合はディレクトリが正順と逆順の両方で再アク セスされ、その子すべても再アクセスされます。 FTS_FOLLOW リンクのターゲットがディレクトリである場合は、正順探索での リターン、すべての子孫のリターン、逆順探索のリターンがこの 順序で実行されます。 FTS_SKIP FTS_CLOSE |
関数 fts_close() は、ファイル階層ストリーム ftsp を閉じ、カレントディレク トリを、 fts_open() を呼び出した時のディレクトリに戻します。 fts_close() 関数は、エラーがなければ 0 を戻し、エラーが発生した場合は -1 を戻します。 |
エラー
fts_open() 関数の実行が失敗しエラーになると、ライブラリ関数 open(2) と malloc(3) で指定されたエラーが errno に設定されることがあります。 fts_close() 関数がエラーになると、ライブラリ関数 chdir(2) と close(2) が 指定したエラーが errno 設定されることがあります。 fts_read() 関数と fts_children() 関数がエラーになると、ライブラリ関数 chdir(2), malloc(3), opendir(3), readdir(3), stat(2) で指定されたエラーが errno に設定されることがあります。 fts_children(), fts_open(), fts_set() がエラーになると、以下のように errno を設定します。 |
[EINVAL]
オプションが正しくありません。 関連項目 |
規格
fts ユーティリティは、将来、 IEEE Std 1003.1-1988 (‘‘POSIX.1’’) リビジョ ンに組み込まれると思われます。 FreeBSD 10.0 April 16, 1994 FreeBSD 10.0 |