.\" Copyright (c) 1993 Michael Haardt (michael@moria.de) .\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) .\" and copyright (c) 2006 Justin Pryzby .\" and copyright (c) 2006 Michael Kerrisk .\" .\" %%%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 .\" . .\" %%%LICENSE_END .\" .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu) .\" 2006-05-24, Justin Pryzby .\" document FTW_ACTIONRETVAL; include .SH RETURN VALUE; .\" 2006-05-24, Justin Pryzby and .\" Michael Kerrisk .\" reorganized and rewrote much of the page .\" 2006-05-24, Michael Kerrisk .\" 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 .\" Updated & Modified 1999-09-14, NAKANO Takeo .\" Updated & Modified 2005-11-04, Akihiro MOTOKI .\" Updated 2006-07-26, Akihiro MOTOKI , LDP v2.36 .\" .TH FTW 3 2020\-06\-09 Linux "Linux Programmer's Manual" .SH 名前 ftw, nftw \- ファイルツリーを歩きまわる .SH 書式 .nf \fB#include \fP .PP \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 .PP \fB#include \fP .PP \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 .fi .PP .RS -4 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7) 参照): .RE .PP \fBnftw\fP(): _XOPEN_SOURCE >= 500 .SH 説明 \fBnftw\fP() walks through the directory tree that is located under the directory \fIdirpath\fP, and calls \fIfn\fP() once for each entry in the tree. By default, directories are handled before the files and subdirectories they contain (preorder traversal). .PP To avoid using up all of the calling process's file descriptors, \fInopenfd\fP specifies the maximum number of directories that \fBnftw\fP() will hold open simultaneously. When the search depth exceeds this, \fBnftw\fP() will become slower because directories have to be closed and reopened. \fBnftw\fP() uses at most one file descriptor for each level in the directory tree. .PP For each entry found in the tree, \fBnftw\fP() calls \fIfn\fP() with four arguments: \fIfpath\fP, \fIsb\fP, \fItypeflag\fP, and \fIftwbuf\fP. \fIfpath\fP is the pathname of the entry, and is expressed either as a pathname relative to the calling process's current working directory at the time of the call to \fBnftw\fP(), if \fIdirpath\fP was expressed as a relative pathname, or as an absolute pathname, if \fIdirpath\fP was expressed as an absolute pathname. \fIsb\fP is a pointer to the \fIstat\fP structure returned by a call to \fBstat\fP(2) for \fIfpath\fP. .PP The \fItypeflag\fP argument passed to \fIfn\fP() is an integer that has one of the following values: .TP \fBFTW_F\fP \fIfpath\fP が通常のファイルである .TP \fBFTW_D\fP \fIfpath\fP がディレクトリである .TP \fBFTW_DNR\fP \fIfpath\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_NS\fP The \fBstat\fP(2) call failed on \fIfpath\fP, which is not a symbolic link. The probable cause for this is that the caller had read permission on the parent directory, so that the filename \fIfpath\fP could be seen, but did not have execute permission, so that the file could not be reached for \fBstat\fP(2). The contents of the buffer pointed to by \fIsb\fP are undefined. .TP \fBFTW_SL\fP .\" To obtain the definition of this constant from .\" .IR , .\" 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 is a symbolic link pointing to a nonexistent file. (This occurs only if \fBFTW_PHYS\fP is not set.) In this case the \fIsb\fP argument passed to \fIfn\fP() contains information returned by performing \fBlstat\fP(2) on the "dangling" symbolic link. (But see BUGS.) .PP The fourth argument (\fIftwbuf\fP) that \fBnftw\fP() supplies when calling \fIfn\fP() is a pointer to a structure of type \fIFTW\fP: .PP .in +4n .EX struct FTW { int base; int level; }; .EE .in .PP \fIbase\fP は、ファイル名 (basename 要素) の、 \fIfpath\fP で渡されるパス名の中でのオフセットである。 \fIlevel\fP はディレクトリツリーでの \fIfpath\fP の深さを示す。深さはディレクトリツリーのトップ (root) からの 相対値である (\fIdirpath\fP は深さ 0 である)。 .PP ツリーの探索を止めたい場合は、 \fIfn\fP() が 0 以外の値を返せば良い (この値は \fBnftw\fP() 自身の戻り値となる)。 それ以外の場合は \fBnftw\fP() はツリー全体の探索を続け、すべてのツリーを探索し終えたところで 0 を返す。探索中に (\fBmalloc\fP(3) の失敗などの) エラーが起こると \-1 を返す。 .PP \fBnftw\fP() は動的なデータ構造を用いるので、ツリー探索を安全に中断する唯一の方法は 0 以外の値を \fIfn\fP() の返り値とすることである。割り込みを扱うには、 例えば発生した割り込みをマークしておいて、 0 以外の値を返すようにする シグナルによりメモリーリークを起こさずに探索を終了できるようにするには、 シグナルハンドラーで \fIfn\fP() がチェックするグローバルなフラグをセットするようにすればよい。 プログラムを終了させる場合以外は、 \fBlongjmp\fP(3) を使用しないこと。 .PP The \fIflags\fP argument of \fBnftw\fP() is formed by ORing zero or more of the following flags: .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() は上記のリストにある値以外を返さないようにすべきである。 .PP \fI\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 セットされると、シンボリックリンクを辿らない (おそらくこちらが 通常望ましい動作だろう)。セットされていないとシンボリックリンクを 辿るが、同じファイルが二回報告されることはない。 .IP \fBFTW_PHYS\fP がセットされずに \fBFTW_DEPTH\fP がセットされると、自分自身に対するシンボリックリンクを配下に持つ ディレクトリに対して \fIfn\fP() が呼び出されることは決してない。 .SS ftw() \fBftw\fP() is an older function that offers a subset of the functionality of \fBnftw\fP(). The notable differences are as follows: .IP * 3 \fBftw\fP() has no \fIflags\fP argument. It behaves the same as when \fBnftw\fP() is called with \fIflags\fP specified as zero. .IP * The callback function, \fIfn\fP(), is not supplied with a fourth argument. .IP * The range of values that is passed via the \fItypeflag\fP argument supplied to \fIfn\fP() is smaller: just \fBFTW_F\fP, \fBFTW_D\fP, \fBFTW_DNR\fP, \fBFTW_NS\fP, and (possibly) \fBFTW_SL\fP. .SH 返り値 これらの関数は、成功すると 0 を、エラーが発生すると \-1 を返す。 .PP \fIfn\fP() が 0 以外を返した場合、ディレクトリツリーの探索を終了し、 \fIfn\fP() が返した値を \fBftw\fP() や \fBnftw\fP() の結果として返す。 .PP \fBnftw\fP() が \fBFTW_ACTIONRETVAL\fP フラグ付きで呼ばれた場合、ツリーの探索を終了させるために \fIfn\fP() が使用できる、非 0 の値は \fBFTW_STOP\fP だけであり、 この値は \fBnftw\fP() の返り値として返される。 .SH バージョン \fBnftw\fP() は バージョン 2.1 以降の glibc で利用できる。 .SH 属性 この節で使用されている用語の説明については、 \fBattributes\fP(7) を参照。 .TS allbox; lb lb lb l l l. インターフェース 属性 値 T{ \fBnftw\fP() T} Thread safety MT\-Safe cwd T{ \fBftw\fP() T} Thread safety MT\-Safe .TE .sp 1 .SH 準拠 POSIX.1\-2001, POSIX.1\-2008, SVr4, SUSv1. POSIX.1\-2008 は \fBftw\fP() を廃止予定としている。 .SH 注意 POSIX.1\-2008 notes that the results are unspecified if \fIfn\fP does not preserve the current working directory. .PP \fBnftw\fP() 関数と、 \fBftw\fP() における \fBFTW_SL\fP は、SUSv1 で導入された。 .PP In some implementations (e.g., glibc), \fBftw\fP() will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only for symbolic links that do not point to an existing file, and again on other systems \fBftw\fP() will use \fBFTW_SL\fP for each symbolic link. If \fIfpath\fP is a symbolic link and \fBstat\fP(2) failed, POSIX.1\-2008 states that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP is passed in \fItypeflag\fP. For predictable results, use \fBnftw\fP(). .SH バグ .\" https://bugzilla.redhat.com/show_bug.cgi?id=1422736 .\" http://austingroupbugs.net/view.php?id=1121 .\" glibc commit 6ba205b2c35e3e024c8c12d2ee1b73363e84da87 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=23501 According to POSIX.1\-2008, when the \fItypeflag\fP argument passed to \fIfn\fP() contains \fBFTW_SLN\fP, the buffer pointed to by \fIsb\fP should contain information about the dangling symbolic link (obtained by calling \fBlstat\fP(2) on the link). Early glibc versions correctly followed the POSIX specification on this point. However, as a result of a regression introduced in glibc 2.4, the contents of the buffer pointed to by \fIsb\fP were undefined when \fBFTW_SLN\fP is passed in \fItypeflag\fP. (More precisely, the contents of the buffer were left unchanged in this case.) This regression was eventually fixed in glibc 2.30, so that the glibc implementation (once more) follows the POSIX specification. .SH 例 以下のプログラムは、一つ目のコマンドライン引数を名前に持つパス以下の ディレクトリツリーを探索する。引数が指定されなかった場合は、 カレントディレクトリ以下を探索する。 各々のファイルについて様々の情報が表示される。 二番目のコマンドライン引数に文字を指定することで、 \fBnftw\fP() を呼び出す際に \fIflags\fP 引数に渡す値を制御することができる。 .SS プログラムのソース \& .EX #define _XOPEN_SOURCE 500 #include #include #include #include #include static int display_info(const char *fpath, const struct stat *sb, int tflag, struct FTW *ftwbuf) { printf("%\-3s %2d ", (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); if (tflag == FTW_NS) printf("\-\-\-\-\-\-\-"); else printf("%7jd", (intmax_t) sb\->st_size); printf(" %\-40s %d %s\en", 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); } .EE .SH 関連項目 \fBstat\fP(2), \fBfts\fP(3), \fBreaddir\fP(3) .SH この文書について この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は \%https://www.kernel.org/doc/man\-pages/ に書かれている。