| FTS(3) | Linux Programmer's Manual | FTS(3) |
fts, fts_open, fts_read, fts_children, fts_set, fts_close - ファイル階層をたどる
#include <sys/types.h>
#include <sys/stat.h>
#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 関数群は、ファイル階層をたどるために提供されている。 簡単に概略すると次のようになる。 fts_open() 関数は、他の fts 関数群に渡すための、ファイル階層の「ハンドル」を返す。 fts_read() 関数は、ファイル階層中にある 1 つのファイルを記述する構造体へのポインターを返す。 fts_children() 関数は、階層中のディレクトリにあるファイルを記述する構造体の リンクリストへのポインターを返す。 一般にディレクトリは、 preorder (正方向：下の階層のディレクトリをたどる前) と postorder (逆方向：下の階層のディレクトリをすべてたどった後) という、 異なる方向で 2 回たどられる。ファイルは 1 回たどられる。 ディレクトリ階層を「論理的に」(シンボリックリングが指すファイルを見て) 辿ることも、 物理的に (シンボリックリンク自身を見て) 辿ることも可能である。 また、階層中の移動の道筋を指示すること・ 余分なものを取り除くこと・階層の一部を再びたどることが可能である。
2
つの構造体がインクルードファイル
<fts.h>
で定義されている
(さらに typedef
されている)。 1
つ目は、ファイル階層そのものを表現する
FTS 構造体である。 2
つ目は、ファイル階層中のファイルを表現する
FTSENT 構造体である。
FTSENT
構造体は通常、ファイル階層中のすべてのファイルに対して返される。
この man
ページでは、「ファイル」と
「FTSENT
構造体」を一般に読み変えることができる。
FTSENT
構造体は、少なくとも次のようなフィールドを持っており、
以下でより詳しく説明されている。
typedef struct _ftsent {
unsigned 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;
これらのフィールドは、次のように定義されている。
ファイル階層中のすべてのファイルのパスに対して、 ただ 1 つのバッファーが使われる。 したがって、 fts_path と fts_accpath フィールドは、 fts_read() によって返された最も新しいファイルに対して「のみ」ヌル終端されることが保証される。 これらのフィールドを、他の FTSENT 構造体で表現されるファイルを参照するために使うには、 FTSENT 構造体の fts_pathlen フィールドにある情報を使ってパスのバッファーを修正する必要がある。 これらの修正は、さらに fts_read() を呼び出そうとする場合には、元に戻しておかなければならない。 fts_name フィールドは、常に NUL 終端される。
fts_open() 関数は、文字列ポインターの配列へのポインターを引き数に取る。 この文字列ポインターは、論理ファイル階層をつくる 1 つ以上のパスの名前になる。 配列は、 null ポインターで終端されなければならない。
多くのオプションがあり、少なくとも 1 つ (FTS_LOGICAL または FTS_PHYSICAL) が指定されなければならない。 オプションは以下の値の論理和をとって選択する。
引き数 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() 関数は、階層中のファイルを記述する FTSENT 構造体へのポインターを返す。 (読み込み可能で、循環していない) ディレクトリは、 1 回は preorder で、もう 1 回は postorder で、少なくとも 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() 関数によって postorder で FTSENT 構造体が返された後、 fts_read() の呼出しがあるまで、 これらの構造体は上書きされない。
fts_children() 関数は、 FTSENT 構造体へのポインターを返す。 この構造体は、( fts_read() で最も新しく返された FTSENT 構造体で表現されるディレクトリにあるファイルの) ヌル終端されたリンクリストの最初のエントリーを記述する。 このリストは、 FTSENT 構造体の fts_link フィールドを使ってリンクされ、 ユーザー指定の比較関数がある場合は、それで順序づけられる。 fts_children() の呼出しを繰り返すことで、 このリンクリストは再生成される。
特別な場合として、 fts_read() がファイル階層について呼ばれていない場合、 fts_children() は fts_open() に指定された論理ディレクトリ (つまり、 fts_open() に指定された引き数) の中にあるファイルへのポインターを返す。 それ以外の場合で、 fts_read() によって最も新しく返された FTSENT 構造体が preorder でたどられたディレクトリでない場合や 何も含んでいないディレクトリの場合は、 fts_children() は NULL を返し、 errno を 0 にする。 エラーが起こった場合、 fts_children() は NULL を返し、 errno をエラーに対応した値にする。
fts_children() によって返される FTSENT 構造体は、同じファイル階層ストリームへの fts_children(), fts_close(), fts_read() の呼出しの後に上書きされる場合がある。
option は、次の値に設定できる。
関数 fts_set() は、ユーザーアプリケーションが ストリーム ftsp のファイル f について更なる処理を決定すること許す。 fts_set() 関数は、成功した場合は 0 を、エラーが起こった場合は -1 を返す。 option は、次の値のいずれか 1 つに設定されなければならない。
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 が次の値にされる。
これらの関数は、Linux では glibc2 から使用可能である。
4.4BSD.
このマニュアルページで説明した API はいずれも、 LFS API を使うプログラムをコンパイルする場合 (例えば、-D_FILE_OFFSET_BITS=64 でコンパイルする場合など)、安全ではない。
この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。
| 2014-03-18 | Linux |