Manpages

名 前

ftw, nftw − フ ァ イ ル ツ リ ー を 歩 き ま わ る

書 式

#include <ftw.h>

int ftw(const char *dirpath,
int (*fn) (const char *fpath, const struct stat *sb,
int typeflag),
int nopenfd);

#define _XOPEN_SOURCE 500 /* feature_test_macros(7) 参 照 */
#define _XOPEN_SOURCE 500
#include <ftw.h>

int nftw(const char *dirpath,
int (*fn) (const char *fpath, const struct stat *sb,
int typeflag, struct FTW *ftwbuf),
int nopenfd, int flags);

説 明

ftw() は 、 dirpath で 指 定 さ れ た デ ィ レ ク ト リ 以 下 の デ ィ レ ク ト リ ツ リ ー 全 体 を 歩 き ま わ り 、 ツ リ ー 中 で エ ン ト リ ー が 見 付 か る ご と に 、 fn() を 呼 び 出 す 。 デ フ ォ ル ト で は 、 デ ィ レ ク ト リ そ の も の が 、 そ の デ ィ レ ク ト リ に あ る フ ァ イ ル や サ ブ デ ィ レ ク ト リ よ り も 先 に 処 理 さ れ る (行 き が け 順 探 索 ; preorder traversal)。 呼 び 出 し 元 プ ロ セ ス が 利 用 可 能 な フ ァ イ ル デ ィ ス ク リ プ タ ー を 使 い 切 っ て し ま わ な い よ う に す る た め 、 ftw() が 同 時 に オ ー プ ン す る デ ィ レ ク ト リ の 最 大 数 を nopenfd で 指 定 す る こ と が で き る 。 探 索 の 深 さ が こ の 値 を 越 え る と 、 一 つ の デ ィ レ ク ト リ を 閉 じ て か ら 他 の デ ィ レ ク ト リ を オ ー プ ン し 直 す こ と に な る の で 、 ftw() の 動 作 は 遅 く な る 。 ftw() は 、 デ ィ レ ク ト リ ツ リ ー の 階 層 1 レ ベ ル に つ き 、 最 大 で も 一 つ の フ ァ イ ル デ ィ ス ク リ プ タ ー し か 使 用 し な い 。 デ ィ レ ク ト リ ツ リ ー で 見 つ か っ た エ ン ト リ ー 毎 に 、 ftw() は fpath, sb, typeflag の 3つ を 引 き 数 と し て fn() を 呼 び 出 す 。 fpath は エ ン ト リ ー の パ ス 名 で あ る 。 dirpath が 相 対 パ ス 名 で 指 定 さ れ た 場 合 に は 、 fpath は ftw() が 呼 び 出 さ れ た 時 点 の 呼 び 出 し 元 プ ロ セ ス の カ レ ン ト ワ ー キ ン グ デ ィ レ ク ト リ か ら の 相 対 パ ス 名 と な る 。 dirpath が 絶 対 パ ス 名 で 指 定 さ れ た 場 合 に は 、 fpath は 絶 対 パ ス 名 と な る 。 sb は fpath に 対 す る stat(2) の 呼 び 出 し で 返 さ れ る stat 構 造 体 へ の ポ イ ン タ ー で あ る 。 typeflag は 整 数 で 、 以 下 の 値 の い ず れ か 一 つ で あ る :

FTW_DNR

fpath が 読 み 込 み で き な い デ ィ レ ク ト リ で あ る

fpath が シ ン ボ リ ッ ク リ ン ク で 、 か つ stat(2) が 失 敗 し た 場 合 、 FTW_NS と FTW_SL (後 述 ) の ど ち ら が typeflag に 渡 さ れ る か は 未 定 義 で あ る と 、 POSIX.1−2001 に は 書 か れ て い る 。 ツ リ ー の 探 索 を 止 め た い 場 合 は 、 fn() が 0 以 外 の 値 を 返 せ ば 良 い (こ の 値 は ftw() 自 身 の 戻 り 値 と な る )。 そ れ 以 外 の 場 合 は ftw() は ツ リ ー 全 体 の 探 索 を 続 け 、 す べ て の ツ リ ー を 探 索 し 終 え た と こ ろ で 0 を 返 す 。 探 索 中 に (malloc(3) の 失 敗 な ど の ) エ ラ ー が 起 こ る と −1 を 返 す 。

