APUE-文件和目录(六)函数ftw和nftw

时间:2021-03-31 04:42:03

名字

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(),这四个参数为fpathsbtypeflagftwbuffpath是节点的路径名,它可以表示为相对路径或者绝对路径,相对路径是相对调用进程的当前工作目录。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)的偏移量。levelfpath在目录树中相对于根节点的深度(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_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);
}