fts

Autres langues

Langue: ja

Autres versions - même langue

Version: 98157 (fedora - 25/11/07)

Autres sections - même nom

Section: 3 (Bibliothèques de fonctions)

Sommaire


BSD mandoc

名前

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> Ft FTS * Fn fts_open char * const *path_argv int options int (*compar)(const FTSENT **, const FTSENT **) Ft FTSENT * Fn fts_read FTS *ftsp Ft FTSENT * Fn fts_children FTS *ftsp int options Ft int Fn fts_set FTS *ftsp FTSENT *f int options Ft int Fn fts_close FTS *ftsp

説明

fts 関数は、 UNIX ファイル階層をたどるために提供されている。 簡単に概略すると次のようになる。 Fn fts_open 関数は、 他の fts 関数に渡すための、ファイル階層の「ハンドル」を返す。 関数 Fn fts_read は、ファイル階層中にある 1 つのファイルを記述する 構造体へのポインタを返す。 関数 Fn fts_children は、階層中のディレクトリにあるファイルを記述する 構造体のリンクリストへのポインタを返す。 一般にディレクトリは、 pre-order (正方向：下の階層のディレクトリをたどる前) と post-order (逆方向：下の階層のディレクトリをすべてたどった後) という、 異なる方向で 2 回たどられる。ファイルは 1 回たどられる。 ディレクトリ階層を「論理的に」(シンボリックリングを無視して) 移動することも、 物理的に (シンボリックリンクをたどって) 移動することも可能である。 また、階層中の移動の道筋を指示すること・ 余分なものを取り除くこと・階層の一部を再びたどることが可能である。

2 つの構造体がインクルードファイル Aq Pa fts.h で定義されている (さらに typedef されている)。 1 つ目は、ファイル階層そのものを表現する Fa FTS 構造体である。 2 つ目は、ファイル階層中のファイルを表現する Fa FTSENT 構造体である。 Fa FTSENT 構造体は通常、ファイル階層中のすべてのファイルに対して返される。 この man ページでは、「ファイル」と Fa 「 FTSENT 構造体」を一般に読み変えることができる。 Fa 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;

これらのフィールドは、次のように定義されている。

