名称

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

ライブラリ

Standard C Library (libc, -lc)

書式

#include < fts.h>

FTS *
fts_open( char * const *path_argv, int options, int (*compar)(const FTSENT * const *, const FTSENT * const *));

FTSENT *
fts_read( FTS *ftsp);

FTSENT *
fts_children( FTS *ftsp, int options);

int
fts_set( FTS *ftsp, FTSENT *f, int options);

void
fts_set_clientptr( FTS *ftsp, void *clientdata);

void *
fts_get_clientptr( FTS *ftsp);

FTS *
fts_get_stream( FTSENT *f);

int
fts_close( FTS *ftsp);

解説

fts 関数は、 UNIX ファイル階層を横断するために提供されます。簡単な概要は、 fts_open() 関数は、他の fts 関数に供給される、ファイル階層の“ハンドル”を返すということです。関数 fts_read() は、ファイル階層のファイルの 1 つを表す構造体へのポインタを返します。関数 fts_children() は、階層のディレクトリに含まれていたファイルの 1 つを表す各々の構造体のリンクしたリストへのポインタを返します。一般的に、ディレクトリは、前の順序 (それらの任意の子がアクセスされる前) と、後の順序 (それらの子のすべてがアクセスされた後) で、 2 回アクセスされます。ファイルは、1 度アクセスされます。階層または階層の部分を取り除いて再アクセスするか取り除くかまたは再アクセスするかの移動の順序で、階層を“論理的に” (シンボリックリンクを無視して) または物理的に (シンボリックリンクをアクセスして) 移動させることは可能です。

2 つの構造体 (と typedef) がインクルードファイル < fts.h> に定義されます。最初は、ファイル階層自体を表現する構造体 FTS です。 2 つめは、ファイル階層でファイルを表現する構造体 FTSENT です。通常は、 FTSENT 構造体は、ファイル階層中のすべてのファイルのために返されます。このマニュアルページで、“ファイル”と“ FTSENT 構造体”は、一般的に交換可能です。

FTS 構造体は、1 つのポインタのための空間を含んでいます。それは、アプリケーションデータか階層ごとの状態を格納するために使用されます。 fts_set_clientptr() と fts_get_clientptr() 関数は、このポインタを設定するか取得するために使用されます。これは、 fts_get_stream() 関数を使用する引数の元の FTS のストリームを決定することができる、ソートの比較機能からアクセスされるときにだけ役に立ちそうです。 2 つの get 関数は、また同じ名前のマクロとして利用可能です。

FTSENT 構造体は、少なくとも次のフィールドを含んでいます。それらは、後でより詳しく説明されます。

typedef struct _ftsent { 
 int fts_info;   /* FTSENT 構造体の状態 */ 
 char *fts_accpath;  /* アクセスパス */ 
 char *fts_path;   /* ルートパス */ 
 size_t fts_pathlen;  /* strlen(fts_path) */ 
 char *fts_name;   /* ファイル名 */ 
 size_t fts_namelen;  /* strlen(fts_name) */ 
 long fts_level;   /* 深さ (-1 to N) */ 
 int fts_errno;   /* ファイル errno */ 
 long long fts_number;  /* ローカル数値 */ 
 void *fts_pointer;  /* ローカルアドレス値 */ 
 struct ftsent *fts_parent; /* 親ディレクトリ */ 
 struct ftsent *fts_link; /* 次のファイル構造体 */ 
 struct ftsent *fts_cycle; /* cycle 構造体 */ 
 struct stat *fts_statp;  /* stat(2) 情報 */ 
} FTSENT;

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

fts_info

返された FTSENT 構造体とそれが表わすファイルについて記述する次の値のうちの 1 つです。エラー ( FTS_D) のないディレクトリを除いて、これらのエントリのすべては末端です。すなわち、それらは、再アクセスされし、子のうちのいずれもアクセスされません。

fts_accpath

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

fts_path

横断のルートに相対的なファイルのためのパス。このパスは、接頭辞として fts_open() に指定されたパスを含んでいます。

fts_pathlen

参照が fts_path によって参照される文字列の長さです。

fts_name

ファイルの名前。

fts_namelen

fts_name によって参照される文字列の長さ。

fts_level

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

fts_errno

FTS_DNR, FTS_ERR または FTS_NS に設定されている fts_info フィールドをつけて fts_children() または fts_read() 関数から FTSENT 構造体を返すとき、 fts_errno フィールドは、エラーの原因を特定する外部変数 errno の値を含んでいます。そうでなければ、 fts_errno フィールドの内容は、未定義です。

fts_number