ftw() は 動 的 な デ ー タ 構 造 を 用 い る の で 、 ツ リ ー 探 索 を 安 全 に 中 断 す る 唯 一 の 方 法 は 0 以 外 の 値 を fn() の 返 り 値 と す る こ と で あ る 。 割 り 込 み を 扱 う に は 、 例 え ば 発 生 し た 割 り 込 み を マ ー ク し て お い て 、 0 以 外 の 値 を 返 す よ う に す る シ グ ナ ル に よ り メ モ リ ー リ ー ク を 起 こ さ ず に 探 索 を 終 了 で き る よ う に す る に は 、 シ グ ナ ル ハ ン ド ラ ー で fn() が チ ェ ッ ク す る グ ロ ー バ ル な フ ラ グ を セ ッ ト す る よ う に す れ ば よ い 。 プ ロ グ ラ ム を 終 了 さ せ る 場 合 以 外 は 、 longjmp(3) を 使 用 し な い こ と 。

nftw() 関 数 nftw() は ftw() と 同 じ だ が 、 引 き 数 flags が 追 加 さ れ る 点 と 、 fn() の 引 き 数 に ftwbuf が 追 加 さ れ る 点 が 異 な る 。 こ の flags 引 き 数 は 下 記 の フ ラ グ の 0 個 以 上 の 論 理 和 を 取 っ た も の で あ る :
FTW_ACTIONRETVAL (glibc 2.3.3 以 降 ) こ の フ ラ グ は glibc 固 有 で あ る 。 こ の フ ラ グ を セ ッ ト す る と 、 nftw() の fn() の 返 り 値 の 扱 い が 変 わ る 。 fn() は 以 下 の 値 の い ず れ か 一 つ を 返 す 必 要 が あ る 。

FTW_CONTINUE

nftw() は 通 常 通 り 処 理 を 続 け る 。

FTW_SKIP_SIBLINGS

fn() が こ の 値 を 返 し た 場 合 、 処 理 中 の エ ン ト リ ー の 兄 弟 (同 じ 階 層 の エ ン ト リ ー ) の 処 理 は ス キ ッ プ さ れ 、 親 デ ィ レ ク ト リ で 続 き の 処 理 が 行 わ れ る 。

FTW_SKIP_SUBTREE

fn() が 呼 び 出 さ れ た エ ン ト リ ー が デ ィ レ ク ト リ (typeflag が FTW_D) の 場 合 に 、 こ の 値 を 返 す と fn() の 引 き 数 と し て 渡 さ れ た デ ィ レ ク ト リ 内 の エ ン ト リ ー の 処 理 が 行 わ れ な く な る 。 nftw() は 処 理 中 の デ ィ レ ク ト リ の 兄 弟 (同 じ 階 層 の エ ン ト リ ー ) か ら 処 理 を 続 け る 。

FTW_STOP

nftw () は 、 返 り 値 FTW_STOP で す ぐ に 復 帰 す る 。 他 の 返 り 値 は 将 来 新 し い 動 作 に 対 応 付 け ら れ る 可 能 性 が あ る 。 fn() は 上 記 の リ ス ト に あ る 値 以 外 を 返 さ な い よ う に す べ き で あ る 。

<ftw.h> で FTW_ACTIONRETVAL の 定 義 が 有 効 に す る た め に は 、 (「 ど の 」 ヘ ッ ダ ー フ ァ イ ル を イ ン ク ル ー ド す る よ り も 前 に ) 機 能 検 査 マ ク ロ _GNU_SOURCE を 定 義 し な け れ ば な ら な い 。

