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