FTS(3) BSD 库函数手册 遍历文件夹(二)

一、FTS_OPEN

　　FTS * fts_open(char * const *path_argv, int options,
　　　　　　　　int (*compar)(const FTSENT **, const FTSENT **));

　　函数fts_open()接受一个指向数组的指针，字符指针命名了一个或多个路径组成了要遍历的逻辑文件层次。数组必须以NULL指针结束。

　　这有很多选项，但是至少它们(FTS_LOGICAL 或 FTS_PHYSICAL)中的一个必须被指定。options 包含以下值：

　　FTS_COMFOLLOW
　　　　　　此option把任何指定的符号链接作为一个根路径(root path)紧跟着FTS_LOGICAL,不管FTS_LOGICAL是否被指定。

　　FTS_LOGICAL
　　　　　　此option导致fts给符号链接的对象(target)返回FTSENT结构，而不是返回给符号链接本身。如果设置了该option，只有那些引用了不存在的文件的符号链接才把FTSENT 结构返回给应用程序。FTS_LOSICAL或FTS_PHYSICAL必须提供给fts_open()函数

　　FTS_NOSTAT
　　　　　　默认情况下，程序为每个被访问的程序返回FTSENT 结构引用文件的特征信息(FTSENT结构中的statp字段）。本option使那个规定作为性能优化，允许fts函数把fts_info字段设置为FTS_NSOK，并使statp字段未定义

　　FTS_PHYSICAL
　　　　　　　　此选项让fts把FTSENT结构返回给符号链接自身，而不是给它指向的对象。如果设置了该option，文件层次里所有符号链接的FTSENT 结构都将返回给应用程序。FTS_LOSICAL或FTS_PHYSICAL必须提供给fts_open()函数

　　FTS_SEEDOT
　　　　　　默认情况下，除非它们是被作为参数指定给函数 fts_open(), 任何以'.' 或 '..'命名的文件都将被忽视。这个option导致fts例程给点文件返回FTSENT结构。

　　FTS_XDEV
　　　　　　　　此选项阻止fts遍历到那些跟开始目录有着不同device number(设备号)的目录中

int (*compar)(const FTSENT **, const FTSENT **)

参数 compar() 指定了一个用户定义的函数，该函数可能被用来整理要遍历的层次。它接受2个指向FTSENT结构的指针的指针，并返回一个int值。正值，零或负值用来表明第一个参数引用的文件是位于第二个参数引用的文件之前，无序，或者之后。FTSENT 结构的fts_accpath, fts_path 和 fts_pathlen 字段也许根本不会在这个comparison(对照)里使用。如果fts_info字段被设为FTS_NS 或 FTS_NSOK，字段fts_statp也不用。如果compar()参数是NULL，目录遍历顺序就是在path_argv里标记的那个顺序。

二、FTS_OPEN_B

　　FTS * fts_open_b(char * const *path_argv, int options,
　　　　　　　　int (^compar)(const FTSENT **, const FTSENT **));

　　fts_open_b()函数跟fts_open()函数很像，除了cmpar是一个块指针而不是函数指针。此块指针将传递给 qsort_b(3)(而fts_open把函数指针传递给qsort(3)).

三、FTS_READ

　　FTSENT * fts_read(FTS *ftsp);

　　fts_read()函数返回一个指向FTSENT结构的指针, 该结构包含了hierarchy(层)里某个文件的信息。目录(可读的，不导致循环(do not cause cycles)的)至少被访问2次，一次以前序方式访问，一次以后序方式。其它文件则至少访问一次。(不导致循环的目录间的硬链接或者两个符号链接之间可能导致文件不止一次被访问，目录则会超过两次)。

　　如果所有层里的成员都已经遍历完毕，fts_read()返回NULL并且设置外部变量errno为0。如果一个跟文件无关的错误发生，fts_read()返回NULL并设置相应的errno。如果产生一个跟文件有关的错误，返回一个指向FTSENT结构的指针，errno可能设置也可能不设置(参见fts_info)。

　　fts_read()返回的FTSENT结构可能在调用了在同一个文件层次流里的fts_close()或fts_read()之后被覆盖，除非他们代表文件类型目录，这样结构就不会被覆盖直到后序访问的fts_read()返回FTSENT结构后又调用fts_read()函数。

四、FTS_CHILDREN

　　FTSENT * fts_children(FTS *ftsp, int options);

　　fts_children()函数返回一个指向FTSENT结构的指针。该结构表述了目录中以NULL结束的文件链表的第一项，是fts_read()最近一次返回的。该链表通过FTSENT结构的fts_link字段连接，并由用户指定的comparison(对照)函数排序。重复调用fts_children()会重新生成链表。

　　作为特殊情况，如果hierarchy(层)还没调用fts_read()函数。fts_children()函数会返回一个指针，指向由fts_open()打开的逻辑目录中的文件。否则，如果fts_read()最近返回的FTSENT结构不是一个目录，或者返回的目录不包含任何文件，fts_children返回NULL并设置errbo为0. 如果有错误产生，fts_children()返回NULL并设置相应的errno.

　　fts_children()返回的FTSENT结构可能在同一个(file hierarchy stream)文件层次流里调用了fts_children(),fts_close() 或 fts_read()后被覆盖。

　　选项可以是以下值：

　　FTS_NAMEONLY　　只需要文件名。 返回的结构链表中的所有字段的内容是未定义的，除了fts_name, fts_namelen字段。

五、 FTS_SET

　　int fts_set(FTS *ftsp, FTSENT *f, int options);

　　函数fts_set()允许用户应用程序决定对流ftsp中文件f的进一步处理。成功返回0，出错返回-1.

　　选项必须是以下值之一：

　　FTS_AGAIN

　　　　　　重新访问文件，任何类型文件都可能被再次访问。接下来调用的fts_read()将返回这个引用文件。结构中的fts_stat 和 fts_info 字段将在那时重新初始化， 但是其他字段不变。此选择只针对fts_read()函数最近刚返回的文件。 一般是用于后序目录访问，在此让目录跟它所有的descendants(后裔)一样再次被访问(包括前序和后序)。

　　FTS_FOLLOW

　　　　　　引用文件必须是符号链接。 如果这引用文件是fts_read()最近刚返回的， 下个fts_read()返回的文件，fts_info 和 fts_statp都被重新初始化用来放映此链接文件的对象，而不是该链接文件。另一种情况，如果该链接文件不存在链接对象，返回的结构字段将保持不变，fts_info字段被设置为FTS_SLNONE.

　　FTS_SKIP

　　　　　　不访问此文件的任何descendants(后裔)。此文件可以是函数fts_children()和函数fts_read()最近返回的文件之一。

 

六、FTS_CLOSE

　　　fts_close()函数关闭文件层次流ftsp, 保存当前目录到调用fts_open()打开的ftsp的那个目录里。成功返回0，失败返回-1。

七、ERRORS(错误)

　　fts_open()函数可能失败， errno值为库函数open(2)和malloc(3)指定的错误类型。

　　fts_close()函数可能失败，errno值为库函数chdir(2)和close(2)指定的错误类型。

　　fts_read()和 fts_children()函数可能失败，errno值为库函数chdir(2), malloc(3), opendir(3), readdir(3) 和 stat(2)指定的错误类型。

　　此外，fts_children(), fts_open()和fts_set()可能失败，errno设置如下：

　　　　[EINVAL]　　　　选项无效