FTW_CHDIR セ ッ ト さ れ る と 、 デ ィ レ ク ト リ の 内 容 を 処 理 す る 前 に そ の デ ィ レ ク ト リ に chdir(2) す る 。 こ の フ ラ グ は 、 fpath が 属 す デ ィ レ ク ト リ で 何 ら か の 動 作 を 実 行 す る 必 要 が あ る 場 合 に 便 利 で あ る 。 (こ の フ ラ グ を 指 定 し て も fn の fpath 引 き 数 で 渡 さ れ る パ ス 名 に は 影 響 し な い 。 )
FTW_DEPTH セ ッ ト さ れ る と 、 帰 り が け 順 探 索 (post−order traversal) を 行 う 。 つ ま り 、 デ ィ レ ク ト リ そ の も の を 引 き 数 と し た fn() 呼 出 し は 、 そ の デ ィ レ ク ト リ に 含 ま れ る フ ァ イ ル と サ ブ デ ィ レ ク ト リ に 対 す る 処 理 の 「 後 で 」 行 わ れ る (デ フ ォ ル ト で は 、 デ ィ レ ク ト リ 自 身 の 処 理 は デ ィ レ ク ト リ 内 の エ ン ト リ ー よ り 「 前 に 」 行 な わ れ る )。
FTW_MOUNT セ ッ ト さ れ る と 、 同 じ フ ァ イ ル シ ス テ ム の 中 だ け を 探 索 対 象 と す る (つ ま り 、 マ ウ ン ト ポ イ ン ト を ま た ぐ こ と は な い )。
FTW_PHYS セ ッ ト さ れ る と 、 シ ン ボ リ ッ ク リ ン ク を 辿 ら な い (お そ ら く こ ち ら が 通 常 望 ま し い 動 作 だ ろ う )。 セ ッ ト さ れ て い な い と シ ン ボ リ ッ ク リ ン ク を 辿 る が 、 同 じ フ ァ イ ル が 二 回 報 告 さ れ る こ と は な い 。

FTW_PHYS が セ ッ ト さ れ ず に FTW_DEPTH が セ ッ ト さ れ る と 、 自 分 自 身 に 対 す る シ ン ボ リ ッ ク リ ン ク を 配 下 に 持 つ デ ィ レ ク ト リ に 対 し て fn() が 呼 び 出 さ れ る こ と は 決 し て な い 。 デ ィ レ ク ト リ ツ リ ー の エ ン ト リ ー 毎 に 、 nftw() は 4つ の 引 き 数 で fn() を 呼 び 出 す 。 fpath と sb は ftw() と 同 じ で あ る 。 typeflag に は 、 ftw() で 取 り 得 る 値 の い ず れ か 、 ま た は 以 下 の 値 の い ず れ か が 渡 さ れ る :

FTW_SLN

fpath が シ ン ボ リ ッ ク リ ン ク で 、 存 在 し な い フ ァ イ ル を 指 し て い る (こ れ が セ ッ ト さ れ る の は FTW_PHYS が セ ッ ト さ れ て い な い 場 合 だ け で あ る )。

nftw() が fn() を 呼 び 出 す 際 に 渡 す 4つ め の 引 き 数 は FTW 型 の 構 造 体 で あ る 。

struct FTW {
int base;
int level; };

base は 、 フ ァ イ ル 名 (basename 要 素 ) の 、 fpath で 渡 さ れ る パ ス 名 の 中 で の オ フ セ ッ ト で あ る 。 level は デ ィ レ ク ト リ ツ リ ー で の fpath の 深 さ を 示 す 。 深 さ は デ ィ レ ク ト リ ツ リ ー の ト ッ プ (root) か ら の 相 対 値 で あ る (dirpath は 深 さ 0 で あ る )。

返 り 値

こ れ ら の 関 数 は 、 成 功 す る と 0 を 、 エ ラ ー が 発 生 す る と −1 を 返 す 。

