release/man3/ftw.3

   1 .\" Copyright (c) 1993 Michael Haardt (u31b3hs@pool.informatik.rwth-aachen.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., 675 Mass Ave, Cambridge, MA 02139,
  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 .\" Japanese Version Copyright (c) 1998 NAKANO Takeo all rights reserved.
  36 .\" Translated 1998-04-28, NAKANO Takeo <nakano@apm.seikei.ac.jp>
  37 .\" Updated & Modified 1999-09-14, NAKANO Takeo <nakano@apm.seikei.ac.jp>
  38 .\" Updated & Modified 2005-11-04, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  39 .\" Updated 2006-07-26, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.36
  40 .\"
  41 .\" WORD:       file descriptor         ファイルディスクリプター
  42 .\"
  43 .TH FTW 3 2010-09-20 "Linux" "Linux Programmer's Manual"
  44 .SH 名前
  45 ftw, nftw \- ファイルツリーを歩きまわる
  46 .SH 書式
  47 .nf
  48 .B #include <ftw.h>
  49 .sp
  50 .BI "int ftw(const char *" dirpath ,
  51 .BI "        int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
  52 .BI "                   int " typeflag ),
  53 .BI "        int " nopenfd );
  54 .sp
  55 .BR "#define _XOPEN_SOURCE 500" "   /* feature_test_macros(7) 参照 */"
  56 .B #define _XOPEN_SOURCE 500
  57 .B #include <ftw.h>
  58 .sp
  59 .BI "int nftw(const char *" dirpath ,
  60 .BI "        int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
  61 .BI "                   int " typeflag ", struct FTW *" ftwbuf ),
  62 .BI "        int " nopenfd ", int " flags );
  63 .fi
  64 .SH 説明
  65 .BR ftw ()
  66 は、
  67 .I dirpath
  68 で指定されたディレクトリ以下のディレクトリツリー全体を歩きまわり、
  69 ツリー中でエントリが見付かるごとに、
  70 .IR fn ()
  71 を呼び出す。
  72 デフォルトでは、ディレクトリそのものが、そのディレクトリにあるファイルや
  73 サブディレクトリよりも先に処理される (行きがけ順探索; preorder traversal)。
  74
  75 呼び出し元プロセスが利用可能なファイルディスクリプタを使い切って
  76 しまわないようにするため、
  77 .BR ftw ()
  78 が同時にオープンするディレクトリの最大数を
  79 .I nopenfd
  80 で指定することができる。
  81 探索の深さがこの値を越えると、
  82 一つのディレクトリを閉じてから他のディレクトリをオープンし直すこと
  83 になるので、
  84 .BR ftw ()
  85 の動作は遅くなる。
  86 .BR ftw ()
  87 は、ディレクトリツリーの階層 1 レベルにつき、
  88 最大でも一つのファイルディスクリプタしか使用しない。
  89
  90 ディレクトリツリーで見つかったエントリ毎に、
  91 .BR ftw ()
  92 は
  93 .IR fpath ,
  94 .IR sb ,
  95 .I typeflag
  96 の 3つを引き数として
  97 .IR fn ()
  98 を呼び出す。
  99 .I fpath
 100 はエントリのパス名である。
 101 .I dirpath
 102 が相対パス名で指定された場合には、
 103 .I fpath
 104 は
 105 .BR ftw ()
 106 が呼び出された時点の呼び出し元プロセスのカレントワーキングディレクトリ
 107 からの相対パス名となる。
 108 .I dirpath
 109 が絶対パス名で指定された場合には、
 110 .I fpath
 111 は絶対パス名となる。
 112 .I sb
 113 は
 114 .I fpath
 115 に対する
 116 .BR stat (2)
 117 の呼び出しで返される
 118 .I stat
 119 構造体へのポインタである。
 120 .I typeflag
 121 は整数で、以下の値のいずれか一つである:
 122 .TP
 123 .B FTW_F
 124 .I fpath
 125 が通常のファイルである
 126 .TP
 127 .B FTW_D
 128 .I fpath
 129 がディレクトリである
 130 .TP
 131 .B FTW_DNR
 132 .I fpath
 133 が読み込みできないディレクトリである
 134 .TP
 135 .B FTW_NS
 136 シンボリックリンクではない
 137 .I fpath
 138 に対する
 139 .BR stat (2)
 140 呼び出しが失敗した。
 141 .sp
 142 .I fpath
 143 がシンボリックリンクで、かつ
 144 .BR stat (2)
 145 が失敗した場合、
 146 .B FTW_NS
 147 と
 148 .B FTW_SL
 149 (後述) のどちらが
 150 .I typeflag
 151 に渡されるかは未定義であると、POSIX.1-2001 には書かれている。
 152 .PP
 153 ツリーの探索を止めたい場合は、
 154 .IR fn ()
 155 が 0 以外の値を返せば良い
 156 (この値は
 157 .BR ftw ()
 158 自身の戻り値となる)。
 159 それ以外の場合は
 160 .BR ftw ()
 161 はツリー全体の探索を続け、すべてのツリーを探索し終えたところで
 162 0 を返す。探索中に
 163 .RB ( malloc (3)
 164 の失敗などの) エラーが起こると \-1 を返す。
 165 .PP
 166 .BR ftw ()
 167 は動的なデータ構造を用いるので、ツリー探索を安全に中断する唯一の方法は
 168 0 以外の値を
 169 .IR fn ()
 170 の返り値とすることである。割り込みを扱うには、
 171 例えば発生した割り込みをマークしておいて、 0 以外の値を返すようにする
 172 シグナルによりメモリリークを起こさずに探索を終了できるようにするには、
 173 シグナルハンドラで
 174 .IR fn ()
 175 がチェックするグローバルなフラグをセットするようにすればよい。
 176 プログラムを終了させる場合以外は、
 177 .BR longjmp (3)
 178 を使用しないこと。
 179 .SS nftw()
 180 関数
 181 .BR nftw ()
 182 は
 183 .BR ftw ()
 184 と同じだが、引き数
 185 .I flags
 186 が追加される点と、
 187 .IR fn ()
 188 の引き数に
 189 .I ftwbuf
 190 が追加される点が異なる。
 191
 192 この
 193 .I flags
 194 引き数は下記のフラグの 0 個以上の論理和を取ったものである:
 195 .TP
 196 .BR FTW_ACTIONRETVAL " (glibc 2.3.3 以降)"
 197 このフラグは glibc 固有である。
 198 このフラグをセットすると、
 199 .BR nftw ()
 200 の
 201 .IR fn ()
 202 の返り値の扱いが変わる。
 203 .IR fn ()
 204 は以下の値のいずれか一つを返す必要がある。
 205 .RS
 206 .TP
 207 .B FTW_CONTINUE
 208 .BR nftw ()
 209 は通常通り処理を続ける。
 210 .TP
 211 .B FTW_SKIP_SIBLINGS
 212 .IR fn ()
 213 がこの値を返した場合、処理中のエントリの兄弟 (同じ階層のエントリ)
 214 の処理はスキップされ、親ディレクトリで続きの処理が行われる。
 215 .\" If \fBFTW_DEPTH\fP
 216 .\" is set, the entry's parent directory is processed next (with
 217 .\" \fIflag\fP set to \fBFTW_DP\fP).
 218 .TP
 219 .B FTW_SKIP_SUBTREE
 220 .IR fn ()
 221 が呼び出されたエントリがディレクトリ
 222 .RI ( typeflag
 223 が
 224 .BR FTW_D )
 225 の場合に、この値を返すと
 226 .IR fn ()
 227 の引き数として渡されたディレクトリ内のエントリの処理が行われなくなる。
 228 .BR nftw ()
 229 は処理中のディレクトリの兄弟 (同じ階層のエントリ) から処理を続ける。
 230 .TP
 231 .B FTW_STOP
 232 .B nftw ()
 233 は、返り値
 234 .B FTW_STOP
 235 ですぐに復帰する。
 236 .PP
 237 他の返り値は将来新しい動作に対応付けられる可能性がある。
 238 .IR fn ()
 239 は上記のリストにある値以外を返さないようにすべきである。
 240
 241 .I <ftw.h>
 242 で
 243 .B FTW_ACTIONRETVAL
 244 の定義が有効にするためには、
 245 (「どの」ヘッダファイルをインクルードするよりも前に)
 246 機能検査マクロ
 247 .B _GNU_SOURCE
 248 を定義しなければならない。
 249 .RE
 250 .TP
 251 .B FTW_CHDIR
 252 セットされると、ディレクトリの内容を処理する前に
 253 そのディレクトリに
 254 .BR chdir (2)
 255 する。このフラグは、
 256 .I fpath
 257 が属すディレクトリで何らかの動作を実行する必要がある場合に
 258 便利である。
 259 .TP
 260 .B FTW_DEPTH
 261 セットされると、帰りがけ順探索 (post-order traversal) を行う。
 262 つまり、ディレクトリそのものを引き数とした
 263 .IR fn ()
 264 呼出しは、そのディレクトリに含まれるファイルとサブディレクトリに
 265 対する処理の「後で」行われる
 266 (デフォルトでは、ディレクトリ自身の処理はディレクトリ内のエントリ
 267 より「前に」行なわれる)。
 268 .TP
 269 .B FTW_MOUNT
 270 セットされると、同じファイルシステムの中だけを探索対象とする
 271 (つまり、マウントポイントをまたぐことはない)。
 272 .TP
 273 .B FTW_PHYS
 274 セットされると、シンボリックリンクを辿らない (おそらくこちらが
 275 通常望ましい動作だろう)。セットされていないとシンボリックリンクを
 276 辿るが、同じファイルが二回報告されることはない。
 277 .sp
 278 .B FTW_PHYS
 279 がセットされずに
 280 .B FTW_DEPTH
 281 がセットされると、自分自身に対するシンボリックリンクを配下に持つ
 282 ディレクトリに対して
 283 .IR fn ()
 284 が呼び出されることは決してない。
 285 .LP
 286 ディレクトリツリーのエントリ毎に、
 287 .BR nftw ()
 288 は 4つの引き数で
 289 .IR fn ()
 290 を呼び出す。
 291 .I fpath
 292 と
 293 .I sb
 294 は
 295 .BR ftw ()
 296 と同じである。
 297 .I typeflag
 298 には、
 299 .BR ftw ()
 300 で取り得る値のいずれか、または以下の値のいずれかが渡される:
 301 .TP
 302 .B FTW_DP
 303 .I fpath
 304 がディレクトリで、かつ
 305 .I flags
 306 で
 307 .B FTW_DEPTH
 308 が指定されていた。
 309 .I fpath
 310 配下のファイルとサブディレクトリは全て処理が終わっている。
 311 .TP
 312 .B FTW_SL
 313 .I fpath
 314 がシンボリックリンクで、かつ \fBFTW_PHYS\fP が \fIflags\fP に
 315 セットされていた。
 316 .\" To obtain the definition of this constant from
 317 .\" .IR <ftw.h> ,
 318 .\" either
 319 .\" .B _BSD_SOURCE
 320 .\" must be defined, or
 321 .\" .BR _XOPEN_SOURCE
 322 .\" must be defined with a value of 500 or more.
 323 .TP
 324 .B FTW_SLN
 325 .I fpath
 326 がシンボリックリンクで、存在しないファイルを指している
 327 (これがセットされるのは
 328 .B FTW_PHYS
 329 がセットされていない場合だけである)。
 330 .LP
 331 .BR nftw ()
 332 が
 333 .IR fn ()
 334 を呼び出す際に渡す 4つめの引き数は
 335 .I FTW
 336 型の構造体である。
 337 .in +4n
 338 .nf
 339
 340 struct FTW {
 341     int base;
 342     int level;
 343 };
 344
 345 .fi
 346 .in
 347 .I base
 348 は、ファイル名 (basename 要素) の、
 349 .I fpath
 350 で渡されるパス名の中でのオフセットである。
 351 .I level
 352 はディレクトリツリーでの
 353 .I fpath
 354 の深さを示す。深さはディレクトリツリーのトップ (root) からの
 355 相対値である
 356 .RI ( dirpath
 357 は深さ 0 である)。
 358 .SH 返り値
 359 これらの関数は、成功すると 0 を、エラーが発生すると \-1 を返す。
 360
 361 .IR fn ()
 362 が 0 以外を返した場合、ディレクトリツリーの探索を終了し、
 363 .IR fn ()
 364 が返した値を
 365 .BR ftw ()
 366 や
 367 .BR nftw ()
 368 の結果として返す。
 369
 370 .BR nftw ()
 371 が
 372 .B FTW_ACTIONRETVAL
 373 フラグ付きで呼ばれた場合、ツリーの探索を終了させるために
 374 .IR fn ()
 375 が使用できる、非 0 の値は
 376 .B FTW_STOP
 377 だけであり、
 378 この値は
 379 .BR nftw ()
 380 の返り値として返される。
 381 .SH 準拠
 382 POSIX.1-2001, SVr4, SUSv1.
 383 POSIX.1-2008 は
 384 .BR ftw ()
 385 を廃止予定としている。
 386 .SH 注意
 387 POSIX.1-2001 の注記によると、
 388 .I fn
 389 がカレントワーキングディレクトリを保持しなかった場合の
 390 結果は規定されていないとされている。
 391 .PP
 392 .BR nftw ()
 393 関数と、
 394 .BR ftw ()
 395 における
 396 .B FTW_SL
 397 は、SUSv1 で導入された。
 398 .LP
 399 .BR ftw ()
 400 で
 401 .B FTW_SL
 402 を一切使わないシステムや、
 403 存在しないファイルを指しているシンボリックリンクの場合にのみ
 404 .B FTW_SL
 405 を使うシステム、また
 406 .BR ftw ()
 407 が全てのシンボリックリンクに対して
 408 .B FTW_SL
 409 を使うシステムもある。
 410 予測可能な動作をさせるためには、
 411 .BR nftw ()
 412 を使うこと。
 413 .LP
 414 Linux では、 libc4, libc5, glibc 2.0.6 は
 415 「stat できるがディレクトリではないオブジェクト」
 416 (ファイル, シンボリックリンク, fifo 等)
 417 に対してはすべて
 418 .B FTW_F
 419 を使う。
 420
 421 .BR nftw ()
 422 関数は glibc 2.1 以降で利用できる。
 423
 424 .B FTW_ACTIONRETVAL
 425 は glibc 固有である。
 426 .SH 例
 427 以下のプログラムは、一つ目のコマンドライン引き数を名前に持つパス以下の
 428 ディレクトリツリーを探索する。引き数が指定されなかった場合は、
 429 カレントディレクトリ以下を探索する。
 430 各々のファイルについて様々の情報が表示される。
 431 二番目のコマンドライン引き数に文字を指定することで、
 432 .BR nftw ()
 433 を呼び出す際に
 434 .I flags
 435 引き数に渡す値を制御することができる。
 436 .nf
 437
 438 #define _XOPEN_SOURCE 500
 439 #include <ftw.h>
 440 #include <stdio.h>
 441 #include <stdlib.h>
 442 #include <string.h>
 443 #include <stdint.h>
 444
 445 static int
 446 display_info(const char *fpath, const struct stat *sb,
 447              int tflag, struct FTW *ftwbuf)
 448 {
 449     printf("%\-3s %2d %7jd   %\-40s %d %s\\n",
 450         (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
 451         (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
 452         (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
 453         (tflag == FTW_SLN) ? "sln" : "???",
 454         ftwbuf\->level, (intmax_t) sb\->st_size,
 455         fpath, ftwbuf\->base, fpath + ftwbuf\->base);
 456     return 0;           /* To tell nftw() to continue */
 457 }
 458
 459 int
 460 main(int argc, char *argv[])
 461 {
 462     int flags = 0;
 463
 464     if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL)
 465         flags |= FTW_DEPTH;
 466     if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL)
 467         flags |= FTW_PHYS;
 468
 469     if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
 470             == \-1) {
 471         perror("nftw");
 472         exit(EXIT_FAILURE);
 473     }
 474     exit(EXIT_SUCCESS);
 475 }
 476 .fi
 477 .SH 関連項目
 478 .BR stat (2),
 479 .BR fts (3),
 480 .BR readdir (3)