Provided by: manpages-ja-dev_0.5.0.0.20210215+dfsg-1_all bug

名前

       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;

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

       fts_info    このフィールドは、返された FTSENT 構造体とファイルを説明する以下のフラグのいず
                   れかを表している。 エラーのないディレクトリ (FTS_D),  の場合は例外として、それ
                   以外のすべてのエントリーは終端である。  つまり、エントリーは再びたどられること
                   もなく、 それより下の階層がたどられることもない。

                   FTS_D       preorder でたどられるディレクトリ。

                   FTS_DC      ツリーの中で循環しているディレクトリ。 (FTSENT 構造体の  fts_cycle
                               フィールドも同様に埋められる。)

                   FTS_DEFAULT ファイルタイプを表現する FTSENT 構造体が、 fts_info の他のいずれか
                               の値で明示的に説明されていない。

                   FTS_DNR     読み込みができないディレクトリ。    これはエラーの場合の返り値であ
                               り、 何がエラーを起こしたかを示すために fts_errno フィールドが設定
                               される。

                   FTS_DOT     fts_open()  へのファイル名として指定されなかった "."  または  ".."
                               という名前のファイル (FTS_SEEDOT を参照すること)。

                   FTS_DP      postorder     でたどられるディレクトリ。    FTSENT    構造体の内容
                               は、preorder のときに返された状態 (つまり、 fts_info  フィールドが
                               FTS_D に設定されている状態) から変更されない。

                   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 構造体では -1 とな
                   る。 また、ルート自身の FTSENT 構造体では 0 になる。

       fts_errno   関数  fts_children()   と  fts_read()   から返される  FTSENT 構造体の fts_info
                   フィールドが FTS_DNR, FTS_ERR, FTS_NS に設定されている場合、 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 フィールドはディレクトリメンバーの
                   ヌル終端されたリンクリストの形式で、  次の構造体を指し示す。  それ以外の場合、
                   fts_link フィールドは定義されない。

       fts_cycle   2  つのディレクトリにハードリンクが張られているため、 または、シンボリックリン
                   クがあるディレクトリを指しているために、  ディレクトリが循環する階層構造を作っ
                   ている場合  (FTS_DC  を参照)、 構造体の fts_cycle フィールドは、階層中で現在の
                   FTSENT 構造体と同じファイルを参照している FTSENT 構造体を指し示す。 それ以外の
                   場合、 fts_cycle フィールドは定義されない。

       fts_statp   このファイルの stat(2)  情報へのポインター。

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

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

       多くのオプションがあり、少なくとも  1 つ (FTS_LOGICAL または FTS_PHYSICAL)  が指定されなけ
       ればならない。 オプションは以下の値の論理和をとって選択する。

       FTS_COMFOLLOW
                    このオプションは、 FTS_LOGICAL の指定にかかわらず、  ルートパスに指定されたシ
                    ンボリックリンクをすぐにたどらせる。

       FTS_LOGICAL  このオプションは、  fts ルーチンにシンボリックリンクそのものではなく、 シンボ
                    リックリンクが指しているファイルの FTSENT 構造体を返させる。 このオプションが
                    設定された場合、 FTSENT 構造体がアプリケーションに返されるような シンボリック
                    リンクのみが、存在しないファイルを参照している。      FTS_LOGICAL      または
                    FTS_PHYSICAL のどちらかを、 fts_open()  関数に与えなければ「ならない」。

       FTS_NOCHDIR  パフォーマンスの最適化のため、 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 つとり、 1 番目の引き数で参
       照されているファイルが 2 番目の引き数で参照されているファイルより 前にある場合は負の値・同
       じ場合はゼロ・後にある場合は正の値を 返さなければならない。 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  回は  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()
       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_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()  によって最も新しく返されたファイルに
                    ついてのみ意味を持つ。 通常は、postorder でディレクトリをたどる場合に使用し、
                    その下の階層と同様に、 ディレクトリを (preorder と postorder の両方で) 再びた
                    どらせる。

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

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

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

   fts_close()
       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 が次の値にされる。

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

バージョン

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

準拠

       4.4BSD.

バグ

       このマニュアルページで説明した API はいずれも、 LFS API を使うプログラムをコンパイルする場
       合 (例えば、-D_FILE_OFFSET_BITS=64 でコンパイルする場合など)、安全ではない。

関連項目

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

この文書について

       この  man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクト
       の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。