fn() が 0 以 外 を 返 し た 場 合 、 デ ィ レ ク ト リ ツ リ ー の 探 索 を 終 了 し 、 fn() が 返 し た 値 を ftw() や nftw() の 結 果 と し て 返 す 。

nftw() が FTW_ACTIONRETVAL フ ラ グ 付 き で 呼 ば れ た 場 合 、 ツ リ ー の 探 索 を 終 了 さ せ る た め に fn() が 使 用 で き る 、 非 0 の 値 は FTW_STOP だ け で あ り 、 こ の 値 は nftw() の 返 り 値 と し て 返 さ れ る 。

バ ー ジ ョ ン

nftw() は バ ー ジ ョ ン 2.1 以 降 の glibc で 利 用 で き る 。

準 拠

POSIX.1−2001, SVr4, SUSv1. POSIX.1−2008 は ftw() を 廃 止 予 定 と し て い る 。

注 意

POSIX.1−2001 の 注 記 に よ る と 、 fn が カ レ ン ト ワ ー キ ン グ デ ィ レ ク ト リ を 保 持 し な か っ た 場 合 の 結 果 は 規 定 さ れ て い な い と さ れ て い る 。

nftw() 関 数 と 、 ftw() に お け る FTW_SL は 、 SUSv1 で 導 入 さ れ た 。

ftw() で FTW_SL を 一 切 使 わ な い シ ス テ ム や 、 存 在 し な い フ ァ イ ル を 指 し て い る シ ン ボ リ ッ ク リ ン ク の 場 合 に の み FTW_SL を 使 う シ ス テ ム 、 ま た ftw() が 全 て の シ ン ボ リ ッ ク リ ン ク に 対 し て FTW_SL を 使 う シ ス テ ム も あ る 。 予 測 可 能 な 動 作 を さ せ る た め に は 、 nftw() を 使 う こ と 。 「 stat で き る が デ ィ レ ク ト リ で は な い オ ブ ジ ェ ク ト 」 (フ ァ イ ル , シ ン ボ リ ッ ク リ ン ク , fifo 等 ) に 対 し て は 、 す べ て FTW_F が 返 さ れ る 。

FTW_ACTIONRETVAL は glibc 固 有 で あ る 。

例

以 下 の プ ロ グ ラ ム は 、 一 つ 目 の コ マ ン ド ラ イ ン 引 き 数 を 名 前 に 持 つ パ ス 以 下 の デ ィ レ ク ト リ ツ リ ー を 探 索 す る 。 引 き 数 が 指 定 さ れ な か っ た 場 合 は 、 カ レ ン ト デ ィ レ ク ト リ 以 下 を 探 索 す る 。 各 々 の フ ァ イ ル に つ い て 様 々 の 情 報 が 表 示 さ れ る 。 二 番 目 の コ マ ン ド ラ イ ン 引 き 数 に 文 字 を 指 定 す る こ と で 、 nftw() を 呼 び 出 す 際 に flags 引 き 数 に 渡 す 値 を 制 御 す る こ と が で き る 。 プ ロ グ ラ ム の ソ ー ス

#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\n",
(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], 'd') != NULL)
flags |= FTW_DEPTH;
if (argc > 2 && strchr(argv[2], 'p') != NULL)
flags |= FTW_PHYS;

if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
== −1) {
perror("nftw");
exit(EXIT_FAILURE); }
exit(EXIT_SUCCESS); }

関 連 項 目

stat(2), fts(3), readdir(3)

こ の 文 書 に つ い て

こ の man ペ ー ジ は Linux man−pages プ ロ ジ ェ ク ト の リ リ ー ス 3.79 の 一 部 で あ る 。 プ ロ ジ ェ ク ト の 説 明 と バ グ 報 告 に 関 す る 情 報 は http://www.kernel.org/doc/man−pages/ に 書 か れ て い る 。