Fa fts_info
このフィールドは、返された Fa FTSENT 構造体とファイルを説明する以下のフラグのいずれかを表している。 エラーのないディレクトリ (FTS_D ) の場合は例外として、それ以外のすべてのエントリは終端である。 つまり、エントリは再びたどられることもなく、 それより下の階層がたどられることもない。
FTS_D
pre-order でたどられるディレクトリ。
FTS_DC
ツリーの中で循環しているディレクトリ。 Fa ( FTSENT 構造体の Fa fts_cycle フィールドも同様に埋められる。)
FTS_DEFAULT
ファイルタイプを表現する Fa FTSENT 構造体が、 Fa fts_info の他のいずれかの値で明示的に説明されていない。
FTS_DNR
読み込みができないディレクトリ。 これはエラーの場合の返り値であり、 何がエラーを起こしたかを示すために Fa fts_errno フィールドが設定される。
FTS_DOT
Fn fts_open へのファイル名として指定されなかった `.' または `..' という名前のファイル ( FTS_SEEDOT を参照すること)。
FTS_DP
post-order でたどられるディレクトリ。 Fa FTSENT 構造体の内容は、pre-order のときに返された状態 (つまり、 Fa fts_info フィールドが FTS_D に設定されている状態) から変更されない。
FTS_ERR
これはエラーの場合の返り値であり、 Fa fts_errno フィールドは、何がエラーを起こしたかを示す値に設定される。
FTS_F
通常のファイル。
FTS_NS
stat(2) 情報が得られなかったファイル。 Fa fts_statp フィールドの内容は定義されない。 これはエラーの場合の返り値であり、 Fa fts_errno フィールドは、何がエラーを起こしたかを示す値に設定される。
FTS_NSOK
stat(2) 情報が要求されなかったファイル。 Fa fts_statp フィールドの内容は定義されない。
FTS_SL
シンボリックリンク。
FTS_SLNONE
リンク先の存在しないシンボリックリンク。 Fa fts_statp フィールドの内容は、シンボリックリンクそのもののファイル特性情報を参照する。
Fa fts_accpath
現在のディレクトリからファイルにアクセスするためのパス。
Fa fts_path
階層をたどるときのルートからみたファイルの相対的なパス。 このパスには、 Fn fts_open に指定したパスがプレフィックスとして含まれる。
Fa fts_pathlen
Fa fts_path で参照される文字列の長さ。
Fa fts_name
ファイルの名前。
Fa fts_namelen
Fa fts_name で参照される文字列の長さ。
Fa fts_level
階層をたどって、このファイルがみつかった深さ。 -1 〜 N の数値で表される。 階層をたどるときの出発点 (ルート) の親ディレクトリを表す Fa FTSENT 構造体では -1 となる。 また、ルート自身の Fa FTSENT 構造体では 0 になる。
Fa fts_errno
関数 Fn fts_children と Fn fts_read から返される Fa FTSENT 構造体の Fa fts_info フィールドが FTS_DNR FTS_ERR FTS_NS に設定されている場合、 Fa fts_errno フィールドにはエラーの原因を示す外部変数 errno の値が入る。 それ以外の場合、 Fa fts_errno フィールドの内容は定義されない。
Fa fts_number
このフィールドは、アプリケーションプログラムから使用するために提供され、 fts 関数では変更されない。 このフィールドは 0 で初期化される。
Fa fts_pointer
このフィールドは、アプリケーションプログラムから使用するために提供され、 fts 関数では変更されない。 このフィールドは NULL で初期化される。
Fa fts_parent
現在のファイルのすぐ上の階層にあるファイル (つまり、現在のファイルがメンバーになっているディレクトリ) を参照する Fa FTSENT 構造体へのポインタ。 最初の出発点に対しても、親となる構造体は与えられる。 しかし、 Fa fts_level , Fa fts_number , Fa fts_pointer フィールドのみの初期化しか保証されない。
Fa fts_link
Fn fts_children から返される場合、 Fa fts_link フィールドはディレクトリメンバーの NUL 終端されたリンクリストの形式で、 次の構造体を指し示す。 それ以外の場合、 Fa fts_link フィールドは定義されない。
Fa fts_cycle
2 つのディレクトリにハードリンクが張られているため、 または、シンボリックリンクがあるディレクトリを指しているために、 ディレクトリが循環する階層構造を作っている場合 ( FTS_DC を参照)、 構造体の Fa fts_cycle フィールドは、階層中で現在の Fa FTSENT 構造体と同じファイルを参照している Fa FTSENT 構造体を指し示す。 それ以外の場合、 Fa fts_cycle フィールドは定義されない。
Fa fts_statp
このファイルの stat(2) 情報へのポインタ。

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

FTS_OPEN

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

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

FTS_COMFOLLOW
このオプションは、 FTS_LOGICAL の指定にかかわらず、 ルートパスに指定されたシンボリックリンクをすぐにたどらせる。
FTS_LOGICAL
このオプションは、 fts ルーチンにシンボリックリンクそのものではなく、 シンボリックリンクが指しているファイルの Fa FTSENT 構造体を返させる。 このオプションが設定された場合、 Fa FTSENT 構造体がアプリケーションに返されるような シンボリックリンクのみが、存在しないファイルを参照している。 FTS_LOGICAL または FTS_PHYSICAL のどちらかを、 Fn fts_open 関数に与えなければ ならない。
FTS_NOCHDIR
パフォーマンスの最適化のため、 fts 関数はファイル階層をたどるときディレクトリを変える。 これには、階層をたどっている間は アプリケーションがある特定のディレクトリにいるということに 依存できない、という副作用がある。 FTS_NOCHDIR オプションで最適化を無効にすると、 fts 関数は現在のディレクトリを変更しない。 FTS_NOCHDIR が指定され、かつ Fn fts_open の引き数として絶対パス名が与えられたとき以外、アプリケーションは、 自らカレントディレクトリを変更したり、 ファイルにアクセスしたりすべきではない、という点に注意すること。
FTS_NOSTAT
デフォルトでは、返された Fa FTSENT 構造体は、たどられた各ファイルについてのファイル特徴情報 Fa ( statp フィールド) を参照する。 このオプションは、 fts 関数が Fa fts_info フィールドを FTS_NSOK に設定し Fa statp の内容を定義されないままにすることを許すことにより、 パフォーマンスの最適化に必要なものを緩和する。
FTS_PHYSICAL
このオプションは、 fts ルーチンにシンボリックリンクが指しているファイルではなく、 シンボリックリンク自身の Fa FTSENT 構造体を返させる。 このオプションが設定されると、階層中のすべてのシンボリックリンクの Fa FTSENT 構造体がアプリケーションに返される。 FTS_LOGICAL または FTS_PHYSICAL のどちらかを Fn fts_open 関数に与えなければ ならない。
FTS_SEEDOT
デフォルトでは、 Fn fts_open のパス引き数として指定されない限り、ファイル階層中にある `.' または `..' という名前のファイルは無視される。 このオプションは、 fts ルーチンにこれらのファイルの Fa FTSENT 構造体を返させる。
FTS_XDEV
このオプションは、 fts が下り始めのファイルとは異なるデバイス番号を持っている ディレクトリに下りるのを阻止する。

