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