日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
FTS(3) FreeBSD ライブラリ関数マニュアル FTS(3)
名称
fts -- ファイルの階層を横断する
ライブラリ
標準 C ライブラリ (libc, -lc)
書式
#include <fts.h>
FTS *
fts_open(char * const *path_argv, int options,
int (*compar)(const FTSENT * const *, const FTSENT * const *));
FTSENT *
fts_read(FTS *ftsp);
FTSENT *
fts_children(FTS *ftsp, int options);
int
fts_set(FTS *ftsp, FTSENT *f, int options);
void
fts_set_clientptr(FTS *ftsp, void *clientdata);
void *
fts_get_clientptr(FTS *ftsp);
FTS *
fts_get_stream(FTSENT *f);
int
fts_close(FTS *ftsp);
解説
fts 関数は、UNIX ファイル階層を横断するために提供されます。簡単な概要は、
fts_open() 関数は、他の fts 関数に供給される、ファイル階層の ``ハンドル''
を返すということです。関数 fts_read() は、ファイル階層のファイルの 1 つを
表す構造体へのポインタを返します。関数 fts_children() は、階層のディレク
トリに含まれていたファイルの 1 つを表す各々の構造体のリンクしたリストへの
ポインタを返します。一般的に、ディレクトリは、前の順序 (それらの任意の子
がアクセスされる前) と、後の順序 (それらの子のすべてがアクセスされた後)
で、2 回アクセスされます。ファイルは、1 度アクセスされます。階層または階
層の部分を取り除いて再アクセスするか取り除くかまたは再アクセスするかの移
動の順序で、階層を ``論理的に'' (シンボリックリンクを無視して) または物理
的に (シンボリックリンクをアクセスして) 移動させることは可能です。
2 つの構造体 (と typedef) がインクルードファイル <fts.h> に定義されます。
最初は、ファイル階層自体を表現する構造体 FTS です。2 つめは、ファイル階層
でファイルを表現する構造体 FTSENT です。通常は、FTSENT 構造体は、ファイル
階層中のすべてのファイルのために返されます。このマニュアルページで、
``ファイル'' と ``FTSENT 構造体'' は、一般的に交換可能です。
FTS 構造体は、1 つのポインタのための空間を含んでいます。それは、アプリ
ケーションデータか階層ごとの状態を格納するために使用されます。
fts_set_clientptr() と fts_get_clientptr() 関数は、このポインタを設定する
か取得するために使用されます。これは、fts_get_stream() 関数を使用する引数
の元の FTS のストリームを決定することができる、ソートの比較機能からアクセ
スされるときにだけ役に立ちそうです。2 つの get 関数は、また同じ名前のマク
ロとして利用可能です。
FTSENT 構造体は、少なくとも次のフィールドを含んでいます。それらは、後でよ
り詳しく説明されます。
typedef struct _ftsent {
int fts_info; /* FTSENT 構造体の状態 */
char *fts_accpath; /* アクセスパス */
char *fts_path; /* ルートパス */
size_t fts_pathlen; /* strlen(fts_path) */
char *fts_name; /* ファイル名 */
size_t fts_namelen; /* strlen(fts_name) */
long fts_level; /* 深さ (-1 to N) */
int fts_errno; /* ファイル errno */
long long fts_number; /* ローカル数値 */
void *fts_pointer; /* ローカルアドレス値 */
struct ftsent *fts_parent; /* 親ディレクトリ */
struct ftsent *fts_link; /* 次のファイル構造体 */
struct ftsent *fts_cycle; /* cycle 構造体 */
struct stat *fts_statp; /* stat(2) 情報 */
} FTSENT;
これらのフィールドは、次のように定義されます。
fts_info 返された FTSENT 構造体とそれが表わすファイルについて記述する
次の値のうちの 1 つです。エラー (FTS_D) のないディレクトリを
除いて、これらのエントリのすべては末端です。すなわち、それら
は、再アクセスされし、子のうちのいずれもアクセスされません。
FTS_D 前の順序でアクセスされるディレクトリ。
FTS_DC ツリーの循環の要因となるディレクトリ。(FTSENT
構造体の fts_cycle フィールドは、同様に書き入れ
られます。)
FTS_DEFAULT 他の fts_info 値のうちの 1 つによってはっきりと
説明されないファイルタイプを表す FTSENT 構造体
です。
FTS_DNR 読み込むことができないディレクトリです。これ
は、エラー返りで、fts_errno フィールドは、何が
エラーの原因となったかを示す値が設定されます。
FTS_DOT fts_open() へのファイル名として指定されなかった
`.' または `..' と名前が付けられたファイルで
す。(FTS_SEEDOT を参照)。
FTS_DP 後の順序でアクセスされているディレクトリです。
FTSENT 構造体の内容は、fts_info フィールドを除
いて、ディレクトリが前の順序で訪問された時から
変更されません。
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_DNR, FTS_ERR または FTS_NS に設定されている fts_info
フィールドをつけて fts_children() または fts_read() 関数から
FTSENT 構造体を返すとき、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 フィールド
は、ディレクトリメンバの NULL で終了したリンクしたリスト中の
次の構造体を指します。そうでなければ、fts_link フィールドの
内容は、未定義です。
fts_cycle 2 つのディレクトリの間のハードリンクまたはディレクトリを指す
シンボリックリンクのために、ディレクトリが階層中 (FTS_DC を
参照) で循環の原因となっているなら、構造体の fts_cycle
フィールドは、現在の FTSENT 構造体と同じファイルに参照する階
層の FTSENT 構造を指します。そうでなければ、fts_cycle フィー
ルドの内容は、未定義です。
fts_statp ファイルのための stat(2) 情報へのポインタです。
1 つのバッファは、ファイル階層中のすべてのファイルのすべてのパスのために
使用されます。したがって、fts_path と fts_accpath フィールドは、
fts_read() によって最近返されたファイルのみヌル文字で終了していることが保
証されます。他の FTSENT 構造体によって表わされる任意のファイルを参照する
これらのフィールドを使用するために、パスバッファがその FTSENT 構造体の
fts_pathlen フィールドに含まれていた情報を使用して修正されることが要求さ
れます。fts_read() へのさらなる呼び出しを試みる前に、そのような修正を元に
戻すべきです。fts_name フィールドは、常にヌル文字で終了します。
FTS_OPEN
fts_open() 関数は、横断される論理的なファイル階層を構成する 1 つ以上のパ
スを指定する文字ポインタの配列へのポインタを取ります。配列は、NULL ポイン
タによって終了しなければなりません。
FTS_LOGICAL または FTS_PHYSICAL のいずれかの少なくとも 1 つを指定されなけ
ればならない、多くのオプションがあります。オプションは、次の値を論理和
(or) することによって選択されます。
FTS_COMFOLLOW
FTS_LOGICAL が指定されても指定されなくても、ルートパスとし
て指定されたどんなシンボリックリンクも、このオプションに
よって直ちに追跡されます。
FTS_LOGICAL このオプションによって fts ルーチンに、シンボリックリンクそ
れら自体の代わりにシンボリックリンクのターゲットのための
FTSENT 構造体が返されるようになります。このオプションが設定
されるなら、アプリケーションに返される FTSENT 構造体のため
の唯一のシンボリックリンクは、存在しないファイルの参照で
す。FTS_LOGICAL または FTS_PHYSICAL のいずれかは fts_open()
関数に提供されなければなりません。
FTS_NOCHDIR ({PATH_MAX} と無関係に) 任意の深さに下降することができ、性
能を改善するために、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 つのポインタを
取り、最初の引数によって参照されるファイルが 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 度アクセスされます。(循環を引き起こさないディレクトリ
の間のハードリンクまたはシンボリックリンクへのシンボリックリンクは、ファ
イルを 2 度以上またはディレクトリを 3 度以上アクセスする原因となるかもし
れません。)
階層のすべてのメンバが返されたなら、fts_read() は、NULL を返し、外部変数
errno に 0 を設定します。階層中のファイルと無関係なエラーが生じるなら、
fts_read() は、NULL を返し、errno を適切な値を設定します。返されたファイ
ルと関係するエラーが生じるなら、FTSENT 構造体へのポインタが返され、errno
は、設定されるしれないし、設定されないかもしれません (fts_info を参照)。
fts_read() によって返された FTSENT 構造体は、同じファイル階層ストリームに
関して fts_close() への呼び出しの後に、または、それらがタイプディレクトリ
のファイルを表わさなければ、同じファイル階層ストリームに関して fts_read()
への呼び出しの後に上書きされます。その場合には、後の順序で FTSENT 構造体
が関数 fts_read() によって返された後に、fts_read() への呼び出しの後まで、
それらは、上書きされません。
FTS_CHILDREN
fts_children() 関数は、fts_read() によって最近返された FTSENT 構造体に
よって表わされるディレクトリのファイルの NULL で終了したリンクしたリスト
の最初のエントリを表す FTSENT 構造体へのポインタを返します。リストは、
FTSENT 構造体の fts_link フィールドでリンクされ、ユーザ指定の比較関数があ
れば、それによって順序付けられます。fts_children() を繰り返し呼び出すと、
このリンクしたリストを再作成させます。
特別の場合として、fts_read() が階層のためにまだ呼び出されていないなら、
fts_children() は、fts_open() に指定された論理的なディレクトリのファイル
(すなわち fts_open() に指定された引数) へのポインタを返します。そうでなけ
れば、fts_read() によって最近返された FTSENT 構造体が前の順序でアクセスさ
れたディレクトリでないか、ディレクトリがファイルを含んでいないなら、
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() からの最近
返されたファイルのためだけに意味があります。ディレクトリが
その子のすべてと同様に前の順序と後の順序の両方で再度アクセ
スされるところで、通常は、後の順序のディレクトリをアクセス
するために使用されます。
FTS_FOLLOW 参照されたファイルは、シンボリックリンクでなければなりませ
ん。参照されたファイルが fts_read() によって最近返された
ファイルであるなら、fts_read() への次の呼び出しは、シンボ
リックリンク自体の代わりにシンボリックリンクのターゲットを
反映するために再初期化した fts_info と fts_statp のフィール
ドでファイルを返します。ファイルが fts_children() によって
最近返されたもののうちの 1 つであるなら、構造体の fts_info
と fts_statp のフィールドは、fts_read() によって返されたと
き、シンボリックリンク自体の代わりにシンボリックリンクの
ターゲットを反映します。どちらの場合でも、シンボリックリン
クのターゲットが存在しないなら、返された構造体のフィールド
は、変更されません、そして、fts_info フィールドは、
FTS_SLNONE に設定されます。
リンクのターゲットがディレクトリであるなら、前の順序の返
り、その子のすべての返り、後の順序の返り、が続けて行われま
す。
FTS_SKIP このファイルの子は、アクセスされません。ファイルは、
fts_children() か fts_read() のいずれかによって最近返された
もののうちの 1 つかもしれません。
FTS_CLOSE
fts_close() 関数は、ファイル階層ストリーム ftsp をクローズして、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 を設定します。
[EINVAL] オプションが無効であったか、またはリストが空です。
関連項目
find(1), chdir(2), stat(2), ftw(3), qsort(3)
歴史
fts インタフェースは、4.4BSD ではじめて導入されました。
fts_get_clientptr(), fts_get_stream() と fts_set_clientptr() 関数は、主に
異なったデータ構造を使用することで fts の機能のための代替のインタフェース
を提供するために、FreeBSD 5.0 で導入されました。
バグ
fts_open() 関数は、FTS_LOGICAL オプションが提供されるか、または、カレント
ディレクトリを open(2) (オープン) することができないなら、自動的に
FTS_NOCHDIR オプションを設定します。
FreeBSD 11.2 January 12, 2014 FreeBSD 11.2