diff options
Diffstat (limited to 'documentation/manual-pages/ja/man3/fts.3')
| -rw-r--r-- | documentation/manual-pages/ja/man3/fts.3 | 715 |
1 files changed, 715 insertions, 0 deletions
diff --git a/documentation/manual-pages/ja/man3/fts.3 b/documentation/manual-pages/ja/man3/fts.3 new file mode 100644 index 0000000000..d327a9eb14 --- /dev/null +++ b/documentation/manual-pages/ja/man3/fts.3 @@ -0,0 +1,715 @@ +.\" 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 |