---

   ftw - обход файлового дерева

---

Other Alias

---

ОБЗОР

#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);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

nftw(): _XOPEN_SOURCE >= 500

---

ОПИСАНИЕ

Чтобы избежать использования всех файловых дескрипторов вызывающего процесса, в nopenfd задаётся максимальное количество одновременно открываемых nftw() каталогов. Когда это количество превышается, работа nftw() немного замедляется, так как каталоги будут закрываться и снова открываться. Функция nftw() использует не более одного файлового дескриптора для работы с каждым уровнем дерева каталогов.

Для каждого найденного элемента дерева nftw() вызывает функцию fn() с четырьмя аргументами: fpath, sb, typeflag и ftwbuf. В fpath указывается полное имя элемента в виде, или пути относительно рабочего каталога вызывающего процесса на момент вызова nftw() (если dirpath указан в виде относительного пути), или абсолютного пути (если dirpath указан в виде абсолютного пути). В sb задаётся указатель на структуру stat, возвращаемую вызовом stat(2) для fpath. В typeflag указывается целое число, которое может быть одним из следующих:

FTW_F fpath обычный файл

FTW_D fpath каталог

FTW_DNR fpath каталог, который не может быть прочитан

FTW_DP fpath является каталогом, и в flags установлен FTW_DEPTH (если FTW_DEPTH отсутствует в flags, то каталоги всегда будут просматриваться с typeflag равным FTW_D). Обработаны все файлы и подкаталоги в fpath.

FTW_NS Вызов stat(2) завершился с ошибкой для fpath, который не является символьной ссылкой. Вероятно, проблема в том, что вызывающий имеет право на чтение родительского каталога, и поэтому файл с именем fpath доступен, но не имеет права выполнения, и поэтому файл недоступен для stat(2).

FTW_SL fpath является символьной ссылкой и в flags установлен FTW_PHYS.

FTW_SLN fpath является символьной ссылкой, указывающей на несуществующий файл (это может произойти, только если не установлен флаг FTW_PHYS).

Четвёртый аргумент, передаваемый nftw() при вызове fn(), является структурой типа FTW:

struct FTW {
    int base;
    int level;
};

Для остановки обхода дерева fn() возвращает ненулевое значение; оно станет возвращаемым значением для nftw(). Пока fn() возвращает 0, nftw() будет продолжать свой поиск до полного обхода дерева (в этом случае она возвратит ноль), или пока не возникнет ошибка (например, из-за malloc(3)). В этом случае функция возвратит значение -1.

Так как nftw() использует динамические структуры данных, то единственным безопасным способом для выхода из процесса обхода дерева будет возврат ненулевого значения из fn(). Для завершения обхода по сигналу без утечек памяти в обработчике нужно устанавливать глобальный флаг, проверяемый fn(). Не используйте longjmp(3) кроме как для завершения программы.

Значение аргумента flags в nftw() составляется логическим сложением 0 или нескольких следующих флагов:

FTW_ACTIONRETVAL (начиная с glibc 2.3.3) Если этот флаг, имеющийся только в glibc, не задан, то nftw() по другому обрабатывает полученное от fn() значение. Вызов fn() должен возвращать одно из следующих значений:

#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;           /* указать nftw() продолжать */
}
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);
}