fts_read(3)

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

標準 C ライブラリ (libc, −lc)

#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 は、 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;

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

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

FTS_D
正順でアクセスされるディレクトリです。

FTS_DC
ツリーでの循環の原因となるディレクトリです。 ( FTSENT 構造体の fts_cycle フィールドにも同様に この情報が入ります。)

FTS_DEFAULT
他のどの fts_info の値でも明確に表さないファイ ルタイプを表す FTSENT 構造体です。

FTS_DNR
読み込めないディレクトリです。これはエラーリ ターンで、 fts_errno フィールドにエラーの原因を 表す値が設定されます。

FTS_DOT
fts_open() にファイル名として指定されていない、 ‘.’ や、 ‘..’ という名前を持つファイルです ( FTS_SEEDOT を参照)。

FTS_DP
逆順でアクセスされるディレクトリです。正順 (つ まり、 fts_info フィールドに FTS_D が設定された 場合) で戻ってきた時は、 FTSENT 構造体の内容は 変更されていません。

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 構造体には、番号 FTS_ROOTPARENTLEVEL (−1) が付されます。ルートの FTSENT 構造 体には、番号 FTS_ROOTLEVEL (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 フィールドは、 NUL終端 されていることが保証されるのは、 fts_read() が最後に戻したファイル のみで す。他の FTSENT 構造体が表すファイルを参照するために、このフィールドを使 用するためには、その FTSENT 構造体の fts_pathlen フィールドに含まれる情報 でパスバッファを修正する必要があります。 fts_read() をさらに呼び出す前 に、このような修正を元に戻しておく必要があります。 fts_name フィールド は、常に NUL終端されています。

FTS_OPEN

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

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

このオプションを指定すると、 FTS_LOGICAL が指定されているか どうかに関わらず、ルートパスとして指定されたシンボリックリ ンクがすぐにたどられます。

FTS_LOGICAL
このオプションを指定すると、 fts ルーチンは、シンボリックリ ンクそのものではなく、シンボリックリンクのターゲットの FTSENT 構造体を戻すようになります。このオプションを設定する と、アプリケーションに戻される FTSENT 構造体が指すシンボ リックリンクは、存在しないファイルを参照するものだけになり ます。 fts_open() 関数には、 FTS_LOGICAL か FTS_PHYSICAL を 指定する必要があります。

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_open() 関数に は、 FTS_LOGICAL か FTS_PHYSICAL を指定する必要があります。

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 回アクセスされます。 (ディレクトリ間のハードリンクで循 環の原因とならないもの、またはシンボリックリンクに対するシンボリックリン クは、ファイルの場合、 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_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_name フィールドと fts_namelen フィールドを除いて未定義 になります。

FTS_SET

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

ファイルを再アクセスします。どのようなファイルタイプのファ イルも再アクセスされる可能性があります。その次に fts_read() を呼び出すことで、参照されたファイルが戻されます。そのと き、構造体の fts_stat フィールドと fts_info フィールドが再 び初期化されますが、その他のフィールドは変更されません。こ のオプションは、 fts_read() が最近戻したファイルに対しての み意味を持ちます。通常の場合は逆順ディレクトリアクセスに使 用します。この場合はディレクトリが正順と逆順の両方で再アク セスされ、その子すべても再アクセスされます。

FTS_FOLLOW
参照するファイルは、シンボリックリンクである必要がありま す。参照するファイルが、 fts_read() で最近戻されたものであ る場合、次に fts_read() を呼び出すと、 fts_info フィールド と fts_statp フィールドが初期化され、シンボリックリンク自体 ではなくシンボリックリンクのターゲットを指した状態でファイ ルが戻されます。ファイルが fts_children() で最近戻されたも のである場合、構造体の fts_info フィールドと fts_statp フィールドは、 fts_read() で戻されると、シンボリックリンク 自体ではなくシンボリックリンクのターゲットを反映します。ど ちらの場合でも、シンボリックリンクのターゲットが存在しなけ れば、戻される構造体のフィールドは変更されず、 fts_info フィールドは FTS_SLNONE に設定されます。

リンクのターゲットがディレクトリである場合は、正順探索での リターン、すべての子孫のリターン、逆順探索のリターンがこの 順序で実行されます。

FTS_SKIP
このファイルの子はアクセスされません。ここで指定するファイ ルとして、 fts_children() か fts_read() が最近戻したものど ちらかが可能です。

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 を設定します。

オプションが正しくありません。

関連項目

find(1), chdir(2), stat(2), qsort(3)

fts ユーティリティは、将来、 IEEE Std 1003.1-1988 (‘‘POSIX.1’’) リビジョ ンに組み込まれると思われます。

FreeBSD 10.0 April 16, 1994 FreeBSD 10.0