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 .\"
  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 2014\-12\-31 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 \fBstat\fP(2) の呼び出しがシンボリックリンクでない \fIfpath\fP で失敗した。
  95 これのよくある原因は、呼び出し元が親ディレクトリに対する読み込み許可を持っており、 ファイル名 \fIfpath\fP
  96 を見ることができたが、実行許可は持っておらず、 そのため \fBstat\fP(2) ではそのファイルに到達できなかった、というものである。
  97 .sp
  98 \fIfpath\fP がシンボリックリンクで、かつ \fBstat\fP(2)  が失敗した場合、 \fBFTW_NS\fP と \fBFTW_SL\fP (後述)
  99 のどちらが \fItypeflag\fP に渡されるかは未定義であると、POSIX.1\-2001 には書かれている。
 100 .PP
 101 ツリーの探索を止めたい場合は、 \fIfn\fP()  が 0 以外の値を返せば良い (この値は \fBftw\fP()  自身の戻り値となる)。 それ以外の場合は
 102 \fBftw\fP()  はツリー全体の探索を続け、すべてのツリーを探索し終えたところで 0 を返す。探索中に (\fBmalloc\fP(3)  の失敗などの)
 103 エラーが起こると \-1 を返す。
 104 .PP
 105 \fBftw\fP()  は動的なデータ構造を用いるので、ツリー探索を安全に中断する唯一の方法は 0 以外の値を \fIfn\fP()
 106 の返り値とすることである。割り込みを扱うには、 例えば発生した割り込みをマークしておいて、 0 以外の値を返すようにする
 107 シグナルによりメモリリークを起こさずに探索を終了できるようにするには、 シグナルハンドラで \fIfn\fP()
 108 がチェックするグローバルなフラグをセットするようにすればよい。 プログラムを終了させる場合以外は、 \fBlongjmp\fP(3)  を使用しないこと。
 109 .SS nftw()
 110 関数 \fBnftw\fP()  は \fBftw\fP()  と同じだが、引き数 \fIflags\fP が追加される点と、 \fIfn\fP()  の引き数に
 111 \fIftwbuf\fP が追加される点が異なる。
 112
 113 この \fIflags\fP 引き数は下記のフラグの 0 個以上の論理和を取ったものである:
 114 .TP
 115 \fBFTW_ACTIONRETVAL\fP (glibc 2.3.3 以降)
 116 このフラグは glibc 固有である。 このフラグをセットすると、 \fBnftw\fP()  の \fIfn\fP()  の返り値の扱いが変わる。 \fIfn\fP()
 117 は以下の値のいずれか一つを返す必要がある。
 118 .RS
 119 .TP
 120 \fBFTW_CONTINUE\fP
 121 \fBnftw\fP()  は通常通り処理を続ける。
 122 .TP
 123 \fBFTW_SKIP_SIBLINGS\fP
 124 .\" If \fBFTW_DEPTH\fP
 125 .\" is set, the entry's parent directory is processed next (with
 126 .\" \fIflag\fP set to \fBFTW_DP\fP).
 127 \fIfn\fP()  がこの値を返した場合、処理中のエントリの兄弟 (同じ階層のエントリ)  の処理はスキップされ、親ディレクトリで続きの処理が行われる。
 128 .TP
 129 \fBFTW_SKIP_SUBTREE\fP
 130 \fIfn\fP()  が呼び出されたエントリがディレクトリ (\fItypeflag\fP が \fBFTW_D\fP)  の場合に、この値を返すと \fIfn\fP()
 131 の引き数として渡されたディレクトリ内のエントリの処理が行われなくなる。 \fBnftw\fP()  は処理中のディレクトリの兄弟 (同じ階層のエントリ)
 132 から処理を続ける。
 133 .TP
 134 \fBFTW_STOP\fP
 135 \fBnftw ()\fP は、返り値 \fBFTW_STOP\fP ですぐに復帰する。
 136 .PP
 137 他の返り値は将来新しい動作に対応付けられる可能性がある。 \fIfn\fP()  は上記のリストにある値以外を返さないようにすべきである。
 138
 139 \fI<ftw.h>\fP で \fBFTW_ACTIONRETVAL\fP の定義が有効にするためには、
 140 (「どの」ヘッダファイルをインクルードするよりも前に)  機能検査マクロ \fB_GNU_SOURCE\fP を定義しなければならない。
 141 .RE
 142 .TP
 143 \fBFTW_CHDIR\fP
 144 If set, do a \fBchdir\fP(2)  to each directory before handling its contents.
 145 This is useful if the program needs to perform some action in the directory
 146 in which \fIfpath\fP resides.  (Specifying this flag has no effect on the
 147 pathname that is passed in the \fIfpath\fP argument of \fIfn\fP.)
 148 .TP
 149 \fBFTW_DEPTH\fP
 150 セットされると、帰りがけ順探索 (post\-order traversal) を行う。 つまり、ディレクトリそのものを引き数とした \fIfn\fP()
 151 呼出しは、そのディレクトリに含まれるファイルとサブディレクトリに 対する処理の「後で」行われる
 152 (デフォルトでは、ディレクトリ自身の処理はディレクトリ内のエントリ より「前に」行なわれる)。
 153 .TP
 154 \fBFTW_MOUNT\fP
 155 セットされると、同じファイルシステムの中だけを探索対象とする (つまり、マウントポイントをまたぐことはない)。
 156 .TP
 157 \fBFTW_PHYS\fP
 158 セットされると、シンボリックリンクを辿らない (おそらくこちらが 通常望ましい動作だろう)。セットされていないとシンボリックリンクを
 159 辿るが、同じファイルが二回報告されることはない。
 160 .sp
 161 \fBFTW_PHYS\fP がセットされずに \fBFTW_DEPTH\fP がセットされると、自分自身に対するシンボリックリンクを配下に持つ
 162 ディレクトリに対して \fIfn\fP()  が呼び出されることは決してない。
 163 .LP
 164 ディレクトリツリーのエントリ毎に、 \fBnftw\fP()  は 4つの引き数で \fIfn\fP()  を呼び出す。 \fIfpath\fP と \fIsb\fP は
 165 \fBftw\fP()  と同じである。 \fItypeflag\fP には、 \fBftw\fP()  で取り得る値のいずれか、または以下の値のいずれかが渡される:
 166 .TP
 167 \fBFTW_DP\fP
 168 \fIfpath\fP がディレクトリで、かつ \fIflags\fP で \fBFTW_DEPTH\fP が指定されていた (\fBFTW_DEPTH\fP が
 169 \fIflags\fP に指定されていなかった場合、 ディレクトリに対しては常に \fItypeflag\fP が \fBFTW_D\fP で \fIfn\fP()
 170 が呼び出される)。 \fIfpath\fP 配下のファイルとサブディレクトリは全て処理が終わっている。
 171 .TP
 172 \fBFTW_SL\fP
 173 .\" To obtain the definition of this constant from
 174 .\" .IR <ftw.h> ,
 175 .\" either
 176 .\" .B _BSD_SOURCE
 177 .\" must be defined, or
 178 .\" .BR _XOPEN_SOURCE
 179 .\" must be defined with a value of 500 or more.
 180 \fIfpath\fP がシンボリックリンクで、かつ \fBFTW_PHYS\fP が \fIflags\fP に セットされていた。
 181 .TP
 182 \fBFTW_SLN\fP
 183 \fIfpath\fP がシンボリックリンクで、存在しないファイルを指している (これがセットされるのは \fBFTW_PHYS\fP
 184 がセットされていない場合だけである)。
 185 .LP
 186 \fBnftw\fP()  が \fIfn\fP()  を呼び出す際に渡す 4つめの引き数は \fIFTW\fP 型の構造体である。
 187 .in +4n
 188 .nf
 189
 190 struct FTW {
 191     int base;
 192     int level;
 193 };
 194
 195 .fi
 196 .in
 197 \fIbase\fP は、ファイル名 (basename 要素) の、 \fIfpath\fP で渡されるパス名の中でのオフセットである。 \fIlevel\fP
 198 はディレクトリツリーでの \fIfpath\fP の深さを示す。深さはディレクトリツリーのトップ (root) からの 相対値である (\fIdirpath\fP
 199 は深さ 0 である)。
 200 .SH 返り値
 201 これらの関数は、成功すると 0 を、エラーが発生すると \-1 を返す。
 202
 203 \fIfn\fP()  が 0 以外を返した場合、ディレクトリツリーの探索を終了し、 \fIfn\fP()  が返した値を \fBftw\fP()  や
 204 \fBnftw\fP()  の結果として返す。
 205
 206 \fBnftw\fP()  が \fBFTW_ACTIONRETVAL\fP フラグ付きで呼ばれた場合、ツリーの探索を終了させるために \fIfn\fP()
 207 が使用できる、非 0 の値は \fBFTW_STOP\fP だけであり、 この値は \fBnftw\fP()  の返り値として返される。
 208 .SH バージョン
 209 \fBnftw\fP() は バージョン 2.1 以降の glibc で利用できる。
 210 .SH 準拠
 211 POSIX.1\-2001, SVr4, SUSv1.  POSIX.1\-2008 は \fBftw\fP()  を廃止予定としている。
 212 .SH 注意
 213 POSIX.1\-2001 の注記によると、 \fIfn\fP がカレントワーキングディレクトリを保持しなかった場合の 結果は規定されていないとされている。
 214 .PP
 215 \fBnftw\fP()  関数と、 \fBftw\fP()  における \fBFTW_SL\fP は、SUSv1 で導入された。
 216 .LP
 217 \fBftw\fP()  で \fBFTW_SL\fP を一切使わないシステムや、 存在しないファイルを指しているシンボリックリンクの場合にのみ \fBFTW_SL\fP
 218 を使うシステム、また \fBftw\fP()  が全てのシンボリックリンクに対して \fBFTW_SL\fP を使うシステムもある。
 219 予測可能な動作をさせるためには、 \fBnftw\fP()  を使うこと。
 220 .LP
 221 「stat できるがディレクトリではないオブジェクト」 (ファイル, シンボリックリンク, fifo 等)  に対しては、すべて \fBFTW_F\fP
 222 が返される。
 223
 224 \fBFTW_ACTIONRETVAL\fP は glibc 固有である。
 225 .SH 例
 226 以下のプログラムは、一つ目のコマンドライン引き数を名前に持つパス以下の ディレクトリツリーを探索する。引き数が指定されなかった場合は、
 227 カレントディレクトリ以下を探索する。 各々のファイルについて様々の情報が表示される。 二番目のコマンドライン引き数に文字を指定することで、
 228 \fBnftw\fP()  を呼び出す際に \fIflags\fP 引き数に渡す値を制御することができる。
 229 .SS プログラムのソース
 230 .nf
 231 #define _XOPEN_SOURCE 500
 232 #include <ftw.h>
 233 #include <stdio.h>
 234 #include <stdlib.h>
 235 #include <string.h>
 236 #include <stdint.h>
 237
 238 static int
 239 display_info(const char *fpath, const struct stat *sb,
 240              int tflag, struct FTW *ftwbuf)
 241 {
 242     printf("%\-3s %2d %7jd   %\-40s %d %s\en",
 243         (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
 244         (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
 245         (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
 246         (tflag == FTW_SLN) ? "sln" : "???",
 247         ftwbuf\->level, (intmax_t) sb\->st_size,
 248         fpath, ftwbuf\->base, fpath + ftwbuf\->base);
 249     return 0;           /* To tell nftw() to continue */
 250 }
 251
 252 int
 253 main(int argc, char *argv[])
 254 {
 255     int flags = 0;
 256
 257     if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL)
 258         flags |= FTW_DEPTH;
 259     if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL)
 260         flags |= FTW_PHYS;
 261
 262     if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
 263             == \-1) {
 264         perror("nftw");
 265         exit(EXIT_FAILURE);
 266     }
 267     exit(EXIT_SUCCESS);
 268 }
 269 .fi
 270 .SH 関連項目
 271 \fBstat\fP(2), \fBfts\fP(3), \fBreaddir\fP(3)
 272 .SH この文書について
 273 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.76 の一部
 274 である。プロジェクトの説明とバグ報告に関する情報は
 275 http://www.kernel.org/doc/man\-pages/ に書かれている。