名字
ftw,nftw - 文件树遍历
概要
#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);#include <ftw.h>
int ftw(const char *dirpath,int (*fn) (const char *fpath, const struct stat *sb,int typeflag),int nopenfd);描述
nftw()
nftw()遍历位于文件夹dirpath下面的目录树，为每个树的节点调用一次fn()。默认情况下，当前目录总是先于其包含的文件和子目录被处理（先序遍历）。
为了避免调用进程的文件描述符被用尽，nopenfd指定了 nftw() 能够同时打开目录的最大数量。当搜索深度超过这个值，nftw() 将会变慢，因为目录必须被关掉和重新打开。nftw() 为目录树中的每一层至多使用一个文件描述符。
对于在树中发现的每个节点，nftw() 为其调用带四个参数的函数fn(),这四个参数为fpath，sb，typeflag和ftwbuf。fpath是节点的路径名，它可以表示为相对路径或者绝对路径，相对路径是相对调用进程的当前工作目录。sb是为fpath调用stat函数所返回的指向stat结构体的指针。typeflag是一个整型值，取下面其中一个值：
- FTW_F fpath是一个普通文件。
- FTW_D fpath是一个目录。
- FTW_DNR fpath是一个不能被读的目录。
- FTW_DP fpath是一个目录，并且 flag参数被指定为FTW_DEPTH。（如果flags没有被指定为FTW_DEPTH，那么访问目录时使用的typeflag总会是FTW_D。）路径fpath下的所有文件和子目录已经被处理过了。
- FTW_NS 在不是符号链接的fpath上调用stat失败。可能的原因是调用者对父目录有读权限，所以文件名fpath可以被看到，但是没有执行权限，所以执行stat失败。由sb指向的缓存的内容是未定义的。
- FTW_SL fpath是一个符号链接，flags被设置为FTW_PHYS。
- FTW_SLN fpath是一个指向不存在的文件的符号链接。（只在FTW_PHYS未被设置的时候才会发生。）
当调用fn() 时 nftw() 为其提供的第四个参数是一个类型为FTW的结构体：
struct FTW
{int base;int level;
};base是在fpath中给定的路径名中的文件名（basename）的偏移量。level是fpath在目录树中相对于根节点的深度（dirpath的深度为0）。
为了让树的遍历停止，fn() 返回一个非0值；这个值将会成为 nftw() 的返回值。只要fn()返回值为0，nftw()将会继续遍历目录树，直到要么遍历完整个树，在这种情况下会返回0；要么遇到一个错误（比如malloc失败），在这种情况下返回-1。
因为nftw() 使用动态数据结构，遍历目录树时唯一的安全退出方法就是从fn() 返回一个非0值。为了让信号量终止遍历时不会造成内存泄露，让处理这设置一个全局的flag，由fn()对这个全局flag进行检查。不要使用longjmp,除非程序将会终止（terminate）。
nftw() 的flags 参数由下面的一个或者多个的flags进行或运算所形成：
FTW_ACTIONRETVAL (从 glibc 2.3.3开始支持)
如果这个特定的glibc的flag被设置，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的定义，必须在Include任何头文件之前定义功能测试宏 _GNU_SOURCE。
- FTW_CONTINUE
- FTW_CHDIR
如果设置了这个flag,在处理每个目录的内容之前，都会chdir(2)到这个目录。如果程序需要在fpath所在的某个目录做一些操作，这就是有用的。（指定这个flag不会对作为fn 参数fpath进行传递的路径名有影响。） - FTW_DEPTH
设置这个flag会进行后序遍历，也就是在处理完当前目录的内容和它的所有子目录之后才会调用fn() (默认情况下，每个目录在它的内容之前被处理。) - FTW_MOUNT
设置这个flag，就会停留在同一个文件系统中（也就是不会跨越挂载点）。 FTW_PHYS
设置这个flag，就不会跟随符号链接。（这是你想做的。）如果不设置这个flag，就会跟随符号链接，但是没有文件会被报告两次。
如果FTW_PHYS没有被设置，但是设置了FTW_DEPTH，那么函数fn() 就永远不会被自己是自己子孙的目录调用到。
ftw()
ftw() 是一个旧函数，它提供的功能是nftw()函数功能的一个子集。它们的区别如下：
- ftw() 没有flags参数。它和调用参数flags 为0的nftw()等价。
- 回调函数fn() 中没有提供第四个参数。
- 提供给fn() 的typeflag 参数可供选择的范围更小：只有FTW_F,FTW_D, FTW_DNR, FTW_NS,(可能支持) FTW_SL.
返回值
这些函数成功返回0，失败返回-1.
如果fn() 返回非0值，那么树的遍历被终止，fn() 的返回值被当作ftw() 和 nftw() 的返回值返回。
如果nftw() 的调用设置了FTW_ACTIONRETVAL flag,那么应该被fn() 使用的用来终止树的遍历的唯一一个非0值就是FTW_STOP，这个值作为nftw() 的执行结果被返回。
例子
下面的程序遍历以第一个命令行参数作为路径名下的目录树，如果没有指定路径名参数，那么就遍历当前目录下的目录树。它会显示每个文件的不同信息。第二个命令行参数用来指定一些字符，它们可以控制调用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 ",(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("-------");elseprintf("%7jd", (intmax_t) sb->st_size);printf(" %-40s %d %s\n",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);
}
