draft/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 .\"O .SH NAME
  45 .SH 名前
  46 .\"O ftw, nftw \- file tree walk
  47 ftw, nftw \- ファイルツリーを歩きまわる
  48 .\"O .SH SYNOPSIS
  49 .SH 書式
  50 .nf
  51 .B #include <ftw.h>
  52 .sp
  53 .BI "int ftw(const char *" dirpath ,
  54 .BI "        int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
  55 .BI "                   int " typeflag ),
  56 .BI "        int " nopenfd );
  57 .sp
  58 .\"O .BR "#define _XOPEN_SOURCE 500" "   /* See feature_test_macros(7) */"
  59 .BR "#define _XOPEN_SOURCE 500" "   /* feature_test_macros(7) 参照 */"
  60 .B #define _XOPEN_SOURCE 500
  61 .B #include <ftw.h>
  62 .sp
  63 .BI "int nftw(const char *" dirpath ,
  64 .BI "        int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
  65 .BI "                   int " typeflag ", struct FTW *" ftwbuf ),
  66 .BI "        int " nopenfd ", int " flags );
  67 .fi
  68 .\"O .SH DESCRIPTION
  69 .SH 説明
  70 .\"O .BR ftw ()
  71 .\"O walks through the directory tree that is
  72 .\"O located under the directory \fIdirpath\fP,
  73 .\"O and calls \fIfn\fP() once for each entry in the tree.
  74 .\"O By default, directories are handled before the files and
  75 .\"O subdirectories they contain (preorder traversal).
  76 .BR ftw ()
  77 は、
  78 .I dirpath
  79 で指定されたディレクトリ以下のディレクトリツリー全体を歩きまわり、
  80 ツリー中でエントリが見付かるごとに、
  81 .IR fn ()
  82 を呼び出す。
  83 デフォルトでは、ディレクトリそのものが、そのディレクトリにあるファイルや
  84 サブディレクトリよりも先に処理される (行きがけ順探索; preorder traversal)。
  85
  86 .\"O To avoid using up all of the calling process's file descriptors,
  87 .\"O \fInopenfd\fP specifies the maximum number of directories that
  88 .\"O .BR ftw ()
  89 .\"O will hold open simultaneously.
  90 .\"O When
  91 .\"O the search depth exceeds this,
  92 .\"O .BR ftw ()
  93 .\"O will become slower because
  94 .\"O directories have to be closed and reopened.
  95 .\"O .BR ftw ()
  96 .\"O uses at most
  97 .\"O one file descriptor for each level in the directory tree.
  98 呼び出し元プロセスが利用可能なファイルディスクリプタを使い切って
  99 しまわないようにするため、
 100 .BR ftw ()
 101 が同時にオープンするディレクトリの最大数を
 102 .I nopenfd
 103 で指定することができる。
 104 探索の深さがこの値を越えると、
 105 一つのディレクトリを閉じてから他のディレクトリをオープンし直すこと
 106 になるので、
 107 .BR ftw ()
 108 の動作は遅くなる。
 109 .BR ftw ()
 110 は、ディレクトリツリーの階層 1 レベルにつき、
 111 最大でも一つのファイルディスクリプタしか使用しない。
 112
 113 .\"O For each entry found in the tree,
 114 .\"O .BR ftw ()
 115 .\"O calls
 116 .\"O \fIfn\fP() with three arguments:
 117 .\"O .IR fpath ,
 118 .\"O .IR sb ,
 119 .\"O and
 120 .\"O .IR typeflag .
 121 ディレクトリツリーで見つかったエントリ毎に、
 122 .BR ftw ()
 123 は
 124 .IR fpath ,
 125 .IR sb ,
 126 .I typeflag
 127 の 3つを引き数として
 128 .IR fn ()
 129 を呼び出す。
 130 .\"O .I fpath
 131 .\"O is the pathname of the entry,
 132 .\"O and is expressed either as a pathname relative to the calling process's
 133 .\"O current working directory at the time of the call to
 134 .\"O .BR ftw (),
 135 .\"O if
 136 .\"O .IR dirpath
 137 .\"O was expressed as a relative pathname,
 138 .\"O or as an absolute pathname, if
 139 .\"O .I dirpath
 140 .\"O was expressed as an absolute pathname.
 141 .I fpath
 142 はエントリのパス名である。
 143 .I dirpath
 144 が相対パス名で指定された場合には、
 145 .I fpath
 146 は
 147 .BR ftw ()
 148 が呼び出された時点の呼び出し元プロセスのカレントワーキングディレクトリ
 149 からの相対パス名となる。
 150 .I dirpath
 151 が絶対パス名で指定された場合には、
 152 .I fpath
 153 は絶対パス名となる。
 154 .\"O .I sb
 155 .\"O is a pointer to the
 156 .\"O .I stat
 157 .\"O structure returned by a call to
 158 .\"O .BR stat (2)
 159 .\"O for
 160 .\"O .IR fpath .
 161 .I sb
 162 は
 163 .I fpath
 164 に対する
 165 .BR stat (2)
 166 の呼び出しで返される
 167 .I stat
 168 構造体へのポインタである。
 169 .\"O .I typeflag
 170 .\"O is an integer that has one of the following values:
 171 .I typeflag
 172 は整数で、以下の値のいずれか一つである:
 173 .TP
 174 .B FTW_F
 175 .\"O .I fpath
 176 .\"O is a regular file.
 177 .I fpath
 178 が通常のファイルである
 179 .TP
 180 .B FTW_D
 181 .\"O .I fpath
 182 .\"O is a directory.
 183 .I fpath
 184 がディレクトリである
 185 .TP
 186 .B FTW_DNR
 187 .\"O .I fpath
 188 .\"O is a directory which can't be read.
 189 .I fpath
 190 が読み込みできないディレクトリである
 191 .TP
 192 .B FTW_NS
 193 .\"O The
 194 .\"O .BR stat (2)
 195 .\"O call failed on
 196 .\"O .IR fpath ,
 197 .\"O which is not a symbolic link.
 198 シンボリックリンクではない
 199 .I fpath
 200 に対する
 201 .BR stat (2)
 202 呼び出しが失敗した。
 203 .sp
 204 .\"O If
 205 .\"O .I fpath
 206 .\"O is a symbolic link and
 207 .\"O .BR stat (2)
 208 .\"O failed, POSIX.1-2001 states
 209 .\"O that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP (see below)
 210 .\"O is passed in
 211 .\"O .IR typeflag .
 212 .I fpath
 213 がシンボリックリンクで、かつ
 214 .BR stat (2)
 215 が失敗した場合、
 216 .B FTW_NS
 217 と
 218 .B FTW_SL
 219 (後述) のどちらが
 220 .I typeflag
 221 に渡されるかは未定義であると、POSIX.1-2001 には書かれている。
 222 .PP
 223 .\"O To stop the tree walk, \fIfn\fP() returns a nonzero value; this
 224 .\"O value will become the return value of
 225 .\"O .BR ftw ().
 226 .\"O As long as \fIfn\fP() returns 0,
 227 .\"O .BR ftw ()
 228 .\"O will continue either until it has traversed the entire tree,
 229 .\"O in which case it will return zero,
 230 .\"O or until it encounters an error (such as a
 231 .\"O .BR malloc (3)
 232 .\"O failure), in which case it will return \-1.
 233 ツリーの探索を止めたい場合は、
 234 .IR fn ()
 235 が 0 以外の値を返せば良い
 236 (この値は
 237 .BR ftw ()
 238 自身の戻り値となる)。
 239 それ以外の場合は
 240 .BR ftw ()
 241 はツリー全体の探索を続け、すべてのツリーを探索し終えたところで
 242 0 を返す。探索中に
 243 .RB ( malloc (3)
 244 の失敗などの) エラーが起こると \-1 を返す。
 245 .PP
 246 .\"O Because
 247 .\"O .BR ftw ()
 248 .\"O uses dynamic data structures, the only safe way to
 249 .\"O exit out of a tree walk is to return a nonzero value from \fIfn\fP().
 250 .\"O To allow a signal to terminate the walk without causing a memory leak,
 251 .\"O have the handler set a global flag that is checked by \fIfn\fP().
 252 .\"O \fIDon't\fP use
 253 .\"O .BR longjmp (3)
 254 .\"O unless the program is going to terminate.
 255 .BR ftw ()
 256 は動的なデータ構造を用いるので、ツリー探索を安全に中断する唯一の方法は
 257 0 以外の値を
 258 .IR fn ()
 259 の返り値とすることである。割り込みを扱うには、
 260 例えば発生した割り込みをマークしておいて、 0 以外の値を返すようにする
 261 シグナルによりメモリリークを起こさずに探索を終了できるようにするには、
 262 シグナルハンドラで
 263 .IR fn ()
 264 がチェックするグローバルなフラグをセットするようにすればよい。
 265 プログラムを終了させる場合以外は、
 266 .BR longjmp (3)
 267 を使用しないこと。
 268 .SS nftw()
 269 .\"O The function \fBnftw\fP() is the same as
 270 .\"O .BR ftw (),
 271 .\"O except that it has one additional argument, \fIflags\fP,
 272 .\"O and calls \fIfn\fP() with one more argument, \fIftwbuf\fP.
 273 関数
 274 .BR nftw ()
 275 は
 276 .BR ftw ()
 277 と同じだが、引き数
 278 .I flags
 279 が追加される点と、
 280 .IR fn ()
 281 の引き数に
 282 .I ftwbuf
 283 が追加される点が異なる。
 284
 285 .\"O This \fIflags\fP argument is formed by ORing zero or more of the
 286 .\"O following flags:
 287 この
 288 .I flags
 289 引き数は下記のフラグの 0 個以上の論理和を取ったものである:
 290 .TP
 291 .\"O .BR FTW_ACTIONRETVAL " (since glibc 2.3.3)"
 292 .BR FTW_ACTIONRETVAL " (glibc 2.3.3 以降)"
 293 .\"O If this glibc-specific flag is set, then
 294 .\"O .BR nftw ()
 295 .\"O handles the return value from
 296 .\"O .IR fn ()
 297 .\"O differently.
 298 .\"O .IR fn ()
 299 .\"O should return one of the following values:
 300 このフラグは glibc 固有である。
 301 このフラグをセットすると、
 302 .BR nftw ()
 303 の
 304 .IR fn ()
 305 の返り値の扱いが変わる。
 306 .IR fn ()
 307 は以下の値のいずれか一つを返す必要がある。
 308 .RS
 309 .TP
 310 .B FTW_CONTINUE
 311 .\"O Instructs
 312 .\"O .BR nftw ()
 313 .\"O to continue normally.
 314 .BR nftw ()
 315 は通常通り処理を続ける。
 316 .TP
 317 .B FTW_SKIP_SIBLINGS
 318 .\"O If \fIfn\fP() returns this value, then
 319 .\"O siblings of the current entry will be skipped,
 320 .\"O and processing continues in the parent.
 321 .IR fn ()
 322 がこの値を返した場合、処理中のエントリの兄弟 (同じ階層のエントリ)
 323 の処理はスキップされ、親ディレクトリで続きの処理が行われる。
 324 .\" If \fBFTW_DEPTH\fP
 325 .\" is set, the entry's parent directory is processed next (with
 326 .\" \fIflag\fP set to \fBFTW_DP\fP).
 327 .TP
 328 .B FTW_SKIP_SUBTREE
 329 .\"O If \fIfn\fP() is called with an entry that is a directory
 330 .\"O (\fItypeflag\fP is \fBFTW_D\fP), this return
 331 .\"O value will prevent objects within that directory from being passed as
 332 .\"O arguments to \fIfn\fP().
 333 .\"O .BR nftw ()
 334 .\"O continues processing with the next sibling of the directory.
 335 .IR fn ()
 336 が呼び出されたエントリがディレクトリ
 337 .RI ( typeflag
 338 が
 339 .BR FTW_D )
 340 の場合に、この値を返すと
 341 .IR fn ()
 342 の引き数として渡されたディレクトリ内のエントリの処理が行われなくなる。
 343 .BR nftw ()
 344 は処理中のディレクトリの兄弟 (同じ階層のエントリ) から処理を続ける。
 345 .TP
 346 .B FTW_STOP
 347 .\"O Causes
 348 .\"O .BR nftw ()
 349 .\"O to return immediately with the return value
 350 .\"O \fBFTW_STOP\fP.
 351 .B nftw ()
 352 は、返り値
 353 .B FTW_STOP
 354 ですぐに復帰する。
 355 .PP
 356 .\"O Other return values could be associated with new actions in the future;
 357 .\"O \fIfn\fP() should not return values other than those listed above.
 358 他の返り値は将来新しい動作に対応付けられる可能性がある。
 359 .IR fn ()
 360 は上記のリストにある値以外を返さないようにすべきである。
 361
 362 .\"O The feature test macro
 363 .\"O .B _GNU_SOURCE
 364 .\"O must be defined
 365 .\"O (before including
 366 .\"O .I any
 367 .\"O header files)
 368 .\"O in order to
 369 .\"O obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP.
 370 .I <ftw.h>
 371 で
 372 .B FTW_ACTIONRETVAL
 373 の定義が有効にするためには、
 374 (「どの」ヘッダファイルをインクルードするよりも前に)
 375 機能検査マクロ
 376 .B _GNU_SOURCE
 377 を定義しなければならない。
 378 .RE
 379 .TP
 380 .B FTW_CHDIR
 381 .\"O If set, do a
 382 .\"O .BR chdir (2)
 383 .\"O to each directory before handling its contents.
 384 .\"O This is useful if the program needs to perform some action
 385 .\"O in the directory in which \fIfpath\fP resides.
 386 セットされると、ディレクトリの内容を処理する前に
 387 そのディレクトリに
 388 .BR chdir (2)
 389 する。このフラグは、
 390 .I fpath
 391 が属すディレクトリで何らかの動作を実行する必要がある場合に
 392 便利である。
 393 .TP
 394 .B FTW_DEPTH
 395 .\"O If set, do a post-order traversal, that is, call \fIfn\fP() for
 396 .\"O the directory itself \fIafter\fP handling the contents of the directory
 397 .\"O and its subdirectories.
 398 .\"O (By default, each directory is handled \fIbefore\fP its contents.)
 399 セットされると、帰りがけ順探索 (post-order traversal) を行う。
 400 つまり、ディレクトリそのものを引き数とした
 401 .IR fn ()
 402 呼出しは、そのディレクトリに含まれるファイルとサブディレクトリに
 403 対する処理の「後で」行われる
 404 (デフォルトでは、ディレクトリ自身の処理はディレクトリ内のエントリ
 405 より「前に」行なわれる)。
 406 .TP
 407 .B FTW_MOUNT
 408 .\"O If set, stay within the same file system
 409 .\"O (i.e., do not cross mount points).
 410 セットされると、同じファイルシステムの中だけを探索対象とする
 411 (つまり、マウントポイントをまたぐことはない)。
 412 .TP
 413 .B FTW_PHYS
 414 .\"O If set, do not follow symbolic links.
 415 .\"O (This is what you want.)
 416 .\"O If not set, symbolic links are followed, but no file is reported twice.
 417 セットされると、シンボリックリンクを辿らない (おそらくこちらが
 418 通常望ましい動作だろう)。セットされていないとシンボリックリンクを
 419 辿るが、同じファイルが二回報告されることはない。
 420 .sp
 421 .\"O If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set,
 422 .\"O then the function
 423 .\"O .IR fn ()
 424 .\"O is never called for a directory that would be a descendant of itself.
 425 .B FTW_PHYS
 426 がセットされずに
 427 .B FTW_DEPTH
 428 がセットされると、自分自身に対するシンボリックリンクを配下に持つ
 429 ディレクトリに対して
 430 .IR fn ()
 431 が呼び出されることは決してない。
 432 .LP
 433 .\"O For each entry in the directory tree,
 434 .\"O .BR nftw ()
 435 .\"O calls
 436 .\"O .IR fn ()
 437 .\"O with four arguments.
 438 .\"O .I fpath
 439 .\"O and
 440 .\"O .I sb
 441 .\"O are as for
 442 .\"O .BR ftw ().
 443 .\"O .I typeflag
 444 .\"O may receive any of the same values as with
 445 .\"O .BR ftw (),
 446 .\"O or any of the following values:
 447 ディレクトリツリーのエントリ毎に、
 448 .BR nftw ()
 449 は 4つの引き数で
 450 .IR fn ()
 451 を呼び出す。
 452 .I fpath
 453 と
 454 .I sb
 455 は
 456 .BR ftw ()
 457 と同じである。
 458 .I typeflag
 459 には、
 460 .BR ftw ()
 461 で取り得る値のいずれか、または以下の値のいずれかが渡される:
 462 .TP
 463 .B FTW_DP
 464 .\"O .I fpath
 465 .\"O is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP.
 466 .\"O All of the files
 467 .\"O and subdirectories within \fIfpath\fP have been processed.
 468 .I fpath
 469 がディレクトリで、かつ
 470 .I flags
 471 で
 472 .B FTW_DEPTH
 473 が指定されていた。
 474 .I fpath
 475 配下のファイルとサブディレクトリは全て処理が終わっている。
 476 .TP
 477 .B FTW_SL
 478 .\"O .I fpath
 479 .\"O is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP.
 480 .I fpath
 481 がシンボリックリンクで、かつ \fBFTW_PHYS\fP が \fIflags\fP に
 482 セットされていた。
 483 .\" To obtain the definition of this constant from
 484 .\" .IR <ftw.h> ,
 485 .\" either
 486 .\" .B _BSD_SOURCE
 487 .\" must be defined, or
 488 .\" .BR _XOPEN_SOURCE
 489 .\" must be defined with a value of 500 or more.
 490 .TP
 491 .B FTW_SLN
 492 .\"O .I fpath
 493 .\"O is a symbolic link pointing to a nonexistent file.
 494 .\"O (This occurs only if \fBFTW_PHYS\fP is not set.)
 495 .I fpath
 496 がシンボリックリンクで、存在しないファイルを指している
 497 (これがセットされるのは
 498 .B FTW_PHYS
 499 がセットされていない場合だけである)。
 500 .LP
 501 .\"O The fourth argument that
 502 .\"O .BR nftw ()
 503 .\"O supplies when calling
 504 .\"O \fIfn\fP()
 505 .\"O is a structure of type \fIFTW\fP:
 506 .BR nftw ()
 507 が
 508 .IR fn ()
 509 を呼び出す際に渡す 4つめの引き数は
 510 .I FTW
 511 型の構造体である。
 512 .in +4n
 513 .nf
 514
 515 struct FTW {
 516     int base;
 517     int level;
 518 };
 519
 520 .fi
 521 .in
 522 .\"O .I base
 523 .\"O is the offset of the filename (i.e., basename component)
 524 .\"O in the pathname given in
 525 .\"O .IR fpath .
 526 .\"O .I level
 527 .\"O is the depth of
 528 .\"O .I fpath
 529 .\"O in the directory tree, relative to the root of the tree
 530 .\"O .RI ( dirpath ,
 531 .\"O which has depth 0).
 532 .I base
 533 は、ファイル名 (basename 要素) の、
 534 .I fpath
 535 で渡されるパス名の中でのオフセットである。
 536 .I level
 537 はディレクトリツリーでの
 538 .I fpath
 539 の深さを示す。深さはディレクトリツリーのトップ (root) からの
 540 相対値である
 541 .RI ( dirpath
 542 は深さ 0 である)。
 543 .\"O .SH "RETURN VALUE"
 544 .SH 返り値
 545 .\"O These functions return 0 on success, and \-1 if an error occurs.
 546 これらの関数は、成功すると 0 を、エラーが発生すると \-1 を返す。
 547
 548 .\"O If \fIfn\fP() returns nonzero,
 549 .\"O then the tree walk is terminated and the value returned by \fIfn\fP()
 550 .\"O is returned as the result of \fBftw\fP() or
 551 .\"O .BR nftw ().
 552 .IR fn ()
 553 が 0 以外を返した場合、ディレクトリツリーの探索を終了し、
 554 .IR fn ()
 555 が返した値を
 556 .BR ftw ()
 557 や
 558 .BR nftw ()
 559 の結果として返す。
 560
 561 .\"O If
 562 .\"O .BR nftw ()
 563 .\"O is called with the \fBFTW_ACTIONRETVAL\fP flag,
 564 .\"O then the only nonzero value that should be used by \fIfn\fP()
 565 .\"O to terminate the tree walk is \fBFTW_STOP\fP,
 566 .\"O and that value is returned as the result of
 567 .\"O .BR nftw ().
 568 .BR nftw ()
 569 が
 570 .B FTW_ACTIONRETVAL
 571 フラグ付きで呼ばれた場合、ツリーの探索を終了させるために
 572 .IR fn ()
 573 が使用できる、非 0 の値は
 574 .B FTW_STOP
 575 だけであり、
 576 この値は
 577 .BR nftw ()
 578 の返り値として返される。
 579 .\"O .SH "CONFORMING TO"
 580 .SH 準拠
 581 POSIX.1-2001, SVr4, SUSv1.
 582 .\"O POSIX.1-2008 marks
 583 .\"O .BR ftw ()
 584 .\"O as obsolete.
 585 POSIX.1-2008 は
 586 .BR ftw ()
 587 を廃止予定としている。
 588 .\"O .SH NOTES
 589 .SH 注意
 590 .\"O POSIX.1-2001 note that the results are unspecified if
 591 .\"O .I fn
 592 .\"O does not preserve the current working directory.
 593 POSIX.1-2001 の注記によると、
 594 .I fn
 595 がカレントワーキングディレクトリを保持しなかった場合の
 596 結果は規定されていないとされている。
 597 .PP
 598 .\"O The function
 599 .\"O .BR nftw ()
 600 .\"O and the use of \fBFTW_SL\fP with
 601 .\"O .BR ftw ()
 602 .\"O were introduced in SUSv1.
 603 .BR nftw ()
 604 関数と、
 605 .BR ftw ()
 606 における
 607 .B FTW_SL
 608 は、SUSv1 で導入された。
 609 .LP
 610 .\"O On some systems
 611 .\"O .BR ftw ()
 612 .\"O will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only
 613 .\"O for symbolic links that do not point to an existing file,
 614 .\"O and again on other systems
 615 .\"O .BR ftw ()
 616 .\"O will use \fBFTW_SL\fP for each symbolic link.
 617 .\"O For predictable control, use
 618 .\"O .BR nftw ().
 619 .BR ftw ()
 620 で
 621 .B FTW_SL
 622 を一切使わないシステムや、
 623 存在しないファイルを指しているシンボリックリンクの場合にのみ
 624 .B FTW_SL
 625 を使うシステム、また
 626 .BR ftw ()
 627 が全てのシンボリックリンクに対して
 628 .B FTW_SL
 629 を使うシステムもある。
 630 予測可能な動作をさせるためには、
 631 .BR nftw ()
 632 を使うこと。
 633 .LP
 634 .\"O Under Linux, libc4 and libc5 and glibc 2.0.6 will
 635 .\"O use \fBFTW_F\fP for all objects (files, symbolic links, FIFOs, etc.)
 636 .\"O that can be stat'ed but are not a directory.
 637 Linux では、 libc4, libc5, glibc 2.0.6 は
 638 「stat できるがディレクトリではないオブジェクト」
 639 (ファイル, シンボリックリンク, fifo 等)
 640 に対してはすべて
 641 .B FTW_F
 642 を使う。
 643
 644 .\"O The function
 645 .\"O .BR nftw ()
 646 .\"O is available since glibc 2.1.
 647 .BR nftw ()
 648 関数は glibc 2.1 以降で利用できる。
 649
 650 .\"O \fBFTW_ACTIONRETVAL\fP is glibc-specific.
 651 .B FTW_ACTIONRETVAL
 652 は glibc 固有である。
 653 .\"O .SH EXAMPLE
 654 .SH 例
 655 .\"O The following program traverses the directory tree under the path named
 656 .\"O in its first command-line argument, or under the current directory
 657 .\"O if no argument is supplied.
 658 .\"O It displays various information about each file.
 659 .\"O The second command-line argument can be used to specify characters that
 660 .\"O control the value assigned to the \fIflags\fP
 661 .\"O argument when calling
 662 .\"O .BR nftw ().
 663 以下のプログラムは、一つ目のコマンドライン引き数を名前に持つパス以下の
 664 ディレクトリツリーを探索する。引き数が指定されなかった場合は、
 665 カレントディレクトリ以下を探索する。
 666 各々のファイルについて様々の情報が表示される。
 667 二番目のコマンドライン引き数に文字を指定することで、
 668 .BR nftw ()
 669 を呼び出す際に
 670 .I flags
 671 引き数に渡す値を制御することができる。
 672 .nf
 673
 674 #define _XOPEN_SOURCE 500
 675 #include <ftw.h>
 676 #include <stdio.h>
 677 #include <stdlib.h>
 678 #include <string.h>
 679 #include <stdint.h>
 680
 681 static int
 682 display_info(const char *fpath, const struct stat *sb,
 683              int tflag, struct FTW *ftwbuf)
 684 {
 685     printf("%\-3s %2d %7jd   %\-40s %d %s\\n",
 686         (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
 687         (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
 688         (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
 689         (tflag == FTW_SLN) ? "sln" : "???",
 690         ftwbuf\->level, (intmax_t) sb\->st_size,
 691         fpath, ftwbuf\->base, fpath + ftwbuf\->base);
 692     return 0;           /* To tell nftw() to continue */
 693 }
 694
 695 int
 696 main(int argc, char *argv[])
 697 {
 698     int flags = 0;
 699
 700     if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL)
 701         flags |= FTW_DEPTH;
 702     if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL)
 703         flags |= FTW_PHYS;
 704
 705     if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
 706             == \-1) {
 707         perror("nftw");
 708         exit(EXIT_FAILURE);
 709     }
 710     exit(EXIT_SUCCESS);
 711 }
 712 .fi
 713 .\"O .SH "SEE ALSO"
 714 .SH 関連項目
 715 .BR stat (2),
 716 .BR fts (3),
 717 .BR readdir (3)