名前

fts, fts_open, fts_read, fts_children, fts_set, fts_close - ファイル階層をたどる

書式


.Fd #include <sys/types.h>
.Fd #include <sys/stat.h>
.Fd #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
は、階層中のディレクトリにあるファイルを記述する 構造体のリンクリストへのポインタを返す。 一般にディレクトリは、 pre-order (正方向：下の階層のディレクトリをたどる前) と post-order (逆方向：下の階層のディレクトリをすべてたどった後) という、 異なる方向で 2 回たどられる。ファイルは 1 回たどられる。 ディレクトリ階層を「論理的に」(シンボリックリングを無視して) 移動することも、 物理的に (シンボリックリンクをたどって) 移動することも可能である。 また、階層中の移動の道筋を指示すること・ 余分なものを取り除くこと・階層の一部を再びたどることが可能である。

2 つの構造体がインクルードファイル <

fts.h
> で定義されている (さらに typedef されている)。 1 つ目は、ファイル階層そのものを表現する FTS 構造体である。 2 つ目は、ファイル階層中のファイルを表現する FTSENT 構造体である。 FTSENT 構造体は通常、ファイル階層中のすべてのファイルに対して返される。 この man ページでは、「ファイル」と 「 FTSENT 構造体」を一般に読み変えることができる。 FTSENT 構造体は、少なくとも次のようなフィールドを持っており、 以下でより詳しく説明されている。 typedef struct _ftsent {         u_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
pre-order でたどられるディレクトリ。 
 FTS_DC
ツリーの中で循環しているディレクトリ。 ( FTSENT 構造体の fts_cycle フィールドも同様に埋められる。) 
 FTS_DEFAULT
 ファイルタイプを表現する FTSENT 構造体が、 fts_info の他のいずれかの値で明示的に説明されていない。 
 FTS_DNR
読み込みができないディレクトリ。 これはエラーの場合の返り値であり、 何がエラーを起こしたかを示すために fts_errno フィールドが設定される。 
 FTS_DOT
 fts_open
へのファイル名として指定されなかった ‘
.
’ または ‘
..
’ という名前のファイル 
( FTS_SEEDOT
を参照すること)。 
 FTS_DP
post-order でたどられるディレクトリ。 FTSENT 構造体の内容は、pre-order のときに返された状態 (つまり、 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
によって返された最も新しいファイルに対して のみ 
 NUL
終端されることが保証される。 これらのフィールドを、他の FTSENT 構造体で表現されるファイルを参照するために使うには、 FTSENT 構造体の fts_pathlen フィールドにある情報を使ってパスのバッファーを修正する必要がある。 これらの修正は、さらに 
 fts_read
を呼び出そうとする場合には、元に戻しておかなければならない。 fts_name フィールドは、常に 
 NUL
終端される。

FTS_OPEN

 fts_open
関数は、文字列ポインタの配列へのポインタを引き数に取る。 この文字列ポインタは、論理ファイル階層をつくる 1 つ以上のパスの名前になる。 配列は、 
 NULL
ポインタで終端されなければならない。

多くのオプションがあり、少なくとも 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
関数は、階層中のファイルを記述する FTSENT 構造体へのポインタを返す。 (読み込み可能で、循環していない) ディレクトリは、 1 回は pre-order で、もう 1 回は post-order で、少なくとも 2 回たどられる。 他のファイルは、少なくとも 1 回たどられる。 (ディレクトリ間のハードリンクによって 循環やシンボリックリンクへのシンボリックリンクが起こらない場合、 ファイルは 2 回以上、ディレクトリは 3 回以上たどられる。)

階層中のすべてのメンバーが返された場合、 

 fts_read
は 
 NULL
を返し、外部変数 errno を 0 にする。 階層中のファイルに関係しないエラーが起こった場合、 
 fts_read
は 
 NULL
を返し、 errno をエラーに対応した値にする。 階層中のファイルに関係したエラーが起こった場合、 FTSENT 構造体へのポインタが返され、 errno は設定される場合と設定されない場合がある ( fts_info を参照すること)。 

 fts_read
によって返される FTSENT 構造体は、同じファイル階層ストリームへの 
 fts_close
の呼出しの後に上書きされる。 また、同じファイル階層ストリームへの 
 fts_read
の呼出しの後でも、構造体がディレクトリを表現していない限り上書きされる。 この場合、 
 fts_read
関数によって post-order で FTSENT 構造体が返された後、 
 fts_read
の呼出しがあるまで、 これらの構造体は上書きされない。

FTS_CHILDREN

 fts_children
関数は、 FTSENT 構造体へのポインタを返す。 この構造体は、( 
 fts_read
で最も新しく返された FTSENT 構造体で表現されるディレクトリにあるファイルの) NUL 終端されたリンクリストの最初のエントリを記述する。 このリストは、 FTSENT 構造体の fts_link フィールドを使ってリンクされ、 ユーザー指定の比較関数がある場合は、それで順序づけられる。 
 fts_children
の呼出しを繰り返すことで、 このリンクリストは再生成される。

特別な場合として、 

 fts_read
がファイル階層について呼ばれていない場合、 
 fts_children
は 
 fts_open
に指定された論理ディレクトリ (つまり、 
 fts_open
に指定された引き数) の中にあるファイルへのポインタを返す。 それ以外の場合で、 
 fts_read
によって最も新しく返された FTSENT 構造体が pre-order でたどられたディレクトリでない場合や 何も含んでいないディレクトリの場合は、 
 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
によって最も新しく返されたファイルについてのみ意味を持つ。 通常は、post-order でディレクトリをたどる場合に使用し、 その下の階層と同様に、 ディレクトリを (pre-order と post-order の両方で) 再びたどらせる。 
 FTS_FOLLOW

参照されてるファイルは、シンボリックリンクでなければならない。 参照されているファイルが 

 fts_read
によって最も新しく返されたものである場合、次の 
 fts_read
の呼出しでは、シンボリックリンクそのものではなく、 シンボリックリンクが指している先を反映するように fts_info, fts_statp を再び初期化したファイルが返される。 ファイルが 
 fts_children
によって最も新しく返されたものの 1 つである場合、 
 fts_read
によって返されたとき、構造体の fts_info, fts_statp フィールドは、シンボリックリンクそのものではなく、 シンボリックリンクが指している先を反映する。 どちらの場合でも、シンボリックリンクが指している先がないときは、 返された構造体のフィールドは変更されず、 fts_info フィールドが 
 FTS_SLNONE
に設定される。

リンク先がディレクトリの場合、 ファイルが pre-order で返された後、下の階層のすべてファイルが返され、 その後で post-order で返される。 

 FTS_SKIP
このファイルの下の階層はたどられない。 このファイルは、 
 fts_children
または 
 fts_read
のどちらかによって最も新しく返されたものの 1 つである。

FTS_CLOSE

 fts_close
関数は、ファイル階層ストリーム ftsp を閉じる。そして、現在のディレクトリを ftsp を開くために 
 fts_open
が呼ばれたディレクトリに復元する。 
 fts_close
関数は、成功した場合は 0 を、エラーが起こった場合は -1 を返す。

エラー

関数 

 fts_open
が失敗した場合、 errno は、ライブラリ関数 open(2) と malloc(3) に対して指定されるエラーに設定される。

関数 

 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
]
 オプションが無効であった。

バージョン

これらの関数は、Linux では glibc2 から使用可能である。

準拠

4.4BSD. fts ユーティリティは、将来の -p1003.1-88 リビジョンに含まれると期待されている。

関連項目

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

openSUSE Logo

コンテンツ