.\" Copyright (c) 1989, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)fts.3 8.5 (Berkeley) 4/16/94 .\" %FreeBSD: src/lib/libc/gen/fts.3,v 1.7.2.5 2001/12/14 18:33:51 ru Exp % .\" .\" $FreeBSD$ .Dd April 16, 1994 .Dt FTS 3 .Os .Sh 名称 .Nm fts .Nd ファイルの階層を横断する .Sh ライブラリ .Lb libc .Sh 書式 .In sys/types.h .In sys/stat.h .In 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" .Sh 解説 .Nm は、 .Tn UNIX ファイル階層を横断するための関数です。簡単に説明すると、 .Fn fts_open 関数はファイル階層の .Dq ハンドル を戻します。このハンドルは、その他の .Nm 関数に指定できます。 .Fn fts_read 関数は、ファイル階層の 1 つのファイルを表す構造体のポインタを戻します。 .Fn fts_children 関数は、構造体のリンクリストへのポインタを戻します。各構造体は、 その階層のあるディレクトリに含まれるファイル 1 つを表します。 一般に、ディレクトリは、正順 (いずれの子にアクセスする前) と 逆順 (すべての子にアクセスした後) の 2 回アクセスされます。 ファイルは 1 回アクセスされます。 シンボリックリンクを無視した、階層への .Dq 論理的な アクセス、 シンボリックリンクをたどる、階層への物理的なアクセス、 階層へのアクセス命令、階層の一部の切り離しや再アクセスが可能です。 .Pp インクルードファイル .Aq Pa fts.h には、2 つの構造体が定義されて (かつ、typedef 型定義もされて) います。 1 つは、ファイル階層そのものを表す構造体 .Fa FTS です。もう 1 つは、ファイル階層のファイル 1 つを表す構造体 .Fa FTSENT です。通常は、ファイル階層のファイルすべてについて、構造体 .Fa FTSENT が 1 つ戻されます。このマニュアルページでは、 .Dq ファイル と .Dq Fa FTSENT No 構造体 は、ほぼ同じ意味を持ちます。 .Fa FTSENT 構造体には、少なくとも以下に示すフィールドを含みます。それぞれの フィールドについては、後で詳しく説明します。 .Bd -literal 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; .Ed .Pp これらのフィールドは、以下のように定義されています。 .Bl -tag -width "fts_namelen" .It Fa fts_info 戻された .Fa FTSENT 構造体とそれが表すファイルを記述します。以下のうち 1 つの値を取ります。 エラーのないディレクトリ .Pq Dv FTS_D を除けば、すべてのエントリは終端です。つまり、再アクセスされることは なく、子がアクセスされることもありません。 .Bl -tag -width FTS_DEFAULT .It Dv FTS_D 正順でアクセスされるディレクトリです。 .It Dv FTS_DC ツリーでの循環の原因となるディレクトリです。 ( .Fa FTSENT 構造体の .Fa fts_cycle フィールドにも同様にこの情報が入ります。) .It Dv FTS_DEFAULT 他のどの .Fa fts_info の値でも明確に表さないファイルタイプを表す .Fa FTSENT 構造体です。 .It Dv FTS_DNR 読み込めないディレクトリです。これはエラーリターンで、 .Fa fts_errno フィールドにエラーの原因を表す値が設定されます。 .It Dv FTS_DOT .Fn fts_open にファイル名として指定されていない、 .Ql .\& や、 .Ql ..\& という名前を持つファイルです ( .Dv FTS_SEEDOT を参照)。 .It Dv FTS_DP 逆順でアクセスされるディレクトリです。 正順 (つまり、 .Fa fts_info フィールドに .Dv FTS_D が設定された場合) で戻ってきた時は、 .Fa FTSENT 構造体の内容は変更されていません。 .It Dv FTS_ERR これはエラーリターンであり、 .Fa fts_errno フィールドにエラーの原因が設定されます。 .It Dv FTS_F 通常ファイルです。 .It Dv FTS_NS .Xr stat 2 で情報が取得できないファイルです。 .Fa fts_statp フィールドの内容は未定義になります。これはエラーリターンであり、 .Fa fts_errno フィールドにエラーの原因を表す値が設定されます。 .It Dv FTS_NSOK .Xr stat 2 での情報取得を要求しないファイルです。 .Fa fts_statp フィールドの内容は不定になります。 .It Dv FTS_SL シンボリックリンクです。 .It Dv FTS_SLNONE ターゲットが存在しないシンボリックリンクです。 .Fa fts_statp フィールドの内容は、そのシンボリックリンク自体の ファイル特性情報を参照します。 .El .It Fa fts_accpath カレントディレクトリからファイルにアクセスするためのパスです。 .It Fa fts_path 横断のルートからの、ファイルの相対パスです。このパスには、 .Fn fts_open に指定したパスが接頭語として含まれます。 .It Fa fts_pathlen .Fa fts_path が参照する文字列の長さです。 .It Fa fts_name ファイルの名前です。 .It Fa fts_namelen .Fa fts_name が参照する文字列の長さです。 .It Fa fts_level このファイルが見つかった場所の、この横断における深さです。この深さは \-1 から N までの番号が付けられます。横断の開始点の親 (またはルート) を表す .Fa FTSENT 構造体には、番号 .Dv FTS_ROOTPARENTLEVEL (\-1) が付されます。 ルートの .Fa FTSENT 構造体には、番号 .Dv FTS_ROOTLEVEL (0) が付されます。 .It Fa fts_errno 関数 .Fn fts_children もしくは .Fn fts_read が構造体 .Fa FTSENT を戻すに際し、 .Fa fts_info フィールドに .Dv FTS_DNR , .Dv FTS_ERR , .Dv FTS_NS のいずれかが設定された状態の場合は、 .Fa fts_errno フィールドは、エラーの原因を示す外部変数 .Va errno の値を含みます。その他の場合、 .Fa fts_errno フィールドの内容は未定義です。 .It Fa fts_number このフィールドは、アプリケーションプログラムで 使用するためのもので、 .Nm 関数群はこのフィールドを変更しません。このフィールドは 0 で初期化されています。 .It Fa fts_pointer このフィールドは、アプリケーションプログラムで使用するためのもので、 .Nm 関数群はこのフィールドを修正しません。このフィールドは .Dv NULL で初期化されています。 .It Fa fts_parent このファイルがメンバとなっているディレクトリのように、現在着目している ファイルのすぐ上の階層にあるファイルを参照する .Fa FTSENT 構造体のポインタです。初期エントリポイントの親構造体も提供されますが、 .Fa fts_level フィールド、 .Fa fts_number フィールド、 .Fa fts_pointer フィールドの初期化しか保証されません。 .It Fa fts_link .Fn fts_children 関数から戻ると、 .Fa fts_link フィールドは、ディレクトリのメンバを表す、ナル終端されたリンクリスト の中の次の構造体を指します。その他の場合、 .Fa fts_link フィールドの内容は未定義です。 .It Fa fts_cycle ディレクトリ 2 つの間のハードリンクや、ディレクトリを指す シンボリックリンクにより、あるディレクトリが階層構造の中で循環の 原因となっている場合 ( .Dv FTS_DC 参照)、この構造体の .Fa fts_cycle フィールドは、この階層構造の中で、 現在の .Fa FTSENT 構造体と同じファイルを参照する .Fa FTSENT 構造体を指します。その他の場合、 .Fa fts_cycle フィールドの内容は未定義です。 .It Fa fts_statp ファイルの .Xr stat 2 の情報を指すポインタです。 .El .Pp ファイル階層にある全ファイルのすべてのパスに対し、1 つのバッファを 使用します。このため、 .Fa fts_path フィールドと .Fa fts_accpath フィールドは、 .Dv NUL Ns 終端されている ことが保証されるのは、 .Fn fts_read が最後に戻したファイル .Em のみ です。他の .Fa FTSENT 構造体が表すファイルを参照するために、この フィールドを使用するためには、その .Fa FTSENT 構造体の .Fa fts_pathlen フィールドに含まれる情報でパスバッファを 修正する必要があります。 .Fn fts_read をさらに呼び出す前に、 このような修正を元に戻しておく必要があります。 .Fa fts_name フィールドは、常に .Dv NUL Ns 終端されています。 .Sh FTS_OPEN 関数 .Fn fts_open は、横断対象の論理ファイル階層を構成する 1 つ以上のパスを 指定する文字型ポインタの配列を指すポインタを取ります。配列は、 .Dv NULL ポインタで終わっている必要があります。 .Pp 数多くのオプションがありますが、最低でも次のうち 1 つ ( .Dv FTS_LOGICAL か .Dv FTS_PHYSICAL ) を指定する必要があります。オプションは、以下の値の論理和を 取ることで選択されます。 .Bl -tag -width "FTS_PHYSICAL" .It Dv FTS_COMFOLLOW このオプションを指定すると、 .Dv FTS_LOGICAL が指定されているかどうかに関わらず、ルートパスとして指定された シンボリックリンクがすぐにたどられます。 .It Dv FTS_LOGICAL このオプションを指定すると、 .Nm ルーチンは、シンボリックリンクそのものではなく、 シンボリックリンクのターゲットの .Fa FTSENT 構造体を戻すようになります。このオプションを設定すると、 アプリケーションに戻される .Fa FTSENT 構造体が指すシンボリックリンクは、存在しないファイルを 参照するものだけになります。 .Fn fts_open 関数には、 .Dv FTS_LOGICAL か .Dv FTS_PHYSICAL を指定する必要があります。 .It Dv FTS_NOCHDIR パフォーマンスを最適化するため、 .Nm 関数は、ファイル階層のアクセス中に カレントディレクトリを変更します。これには、横断中にどのディレクトリ にいるかがアプリケーションで特定できないという副作用があります。 .Dv FTS_NOCHDIR オプションはこの最適化を無効にするので、 .Nm 関数はカレントディレクトリを変更しなくなります。 .Dv FTS_NOCHDIR を指定していない、もしくは、 .Fn fts_open に絶対パス名を引数として指定していない場合は、アプリケーションで カレントディレクトリを変更したり、ファイルにアクセスしたり しないでください。 .It Dv FTS_NOSTAT デフォルトでは、戻される .Fa FTSENT 構造体は、アクセスしたファイルそれぞれについて ファイル特性情報 ( .Fa statp フィールド) を参照しています。このオプションは、パフォーマンスを 最適化するためにこの要件を緩和し、 .Nm 関数が .Fa fts_info フィールドに .Dv FTS_NSOK を設定して、 .Fa statp フィールドの内容を未定義のままにすることを許可します。 .It Dv FTS_PHYSICAL このオプションを指定すると、 .Nm ルーチンは、シンボリックリンクが指すターゲットファイルではなく、 シンボリックリンク自体の .Fa FTSENT 構造体を戻すようになります。このオプションを設定すると、 階層に存在するすべてのシンボリックリンクの .Fa FTSENT 構造体がアプリケーションに戻されます。 .Fn fts_open 関数には、 .Dv FTS_LOGICAL か .Dv FTS_PHYSICAL を指定する必要があります。 .It Dv FTS_SEEDOT デフォルトでは、 .Fn fts_open のパス引数として指定しない限り、ファイル階層に存在する、 .Ql .\& もしくは、 .Ql ..\& という名前のファイルは無視されます。このオプションを指定することにより、 .Nm ルーチンは、このような ファイルの .Fa FTSENT 構造体を戻すようになります。 .It Dv FTS_XDEV このオプションを指定すると、 .Nm は、下降を始めたファイルと 異なるデバイス番号を持つディレクトリに下降しません。 .El .Pp 引数 .Fn compar は、階層横断の順序決めに使用されるユーザ定義関数を 指定します。この関数は、 .Fa FTSENT 構造体のポインタを指す 2 つのポインタを 引数として取り、最初の引数が参照するファイルが、2 番目の引数が 参照するファイルより前に来るか、前でも後ろでもどちらでも構わないか、 後ろに来るかによって、それぞれ負の値、0、正の値を戻さねばなりません。 この比較では、 .Fa FTSENT 構造体の .Fa fts_accpath , .Fa fts_path , .Fa fts_pathlen フィールドを .Em 絶対に 使用してはいけません。 .Fa fts_info フィールドに .Dv FTS_NS か .Dv FTS_NSOK が設定されている場合、 .Fa fts_statp フィールドも使用してはなりません。 引数 .Fn compar が .Dv NULL である場合、ディレクトリ横断順序は、ルートパスでは .Fa path_argv でリストされる順序に、その 他すべての場所では、ディレクトリでリストされている順序になります。 .Sh FTS_READ .Fn fts_read 関数は、階層のファイルを表す .Fa FTSENT 構造体のポインタを戻します。ディレクトリ (読込み可能で循環の原因とならないもの) は、正順探索時に 1 回と 逆順探索時に 1 回、少なくとも 2 回アクセスされます。 その他すべてのファイルは、最低 1 回アクセスされます。 (ディレクトリ間のハードリンクで循環の原因とならないもの、 またはシンボリックリンクに対するシンボリックリンクは、ファイルの場合、 1 回以上アクセスされる原因となり、ディレクトリの場合、 2 回以上アクセスされたりする原因となることがあります。) .Pp 階層のすべてのメンバが戻されると、 .Fn fts_read は .Dv NULL を戻し、外部変数 .Va errno に 0 を設定します。階層中のファイルと無関係なエラーが発生すると、 .Fn fts_read は .Dv NULL を戻し、 .Va errno に適切な値を設定します。戻されるファイルに 関係するエラーが発生すると、 .Fa FTSENT 構造体のポインタが戻され、 .Va errno は設定されたり設定されなかったりします ( .Fa fts_info 参照)。 .Pp .Fn fts_read が戻す .Fa FTSENT 構造体は、同じファイル階層ストリームに対して .Fn fts_close を呼び出した後、もしくは、 その構造体がディレクトリ型ファイルを表していない場合に 同じファイル階層ストリームに対して .Fn fts_read を呼び出した後、上書きされることがあります。 どちらの場合でも、逆順探索の際に .Fn fts_read が .Fa FTSENT を返した後に .Fn fts_read を呼び出すまでは、 .Fa FTSENT 構造体は上書きされません。 .Sh FTS_CHILDREN 関数 .Fn fts_children は、 .Fn fts_read が最近戻した .Fa FTSENT 構造体が表す ディレクトリのファイルの NULL で終わるリンクリストの最初のエントリである .Fa FTSENT 構造体のポインタを戻します。リストは、 .Fa FTSENT 構造体の .Fa fts_link フィールドでリンクされ、ユーザ定義比較関数がある場合は、それで 順序付けられます。 .Fn fts_children を繰り返し呼び出すと、このリンクリストは そのたびに再作成されます。 .Pp 特別な場合として、その階層で .Fn fts_read がまだ呼び出されていない場合、 .Fn fts_children は、 .Fn fts_open に指定された 論理ディレクトリにあるファイル (すなわち、 .Fn ftp_open に指定された引数) を指すポインタを戻します。 .Fn fts_read がすでに呼び出されているときに、 .Fn fts_read が最近戻した .Fa FTSENT 構造体が、正順探索でアクセスされたディレクトリでないか、 ディレクトリにファイルが含まれていない場合、 .Fn fts_children は .Dv NULL を戻し、 .Va errno に 0 を設定します。エラーが発生すると、 .Fn fts_children は .Dv NULL を戻し、 .Va errno に適切な値を設定します。 .Pp .Fn fts_children が戻す .Fa FTSENT 構造体は、同じファイル階層ストリームを 使用した .Fn fts_children , .Fn fts_close , .Fn fts_read の呼び出しの後、 上書きされることがあります。 .Pp .Em option には、以下の値を設定できます。 .Bl -tag -width FTS_NAMEONLY .It Dv FTS_NAMEONLY ファイルの名前だけが必要であることを示します。戻された構造体の リンクリストに存在するすべてのフィールドの内容は、 .Fa fts_name フィールドと .Fa fts_namelen フィールドを除いて未定義になります。 .El .Sh FTS_SET 関数 .Fn fts_set により、ストリーム .Fa ftsp のファイル .Fa f に対して、さらに行なう処理を ユーザアプリケーションが決めることができます。 .Fn fts_set 関数は、問題がなければ 0 を戻し、エラーが発生した場合は \-1 を戻します。 .Em option として、以下のうちの 1 つの値を 設定する必要があります。 .Bl -tag -width FTS_PHYSICAL .It Dv FTS_AGAIN ファイルを再アクセスします。どのようなファイルタイプのファイルも 再アクセスされる可能性があります。その次に .Fn fts_read を呼び出すことで、参照されたファイルが戻されます。そのとき、構造体の .Fa fts_stat フィールドと .Fa fts_info フィールドが再び初期化されますが、その他のフィールドは変更されません。 このオプションは、 .Fn fts_read が最近戻したファイルに対してのみ意味を持ちます。通常の場合は逆順 ディレクトリアクセスに使用します。この場合はディレクトリが正順と逆順の 両方で再アクセスされ、その子すべても再アクセスされます。 .It Dv FTS_FOLLOW 参照するファイルは、シンボリックリンクである必要があります。 参照するファイルが、 .Fn fts_read で最近戻されたものである場合、次に .Fn fts_read を呼び出すと、 .Fa fts_info フィールドと .Fa fts_statp フィールドが 初期化され、シンボリックリンク自体ではなくシンボリックリンクのターゲットを 指した状態でファイルが戻されます。ファイルが .Fn fts_children で最近戻されたものである場合、構造体の .Fa fts_info フィールドと .Fa fts_statp フィールドは、 .Fn fts_read で戻されると、シンボリックリンク自体ではなく シンボリックリンクのターゲットを反映します。どちらの場合でも、 シンボリックリンクのターゲットが存在しなければ、戻される構造体のフィールド は変更されず、 .Fa fts_info フィールドは .Dv FTS_SLNONE に設定されます。 .Pp リンクのターゲットがディレクトリである場合は、正順探索でのリターン、 すべての子孫のリターン、逆順探索のリターンがこの順序で実行されます。 .It Dv FTS_SKIP このファイルの子はアクセスされません。ここで指定するファイルとして、 .Fn fts_children か .Fn fts_read が最近戻したものどちらかが可能です。 .El .Sh FTS_CLOSE 関数 .Fn fts_close は、ファイル階層ストリーム .Fa ftsp を閉じ、カレントディレクトリを、 .Fn fts_open を呼び出した時のディレクトリに戻します。 .Fn fts_close 関数は、エラーがなければ 0 を戻し、エラーが発生した場合は -1 を戻します。 .Sh エラー .Fn fts_open 関数の実行が失敗しエラーになると、ライブラリ関数 .Xr open 2 と .Xr malloc 3 で指定されたエラーが .Va errno に設定されることがあります。 .Pp .Fn fts_close 関数がエラーになると、ライブラリ関数 .Xr chdir 2 と .Xr close 2 が指定したエラーが .Va errno 設定されることがあります。 .Pp .Fn fts_read 関数と .Fn fts_children 関数がエラーになると、ライブラリ関数 .Xr chdir 2 , .Xr malloc 3 , .Xr opendir 3 , .Xr readdir 3 , .Xr stat 2 で指定されたエラーが .Va errno に設定されることがあります。 .Pp .Fn fts_children , .Fn fts_open , .Fn fts_set がエラーになると、以下のように .Va errno を設定します。 .Bl -tag -width Er .It Bq Er EINVAL オプションが正しくありません。 .El .Sh 関連項目 .Xr find 1 , .Xr chdir 2 , .Xr stat 2 , .Xr qsort 3 .Pp .Sh 規格 .Nm ユーティリティは、将来、 .St -p1003.1-88 リビジョンに組み込まれると思われます。 .\"X kuma 99-10-21