+++ /dev/null
-.\" Copyright (c) 1993 Michael Haardt (michael@moria.de)
-.\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
-.\" and copyright (c) 2006 Justin Pryzby <justinpryzby@users.sf.net>
-.\" and copyright (c) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
-.\"
-.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
-.\" This is free documentation; you can redistribute it and/or
-.\" modify it under the terms of the GNU General Public License as
-.\" published by the Free Software Foundation; either version 2 of
-.\" the License, or (at your option) any later version.
-.\"
-.\" The GNU General Public License's references to "object code"
-.\" and "executables" are to be interpreted as the output of any
-.\" document formatting or typesetting system, including
-.\" intermediate and printed output.
-.\"
-.\" This manual is distributed in the hope that it will be useful,
-.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-.\" GNU General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public
-.\" License along with this manual; if not, see
-.\" <http://www.gnu.org/licenses/>.
-.\" %%%LICENSE_END
-.\"
-.\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu)
-.\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net>
-.\" document FTW_ACTIONRETVAL; include .SH "RETURN VALUE";
-.\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> and
-.\" Michael Kerrisk <mtk.manpages@gmail.com>
-.\" reorganized and rewrote much of the page
-.\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com>
-.\" Added an example program.
-.\"*******************************************************************
-.\"
-.\" This file was generated with po4a. Translate the source file.
-.\"
-.\"*******************************************************************
-.\"
-.\" Japanese Version Copyright (c) 1998 NAKANO Takeo all rights reserved.
-.\" Translated 1998-04-28, NAKANO Takeo <nakano@apm.seikei.ac.jp>
-.\" Updated & Modified 1999-09-14, NAKANO Takeo <nakano@apm.seikei.ac.jp>
-.\" Updated & Modified 2005-11-04, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
-.\" Updated 2006-07-26, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.36
-.\"
-.TH FTW 3 2014\-12\-31 Linux "Linux Programmer's Manual"
-.SH 名前
-ftw, nftw \- ファイルツリーを歩きまわる
-.SH 書式
-.nf
-\fB#include <ftw.h>\fP
-.sp
-\fBint ftw(const char *\fP\fIdirpath\fP\fB,\fP
-\fB int (*\fP\fIfn\fP\fB) (const char *\fP\fIfpath\fP\fB, const struct stat *\fP\fIsb\fP\fB,\fP
-\fB int \fP\fItypeflag\fP\fB),\fP
-\fB int \fP\fInopenfd\fP\fB);\fP
-.sp
-\fB#define _XOPEN_SOURCE 500\fP /* feature_test_macros(7) 参照 */
-\fB#define _XOPEN_SOURCE 500\fP
-\fB#include <ftw.h>\fP
-.sp
-\fBint nftw(const char *\fP\fIdirpath\fP\fB,\fP
-\fB int (*\fP\fIfn\fP\fB) (const char *\fP\fIfpath\fP\fB, const struct stat *\fP\fIsb\fP\fB,\fP
-\fB int \fP\fItypeflag\fP\fB, struct FTW *\fP\fIftwbuf\fP\fB),\fP
-\fB int \fP\fInopenfd\fP\fB, int \fP\fIflags\fP\fB);\fP
-.fi
-.SH 説明
-\fBftw\fP() は、 \fIdirpath\fP で指定されたディレクトリ以下のディレクトリツリー全体を歩きまわり、
-ツリー中でエントリーが見付かるごとに、 \fIfn\fP() を呼び出す。 デフォルトでは、ディレクトリそのものが、そのディレクトリにあるファイルや
-サブディレクトリよりも先に処理される (行きがけ順探索; preorder traversal)。
-
-呼び出し元プロセスが利用可能なファイルディスクリプターを使い切って しまわないようにするため、 \fBftw\fP()
-が同時にオープンするディレクトリの最大数を \fInopenfd\fP で指定することができる。 探索の深さがこの値を越えると、
-一つのディレクトリを閉じてから他のディレクトリをオープンし直すこと になるので、 \fBftw\fP() の動作は遅くなる。 \fBftw\fP()
-は、ディレクトリツリーの階層 1 レベルにつき、 最大でも一つのファイルディスクリプターしか使用しない。
-
-ディレクトリツリーで見つかったエントリー毎に、 \fBftw\fP() は \fIfpath\fP, \fIsb\fP, \fItypeflag\fP の 3つを引き数として
-\fIfn\fP() を呼び出す。 \fIfpath\fP はエントリーのパス名である。 \fIdirpath\fP が相対パス名で指定された場合には、
-\fIfpath\fP は \fBftw\fP() が呼び出された時点の呼び出し元プロセスのカレントワーキングディレクトリ からの相対パス名となる。
-\fIdirpath\fP が絶対パス名で指定された場合には、 \fIfpath\fP は絶対パス名となる。 \fIsb\fP は \fIfpath\fP に対する
-\fBstat\fP(2) の呼び出しで返される \fIstat\fP 構造体へのポインターである。 \fItypeflag\fP
-は整数で、以下の値のいずれか一つである:
-.TP
-\fBFTW_F\fP
-\fIfpath\fP が通常のファイルである
-.TP
-\fBFTW_D\fP
-\fIfpath\fP がディレクトリである
-.TP
-\fBFTW_DNR\fP
-\fIfpath\fP が読み込みできないディレクトリである
-.TP
-\fBFTW_NS\fP
-\fBstat\fP(2) の呼び出しがシンボリックリンクでない \fIfpath\fP で失敗した。
-これのよくある原因は、呼び出し元が親ディレクトリに対する読み込み許可を持っており、 ファイル名 \fIfpath\fP
-を見ることができたが、実行許可は持っておらず、 そのため \fBstat\fP(2) ではそのファイルに到達できなかった、というものである。
-.sp
-\fIfpath\fP がシンボリックリンクで、かつ \fBstat\fP(2) が失敗した場合、 \fBFTW_NS\fP と \fBFTW_SL\fP (後述)
-のどちらが \fItypeflag\fP に渡されるかは未定義であると、POSIX.1\-2001 には書かれている。
-.PP
-ツリーの探索を止めたい場合は、 \fIfn\fP() が 0 以外の値を返せば良い (この値は \fBftw\fP() 自身の戻り値となる)。 それ以外の場合は
-\fBftw\fP() はツリー全体の探索を続け、すべてのツリーを探索し終えたところで 0 を返す。探索中に (\fBmalloc\fP(3) の失敗などの)
-エラーが起こると \-1 を返す。
-.PP
-\fBftw\fP() は動的なデータ構造を用いるので、ツリー探索を安全に中断する唯一の方法は 0 以外の値を \fIfn\fP()
-の返り値とすることである。割り込みを扱うには、 例えば発生した割り込みをマークしておいて、 0 以外の値を返すようにする
-シグナルによりメモリーリークを起こさずに探索を終了できるようにするには、 シグナルハンドラーで \fIfn\fP()
-がチェックするグローバルなフラグをセットするようにすればよい。 プログラムを終了させる場合以外は、 \fBlongjmp\fP(3) を使用しないこと。
-.SS nftw()
-関数 \fBnftw\fP() は \fBftw\fP() と同じだが、引き数 \fIflags\fP が追加される点と、 \fIfn\fP() の引き数に
-\fIftwbuf\fP が追加される点が異なる。
-
-この \fIflags\fP 引き数は下記のフラグの 0 個以上の論理和を取ったものである:
-.TP
-\fBFTW_ACTIONRETVAL\fP (glibc 2.3.3 以降)
-このフラグは glibc 固有である。 このフラグをセットすると、 \fBnftw\fP() の \fIfn\fP() の返り値の扱いが変わる。 \fIfn\fP()
-は以下の値のいずれか一つを返す必要がある。
-.RS
-.TP
-\fBFTW_CONTINUE\fP
-\fBnftw\fP() は通常通り処理を続ける。
-.TP
-\fBFTW_SKIP_SIBLINGS\fP
-.\" If \fBFTW_DEPTH\fP
-.\" is set, the entry's parent directory is processed next (with
-.\" \fIflag\fP set to \fBFTW_DP\fP).
-\fIfn\fP() がこの値を返した場合、処理中のエントリーの兄弟 (同じ階層のエントリー)
-の処理はスキップされ、親ディレクトリで続きの処理が行われる。
-.TP
-\fBFTW_SKIP_SUBTREE\fP
-\fIfn\fP() が呼び出されたエントリーがディレクトリ (\fItypeflag\fP が \fBFTW_D\fP) の場合に、この値を返すと \fIfn\fP()
-の引き数として渡されたディレクトリ内のエントリーの処理が行われなくなる。 \fBnftw\fP() は処理中のディレクトリの兄弟 (同じ階層のエントリー)
-から処理を続ける。
-.TP
-\fBFTW_STOP\fP
-\fBnftw ()\fP は、返り値 \fBFTW_STOP\fP ですぐに復帰する。
-.PP
-他の返り値は将来新しい動作に対応付けられる可能性がある。 \fIfn\fP() は上記のリストにある値以外を返さないようにすべきである。
-
-\fI<ftw.h>\fP で \fBFTW_ACTIONRETVAL\fP の定義が有効にするためには、
-(「どの」ヘッダーファイルをインクルードするよりも前に) 機能検査マクロ \fB_GNU_SOURCE\fP を定義しなければならない。
-.RE
-.TP
-\fBFTW_CHDIR\fP
-セットされると、ディレクトリの内容を処理する前に そのディレクトリに \fBchdir\fP(2) する。このフラグは、 \fIfpath\fP
-が属すディレクトリで何らかの動作を実行する必要がある場合に 便利である。
-(このフラグを指定しても \fIfn\fP の \fIfpath\fP 引き数で渡されるパス名には影響しない。)
-.TP
-\fBFTW_DEPTH\fP
-セットされると、帰りがけ順探索 (post\-order traversal) を行う。 つまり、ディレクトリそのものを引き数とした \fIfn\fP()
-呼出しは、そのディレクトリに含まれるファイルとサブディレクトリに 対する処理の「後で」行われる
-(デフォルトでは、ディレクトリ自身の処理はディレクトリ内のエントリー より「前に」行なわれる)。
-.TP
-\fBFTW_MOUNT\fP
-セットされると、同じファイルシステムの中だけを探索対象とする (つまり、マウントポイントをまたぐことはない)。
-.TP
-\fBFTW_PHYS\fP
-セットされると、シンボリックリンクを辿らない (おそらくこちらが 通常望ましい動作だろう)。セットされていないとシンボリックリンクを
-辿るが、同じファイルが二回報告されることはない。
-.sp
-\fBFTW_PHYS\fP がセットされずに \fBFTW_DEPTH\fP がセットされると、自分自身に対するシンボリックリンクを配下に持つ
-ディレクトリに対して \fIfn\fP() が呼び出されることは決してない。
-.LP
-ディレクトリツリーのエントリー毎に、 \fBnftw\fP() は 4つの引き数で \fIfn\fP() を呼び出す。 \fIfpath\fP と \fIsb\fP は
-\fBftw\fP() と同じである。 \fItypeflag\fP には、 \fBftw\fP() で取り得る値のいずれか、または以下の値のいずれかが渡される:
-.TP
-\fBFTW_DP\fP
-\fIfpath\fP がディレクトリで、かつ \fIflags\fP で \fBFTW_DEPTH\fP が指定されていた (\fBFTW_DEPTH\fP が
-\fIflags\fP に指定されていなかった場合、 ディレクトリに対しては常に \fItypeflag\fP が \fBFTW_D\fP で \fIfn\fP()
-が呼び出される)。 \fIfpath\fP 配下のファイルとサブディレクトリは全て処理が終わっている。
-.TP
-\fBFTW_SL\fP
-.\" To obtain the definition of this constant from
-.\" .IR <ftw.h> ,
-.\" either
-.\" .B _BSD_SOURCE
-.\" must be defined, or
-.\" .BR _XOPEN_SOURCE
-.\" must be defined with a value of 500 or more.
-\fIfpath\fP がシンボリックリンクで、かつ \fBFTW_PHYS\fP が \fIflags\fP に セットされていた。
-.TP
-\fBFTW_SLN\fP
-\fIfpath\fP がシンボリックリンクで、存在しないファイルを指している (これがセットされるのは \fBFTW_PHYS\fP
-がセットされていない場合だけである)。
-.LP
-\fBnftw\fP() が \fIfn\fP() を呼び出す際に渡す 4つめの引き数は \fIFTW\fP 型の構造体である。
-.in +4n
-.nf
-
-struct FTW {
- int base;
- int level;
-};
-
-.fi
-.in
-\fIbase\fP は、ファイル名 (basename 要素) の、 \fIfpath\fP で渡されるパス名の中でのオフセットである。 \fIlevel\fP
-はディレクトリツリーでの \fIfpath\fP の深さを示す。深さはディレクトリツリーのトップ (root) からの 相対値である (\fIdirpath\fP
-は深さ 0 である)。
-.SH 返り値
-これらの関数は、成功すると 0 を、エラーが発生すると \-1 を返す。
-
-\fIfn\fP() が 0 以外を返した場合、ディレクトリツリーの探索を終了し、 \fIfn\fP() が返した値を \fBftw\fP() や
-\fBnftw\fP() の結果として返す。
-
-\fBnftw\fP() が \fBFTW_ACTIONRETVAL\fP フラグ付きで呼ばれた場合、ツリーの探索を終了させるために \fIfn\fP()
-が使用できる、非 0 の値は \fBFTW_STOP\fP だけであり、 この値は \fBnftw\fP() の返り値として返される。
-.SH バージョン
-\fBnftw\fP() は バージョン 2.1 以降の glibc で利用できる。
-.SH 準拠
-POSIX.1\-2001, SVr4, SUSv1. POSIX.1\-2008 は \fBftw\fP() を廃止予定としている。
-.SH 注意
-POSIX.1\-2001 の注記によると、 \fIfn\fP がカレントワーキングディレクトリを保持しなかった場合の 結果は規定されていないとされている。
-.PP
-\fBnftw\fP() 関数と、 \fBftw\fP() における \fBFTW_SL\fP は、SUSv1 で導入された。
-.LP
-\fBftw\fP() で \fBFTW_SL\fP を一切使わないシステムや、 存在しないファイルを指しているシンボリックリンクの場合にのみ \fBFTW_SL\fP
-を使うシステム、また \fBftw\fP() が全てのシンボリックリンクに対して \fBFTW_SL\fP を使うシステムもある。
-予測可能な動作をさせるためには、 \fBnftw\fP() を使うこと。
-.LP
-「stat できるがディレクトリではないオブジェクト」 (ファイル, シンボリックリンク, fifo 等) に対しては、すべて \fBFTW_F\fP
-が返される。
-
-\fBFTW_ACTIONRETVAL\fP は glibc 固有である。
-.SH 例
-以下のプログラムは、一つ目のコマンドライン引き数を名前に持つパス以下の ディレクトリツリーを探索する。引き数が指定されなかった場合は、
-カレントディレクトリ以下を探索する。 各々のファイルについて様々の情報が表示される。 二番目のコマンドライン引き数に文字を指定することで、
-\fBnftw\fP() を呼び出す際に \fIflags\fP 引き数に渡す値を制御することができる。
-.SS プログラムのソース
-.nf
-#define _XOPEN_SOURCE 500
-#include <ftw.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-#include <stdint.h>
-
-static int
-display_info(const char *fpath, const struct stat *sb,
- int tflag, struct FTW *ftwbuf)
-{
- printf("%\-3s %2d %7jd %\-40s %d %s\en",
- (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" :
- (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" :
- (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" :
- (tflag == FTW_SLN) ? "sln" : "???",
- ftwbuf\->level, (intmax_t) sb\->st_size,
- fpath, ftwbuf\->base, fpath + ftwbuf\->base);
- return 0; /* To tell nftw() to continue */
-}
-
-int
-main(int argc, char *argv[])
-{
- int flags = 0;
-
- if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL)
- flags |= FTW_DEPTH;
- if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL)
- flags |= FTW_PHYS;
-
- if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
- == \-1) {
- perror("nftw");
- exit(EXIT_FAILURE);
- }
- exit(EXIT_SUCCESS);
-}
-.fi
-.SH 関連項目
-\fBstat\fP(2), \fBfts\fP(3), \fBreaddir\fP(3)
-.SH この文書について
-この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
-である。プロジェクトの説明とバグ報告に関する情報は
-http://www.kernel.org/doc/man\-pages/ に書かれている。
OSDN Git Service
