release/man3/ftw.3

   1 .\" Copyright (c) 1993 Michael Haardt (michael@moria.de)
   2 .\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
   3 .\" and copyright (c) 2006 Justin Pryzby <justinpryzby@users.sf.net>
   4 .\" and copyright (c) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   5 .\"
   6 .\" This is free documentation; you can redistribute it and/or
   7 .\" modify it under the terms of the GNU General Public License as
   8 .\" published by the Free Software Foundation; either version 2 of
   9 .\" the License, or (at your option) any later version.
  10 .\"
  11 .\" The GNU General Public License's references to "object code"
  12 .\" and "executables" are to be interpreted as the output of any
  13 .\" document formatting or typesetting system, including
  14 .\" intermediate and printed output.
  15 .\"
  16 .\" This manual is distributed in the hope that it will be useful,
  17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 .\" GNU General Public License for more details.
  20 .\"
  21 .\" You should have received a copy of the GNU General Public
  22 .\" License along with this manual; if not, write to the Free
  23 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  24 .\" USA.
  25 .\"
  26 .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu)
  27 .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net>
  28 .\"     document FTW_ACTIONRETVAL; include .SH "RETURN VALUE";
  29 .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> and
  30 .\"     Michael Kerrisk <mtk.manpages@gmail.com>
  31 .\"     reorganized and rewrote much of the page
  32 .\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com>
  33 .\"     Added an example program.
  34 .\"*******************************************************************
  35 .\"
  36 .\" This file was generated with po4a. Translate the source file.
  37 .\"
  38 .\"*******************************************************************
  39 .TH FTW 3 2010\-09\-20 Linux "Linux Programmer's Manual"
  40 .SH 名前
  41 ftw, nftw \- ファイルツリーを歩きまわる
  42 .SH 書式
  43 .nf
  44 \fB#include <ftw.h>\fP
  45 .sp
  46 \fBint ftw(const char *\fP\fIdirpath\fP\fB,\fP
  47 \fB        int (*\fP\fIfn\fP\fB) (const char *\fP\fIfpath\fP\fB, const struct stat *\fP\fIsb\fP\fB,\fP
  48 \fB                   int \fP\fItypeflag\fP\fB),\fP
  49 \fB        int \fP\fInopenfd\fP\fB);\fP
  50 .sp
  51 \fB#define _XOPEN_SOURCE 500\fP   /* feature_test_macros(7) 参照 */
  52 \fB#define _XOPEN_SOURCE 500\fP
  53 \fB#include <ftw.h>\fP
  54 .sp
  55 \fBint nftw(const char *\fP\fIdirpath\fP\fB,\fP
  56 \fB        int (*\fP\fIfn\fP\fB) (const char *\fP\fIfpath\fP\fB, const struct stat *\fP\fIsb\fP\fB,\fP
  57 \fB                   int \fP\fItypeflag\fP\fB, struct FTW *\fP\fIftwbuf\fP\fB),\fP
  58 \fB        int \fP\fInopenfd\fP\fB, int \fP\fIflags\fP\fB);\fP
  59 .fi
  60 .SH 説明
  61 \fBftw\fP()  は、 \fIdirpath\fP で指定されたディレクトリ以下のディレクトリツリー全体を歩きまわり、 ツリー中でエントリが見付かるごとに、
  62 \fIfn\fP()  を呼び出す。 デフォルトでは、ディレクトリそのものが、そのディレクトリにあるファイルや サブディレクトリよりも先に処理される
  63 (行きがけ順探索; preorder traversal)。
  64
  65 呼び出し元プロセスが利用可能なファイルディスクリプタを使い切って しまわないようにするため、 \fBftw\fP()
  66 が同時にオープンするディレクトリの最大数を \fInopenfd\fP で指定することができる。 探索の深さがこの値を越えると、
  67 一つのディレクトリを閉じてから他のディレクトリをオープンし直すこと になるので、 \fBftw\fP()  の動作は遅くなる。 \fBftw\fP()
  68 は、ディレクトリツリーの階層 1 レベルにつき、 最大でも一つのファイルディスクリプタしか使用しない。
  69
  70 ディレクトリツリーで見つかったエントリ毎に、 \fBftw\fP()  は \fIfpath\fP, \fIsb\fP, \fItypeflag\fP の 3つを引き数として
  71 \fIfn\fP()  を呼び出す。 \fIfpath\fP はエントリのパス名である。 \fIdirpath\fP が相対パス名で指定された場合には、 \fIfpath\fP
  72 は \fBftw\fP()  が呼び出された時点の呼び出し元プロセスのカレントワーキングディレクトリ からの相対パス名となる。 \fIdirpath\fP
  73 が絶対パス名で指定された場合には、 \fIfpath\fP は絶対パス名となる。 \fIsb\fP は \fIfpath\fP に対する \fBstat\fP(2)
  74 の呼び出しで返される \fIstat\fP 構造体へのポインタである。 \fItypeflag\fP は整数で、以下の値のいずれか一つである:
  75 .TP
  76 \fBFTW_F\fP
  77 \fIfpath\fP が通常のファイルである
  78 .TP
  79 \fBFTW_D\fP
  80 \fIfpath\fP がディレクトリである
  81 .TP
  82 \fBFTW_DNR\fP
  83 \fIfpath\fP が読み込みできないディレクトリである
  84 .TP
  85 \fBFTW_NS\fP
  86 シンボリックリンクではない \fIfpath\fP に対する \fBstat\fP(2)  呼び出しが失敗した。
  87 .sp
  88 \fIfpath\fP がシンボリックリンクで、かつ \fBstat\fP(2)  が失敗した場合、 \fBFTW_NS\fP と \fBFTW_SL\fP (後述)
  89 のどちらが \fItypeflag\fP に渡されるかは未定義であると、POSIX.1\-2001 には書かれている。
  90 .PP
  91 ツリーの探索を止めたい場合は、 \fIfn\fP()  が 0 以外の値を返せば良い (この値は \fBftw\fP()  自身の戻り値となる)。 それ以外の場合は
  92 \fBftw\fP()  はツリー全体の探索を続け、すべてのツリーを探索し終えたところで 0 を返す。探索中に (\fBmalloc\fP(3)  の失敗などの)
  93 エラーが起こると \-1 を返す。
  94 .PP
  95 \fBftw\fP()  は動的なデータ構造を用いるので、ツリー探索を安全に中断する唯一の方法は 0 以外の値を \fIfn\fP()
  96 の返り値とすることである。割り込みを扱うには、 例えば発生した割り込みをマークしておいて、 0 以外の値を返すようにする
  97 シグナルによりメモリリークを起こさずに探索を終了できるようにするには、 シグナルハンドラで \fIfn\fP()
  98 がチェックするグローバルなフラグをセットするようにすればよい。 プログラムを終了させる場合以外は、 \fBlongjmp\fP(3)  を使用しないこと。
  99 .SS nftw()
 100 関数 \fBnftw\fP()  は \fBftw\fP()  と同じだが、引き数 \fIflags\fP が追加される点と、 \fIfn\fP()  の引き数に
 101 \fIftwbuf\fP が追加される点が異なる。
 102
 103 この \fIflags\fP 引き数は下記のフラグの 0 個以上の論理和を取ったものである:
 104 .TP
 105 \fBFTW_ACTIONRETVAL\fP (glibc 2.3.3 以降)
 106 このフラグは glibc 固有である。 このフラグをセットすると、 \fBnftw\fP()  の \fIfn\fP()  の返り値の扱いが変わる。 \fIfn\fP()
 107 は以下の値のいずれか一つを返す必要がある。
 108 .RS
 109 .TP
 110 \fBFTW_CONTINUE\fP
 111 \fBnftw\fP()  は通常通り処理を続ける。
 112 .TP
 113 \fBFTW_SKIP_SIBLINGS\fP
 114 .\" If \fBFTW_DEPTH\fP
 115 .\" is set, the entry's parent directory is processed next (with
 116 .\" \fIflag\fP set to \fBFTW_DP\fP).
 117 \fIfn\fP()  がこの値を返した場合、処理中のエントリの兄弟 (同じ階層のエントリ)  の処理はスキップされ、親ディレクトリで続きの処理が行われる。
 118 .TP
 119 \fBFTW_SKIP_SUBTREE\fP
 120 \fIfn\fP()  が呼び出されたエントリがディレクトリ (\fItypeflag\fP が \fBFTW_D\fP)  の場合に、この値を返すと \fIfn\fP()
 121 の引き数として渡されたディレクトリ内のエントリの処理が行われなくなる。 \fBnftw\fP()  は処理中のディレクトリの兄弟 (同じ階層のエントリ)
 122 から処理を続ける。
 123 .TP
 124 \fBFTW_STOP\fP
 125 \fBnftw ()\fP は、返り値 \fBFTW_STOP\fP ですぐに復帰する。
 126 .PP
 127 他の返り値は将来新しい動作に対応付けられる可能性がある。 \fIfn\fP()  は上記のリストにある値以外を返さないようにすべきである。
 128
 129 \fI<ftw.h>\fP で \fBFTW_ACTIONRETVAL\fP の定義が有効にするためには、
 130 (「どの」ヘッダファイルをインクルードするよりも前に)  機能検査マクロ \fB_GNU_SOURCE\fP を定義しなければならない。
 131 .RE
 132 .TP
 133 \fBFTW_CHDIR\fP
 134 セットされると、ディレクトリの内容を処理する前に そのディレクトリに \fBchdir\fP(2)  する。このフラグは、 \fIfpath\fP
 135 が属すディレクトリで何らかの動作を実行する必要がある場合に 便利である。
 136 .TP
 137 \fBFTW_DEPTH\fP
 138 セットされると、帰りがけ順探索 (post\-order traversal) を行う。 つまり、ディレクトリそのものを引き数とした \fIfn\fP()
 139 呼出しは、そのディレクトリに含まれるファイルとサブディレクトリに 対する処理の「後で」行われる
 140 (デフォルトでは、ディレクトリ自身の処理はディレクトリ内のエントリ より「前に」行なわれる)。
 141 .TP
 142 \fBFTW_MOUNT\fP
 143 セットされると、同じファイルシステムの中だけを探索対象とする (つまり、マウントポイントをまたぐことはない)。
 144 .TP
 145 \fBFTW_PHYS\fP
 146 セットされると、シンボリックリンクを辿らない (おそらくこちらが 通常望ましい動作だろう)。セットされていないとシンボリックリンクを
 147 辿るが、同じファイルが二回報告されることはない。
 148 .sp
 149 \fBFTW_PHYS\fP がセットされずに \fBFTW_DEPTH\fP がセットされると、自分自身に対するシンボリックリンクを配下に持つ
 150 ディレクトリに対して \fIfn\fP()  が呼び出されることは決してない。
 151 .LP
 152 ディレクトリツリーのエントリ毎に、 \fBnftw\fP()  は 4つの引き数で \fIfn\fP()  を呼び出す。 \fIfpath\fP と \fIsb\fP は
 153 \fBftw\fP()  と同じである。 \fItypeflag\fP には、 \fBftw\fP()  で取り得る値のいずれか、または以下の値のいずれかが渡される:
 154 .TP
 155 \fBFTW_DP\fP
 156 \fIfpath\fP がディレクトリで、かつ \fIflags\fP で \fBFTW_DEPTH\fP が指定されていた。 \fIfpath\fP
 157 配下のファイルとサブディレクトリは全て処理が終わっている。
 158 .TP
 159 \fBFTW_SL\fP
 160 .\" To obtain the definition of this constant from
 161 .\" .IR <ftw.h> ,
 162 .\" either
 163 .\" .B _BSD_SOURCE
 164 .\" must be defined, or
 165 .\" .BR _XOPEN_SOURCE
 166 .\" must be defined with a value of 500 or more.
 167 \fIfpath\fP がシンボリックリンクで、かつ \fBFTW_PHYS\fP が \fIflags\fP に セットされていた。
 168 .TP
 169 \fBFTW_SLN\fP
 170 \fIfpath\fP がシンボリックリンクで、存在しないファイルを指している (これがセットされるのは \fBFTW_PHYS\fP
 171 がセットされていない場合だけである)。
 172 .LP
 173 \fBnftw\fP()  が \fIfn\fP()  を呼び出す際に渡す 4つめの引き数は \fIFTW\fP 型の構造体である。
 174 .in +4n
 175 .nf
 176
 177 struct FTW {
 178     int base;
 179     int level;
 180 };
 181
 182 .fi
 183 .in
 184 \fIbase\fP は、ファイル名 (basename 要素) の、 \fIfpath\fP で渡されるパス名の中でのオフセットである。 \fIlevel\fP
 185 はディレクトリツリーでの \fIfpath\fP の深さを示す。深さはディレクトリツリーのトップ (root) からの 相対値である (\fIdirpath\fP
 186 は深さ 0 である)。
 187 .SH 返り値
 188 これらの関数は、成功すると 0 を、エラーが発生すると \-1 を返す。
 189
 190 \fIfn\fP()  が 0 以外を返した場合、ディレクトリツリーの探索を終了し、 \fIfn\fP()  が返した値を \fBftw\fP()  や
 191 \fBnftw\fP()  の結果として返す。
 192
 193 \fBnftw\fP()  が \fBFTW_ACTIONRETVAL\fP フラグ付きで呼ばれた場合、ツリーの探索を終了させるために \fIfn\fP()
 194 が使用できる、非 0 の値は \fBFTW_STOP\fP だけであり、 この値は \fBnftw\fP()  の返り値として返される。
 195 .SH 準拠
 196 POSIX.1\-2001, SVr4, SUSv1.  POSIX.1\-2008 は \fBftw\fP()  を廃止予定としている。
 197 .SH 注意
 198 POSIX.1\-2001 の注記によると、 \fIfn\fP がカレントワーキングディレクトリを保持しなかった場合の 結果は規定されていないとされている。
 199 .PP
 200 \fBnftw\fP()  関数と、 \fBftw\fP()  における \fBFTW_SL\fP は、SUSv1 で導入された。
 201 .LP
 202 \fBftw\fP()  で \fBFTW_SL\fP を一切使わないシステムや、 存在しないファイルを指しているシンボリックリンクの場合にのみ \fBFTW_SL\fP
 203 を使うシステム、また \fBftw\fP()  が全てのシンボリックリンクに対して \fBFTW_SL\fP を使うシステムもある。
 204 予測可能な動作をさせるためには、 \fBnftw\fP()  を使うこと。
 205 .LP
 206 Linux では、 libc4, libc5, glibc 2.0.6 は 「stat できるがディレクトリではないオブジェクト」 (ファイル,
 207 シンボリックリンク, fifo 等)  に対してはすべて \fBFTW_F\fP を使う。
 208
 209 \fBnftw\fP()  関数は glibc 2.1 以降で利用できる。
 210
 211 \fBFTW_ACTIONRETVAL\fP は glibc 固有である。
 212 .SH 例
 213 以下のプログラムは、一つ目のコマンドライン引き数を名前に持つパス以下の ディレクトリツリーを探索する。引き数が指定されなかった場合は、
 214 カレントディレクトリ以下を探索する。 各々のファイルについて様々の情報が表示される。 二番目のコマンドライン引き数に文字を指定することで、
 215 \fBnftw\fP()  を呼び出す際に \fIflags\fP 引き数に渡す値を制御することができる。
 216 .nf
 217
 218 #define _XOPEN_SOURCE 500
 219 #include <ftw.h>
 220 #include <stdio.h>
 221 #include <stdlib.h>
 222 #include <string.h>
 223 #include <stdint.h>
 224
 225 static int
 226 display_info(const char *fpath, const struct stat *sb,
 227              int tflag, struct FTW *ftwbuf)
 228 {
 229     printf("%\-3s %2d %7jd   %\-40s %d %s\en",
 230         (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
 231         (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
 232         (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
 233         (tflag == FTW_SLN) ? "sln" : "???",
 234         ftwbuf\->level, (intmax_t) sb\->st_size,
 235         fpath, ftwbuf\->base, fpath + ftwbuf\->base);
 236     return 0;           /* To tell nftw() to continue */
 237 }
 238
 239 int
 240 main(int argc, char *argv[])
 241 {
 242     int flags = 0;
 243
 244     if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL)
 245         flags |= FTW_DEPTH;
 246     if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL)
 247         flags |= FTW_PHYS;
 248
 249     if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
 250             == \-1) {
 251         perror("nftw");
 252         exit(EXIT_FAILURE);
 253     }
 254     exit(EXIT_SUCCESS);
 255 }
 256 .fi
 257 .SH 関連項目
 258 \fBstat\fP(2), \fBfts\fP(3), \fBreaddir\fP(3)
 259 .SH この文書について
 260 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.41 の一部
 261 である。プロジェクトの説明とバグ報告に関する情報は
 262 http://www.kernel.org/doc/man\-pages/ に書かれている。