引き数 Fn compar は、階層をたどる順番を決めるのに使われるユーザー定義関数を指定する。 この関数は、引き数として Fa FTSENT 構造体のポインタのポインタを 2 つとり、 1 番目の引き数で参照されているファイルが 2 番目の引き数で参照されているファイルより 前にある場合は負の値・同じ場合はゼロ・後にある場合は正の値を 返さなければならない。 Fa FTSENT 構造体の Fa fts_accpath , Fa fts_path , Fa fts_pathlen フィールドは、この比較に 絶対 使ってはいけない。 Fa fts_info フィールドが FTS_NS または FTS_NSOK に設定される場合、 Fa fts_statp フィールドはこれらのどちらでもない。 Fn compar 引き数が NULL の場合、ディレクトリをたどる順番は、ルートパスについては Fa path_argv のなかでリストされた順番で、 その他のファイルについてはディレクトリ内でリストされた順番となる。

FTS_READ

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

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

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

FTS_CHILDREN

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

特別な場合として、 Fn fts_read がファイル階層について呼ばれていない場合、 Fn fts_children は Fn fts_open に指定された論理ディレクトリ (つまり、 Fn fts_open に指定された引き数) の中にあるファイルへのポインタを返す。 それ以外の場合で、 Fn fts_read によって最も新しく返された Fa FTSENT 構造体が pre-order でたどられたディレクトリでない場合や 何も含んでいないディレクトリの場合は、 Fn fts_children は NULL を返し、 errno を 0 にする。 エラーが起こった場合、 Fn fts_children は NULL を返し、 errno をエラーに対応した値にする。

Fn fts_children によって返される Fa FTSENT 構造体は、同じファイル階層ストリームへの Fn fts_children , Fn fts_close , Fn fts_read の呼出しの後に上書きされる場合がある。

option は、次の値に設定できる。

FTS_NAMEONLY
ファイル名のみが必要とされている。 返された構造体のリンクリストの Fa fts_name , Fa fts_namelen フィールド以外の すべてのフィールドの内容は定義されない。

FTS_SET

関数 Fn fts_set は、ユーザーアプリケーションが ストリーム Fa ftsp のファイル Fa f について更なる処理を決定すること許す。 Fn fts_set 関数は、成功した場合は 0 を、エラーが起こった場合は -1 を返す。 option は、次の値のいずれか 1 つに設定されなければならない。
FTS_AGAIN
ファイルを再びたどる。すべてのファイルタイプが再びたどられる。 次の Fn fts_read の呼出しにより、参照されているファイルが返される。 構造体の Fa fts_stat , Fa fts_info フィールドはこの時に初期化されるが、他のフィールドは変更されない。 このオプションは、 Fn fts_read によって最も新しく返されたファイルについてのみ意味を持つ。 通常は、post-order でディレクトリをたどる場合に使用し、 その下の階層と同様に、 ディレクトリを (pre-order と post-order の両方で) 再びたどらせる。
FTS_FOLLOW

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

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

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

FTS_CLOSE

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

エラー

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

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

関数 Fn fts_read と Fn fts_children が失敗した場合、 errno は、ライブラリ関数 chdir(2), malloc(3), opendir(3), readdir(3), stat(2) に対して指定されるエラーに設定される。

更に、 Fn fts_children , Fn fts_open , Fn fts_set が失敗した場合、 errno が次の値にされる。

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

バージョン

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

準拠

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

関連項目

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