APUE-文件和目录（六）函数ftw和nftw

名字

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() 应该返回下面的值的其中一个：

  1. FTW_CONTINUE
     让nftw() 继续正常进行。

  2. FTW_SKIP_SIBLINGS
     如果fn() 返回这个值，当前节点的兄弟节点会被跳过，处理从父节点继续进行。

  3. FTW_SKIP_SUBTREE
     如果一个目录节点调用fn()(typeflag是FTW_D),这个返回值会阻止这个目录下的对象作为参数传递给fn()。nftw() 继续处理当前目录的下一个兄弟节点。

  4. FTW_STOP
     这会导致nftw() 立即返回FTW_STOP。

     其它返回值可以关联到未来的一些新的行为上；fn() 不应该返回除上面列出的值之外的其它值。

     为了从<ftw.h>中获取FTW_ACTIONRETVAL的定义，必须在Include任何头文件之前定义功能测试宏 _GNU_SOURCE。

• 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("-------");
    else
        printf("%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);
}