このフィールドは、アプリケーションプログラムの使用のために提供されます、そして fts 関数によって修正されません。それは、0 で初期化されます。

fts_pointer

このフィールドは、アプリケーションプログラムの使用のために提供されます、そして fts 関数によって修正されません。それは、 NULL で初期化されます。

fts_parent

現在のファイルのすぐ上の階層中のファイル、すなわち、このファイルがメンバであるディレクトリ、を参照する FTSENT 構造体へのポインタです。初期のエントリポイントのために親の構造体は、同様に提供されます。しかしながら、 fts_level, fts_bignum, fts_number と fts_pointer フィールドだけ初期化されることを保証されます。

fts_link

fts_children() 関数からの返りに際して、 fts_link フィールドは、ディレクトリメンバの NULL で終了したリンクしたリスト中の次の構造体を指します。そうでなければ、 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 フィールドは、常にヌル文字で終了します。

fts_bignum の使用は、 fts_number または fts_pointer の使用について互いに排他的であることに注意してください。

FTS_OPEN

fts_open() 関数は、横断される論理的なファイル階層を構成する 1 つ以上のパスを指定する文字ポインタの配列へのポインタを取ります。配列は、 NULL ポインタによって終了しなければなりません。

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

FTS_COMFOLLOW: FTS_LOGICAL が指定されても指定されなくても、ルートパスとして指定されたどんなシンボリックリンクも、このオプションによって直ちに追跡されます。
FTS_LOGICAL: このオプションによって fts ルーチンに、シンボリックリンクそれら自体の代わりにシンボリックリンクのターゲットのための FTSENT 構造体が返されるようになります。このオプションが設定されるなら、アプリケーションに返される FTSENT 構造体のための唯一のシンボリックリンクは、存在しないファイルの参照です。 FTS_LOGICAL または FTS_PHYSICAL のいずれかは fts_open() 関数に提供されなければなりません。
FTS_NOCHDIR: ({ PATH_MAX}と無関係に) 任意の深さに下降することができ、性能を改善するために、 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 つのポインタを取り、最初の引数によって参照されるファイルが 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 度アクセスされます。 (循環を引き起こさないディレクトリの間のハードリンクまたはシンボリックリンクへのシンボリックリンクは、ファイルを 2 度以上またはディレクトリを 3 度以上アクセスする原因となるかもしれません。)

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

fts_read() によって返された FTSENT 構造体は、同じファイル階層ストリームに関して fts_close() への呼び出しの後に、または、それらがタイプディレクトリのファイルを表わさなければ、同じファイル階層ストリームに関して fts_read() への呼び出しの後に上書きされます。その場合には、後の順序で FTSENT 構造体が関数 fts_read() によって返された後に、 fts_read() への呼び出しの後まで、それらは、上書きされません。

FTS_CHILDREN

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

特別の場合として、 fts_read() が階層のためにまだ呼び出されていないなら、 fts_children() は、 fts_open() に指定された論理的なディレクトリのファイル (すなわち fts_open() に指定された引数) へのポインタを返します。そうでなければ、 fts_read() によって最近返された FTSENT 構造体が前の順序でアクセスされたディレクトリでないか、ディレクトリがファイルを含んでいないなら、 fts_children() は、 NULL を返し、 errno に 0 を設定します。エラーが生じるなら、 fts_children() は、 NULL を返し、 errno を適切に設定します。

fts_children() によって返された FTSENT 構造体は、同じファイル階層ストリームに関して fts_children(), fts_close() または fts_read() への呼び出しの後に上書きされるかもしれません。

option は、次の値を設定できます:

FTS_SET

関数 fts_set() は、ユーザアプリケーションがストリーム ftsp のファイル f のためのさらなる処理を決定することを可能にします。 fts_set() 関数は、成功すれば 0 を返し、エラーが生じるなら、-1 を返します。 option は、次の値のうちの 1 つに設定されなければなりません。

FTS_CLOSE

fts_close() 関数は、ファイル階層ストリーム ftsp をクローズして、 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 を設定します。

歴史

fts インタフェースは、 4.4BSD ではじめて導入されました。 fts_get_clientptr(), fts_get_stream() と fts_set_clientptr() 関数は、主に異なったデータ構造を使用することで fts の機能のための代替のインタフェースを提供するために、 FreeBSD 5.0 で導入されました。

バグ

fts_open() 関数は、 FTS_LOGICAL オプションが提供されるか、または、カレントディレクトリを open(2) (オープン) することができないなら、自動的に FTS_NOCHDIR オプションを設定します。

YOS OPENSONAR

名称