НАИМЕНОВАНИЕ¶

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

БИБЛИОТЕКА¶

Стандартная библиотека языка C (libc, -lc)

ОБЗОР¶

#include <ftw.h>

int nftw(const char *dirpath,
        typeof(int (const char *fpath, const struct stat *sb,
                    int typeflag, struct FTW *ftwbuf))
            *fn,
        int nopenfd, int flags);

[[deprecated]]
int ftw(const char *dirpath,
        typeof(int (const char *fpath, const struct stat *sb,
                    int typeflag))
            *fn,
        int nopenfd);

nftw():

    _XOPEN_SOURCE >= 500

ОПИСАНИЕ¶

nftw() walks through the directory tree that is located under the directory dirpath, and calls fn() once for each entry in the tree. By default, directories are handled before the files and subdirectories they contain (preorder traversal).

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

For each entry found in the tree, nftw() calls fn() with four arguments: fpath, sb, typeflag, and ftwbuf. fpath is the pathname of the entry, and is expressed either as a pathname relative to the calling process's current working directory at the time of the call to nftw(), if dirpath was expressed as a relative pathname, or as an absolute pathname, if dirpath was expressed as an absolute pathname. sb is a pointer to the stat structure returned by a call to stat(2) for fpath.

Аргумент typeflag, передаваемый в fn(), представляет собой целое число, которое может быть одним из следующих значений:

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). Содержимое буфера, указываемого sb, не определено.

FTW_SL

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

FTW_SLN

fpath is a symbolic link pointing to a nonexistent file. (This occurs only if FTW_PHYS is not set.) In this case the sb argument passed to fn() contains information returned by performing lstat(2) on the "dangling" symbolic link. (But see BUGS.)

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

struct FTW {


    int base;


    int level;
};

base — смещение на имя файла (т.е. базовая часть) в пути, заданном в fpath. level — глубина fpath в дереве каталогов относительно корня дерева (dirpath имеет глубину 0).

To stop the tree walk, fn() returns a nonzero value; this value will become the return value of nftw(). As long as fn() returns 0, nftw() will continue either until it has traversed the entire tree, in which case it will return zero, or until it encounters an error (such as a malloc(3) failure), in which case it will return -1.

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

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

FTW_ACTIONRETVAL (начиная с glibc 2.3.3)

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

FTW_CHDIR

Если установлен этот флаг, то будет выполняться chdir(2) для каждого каталога перед обработкой его содержимого. Это полезно, если программе требуется выполнить какое-то действие в каталоге, в котором расположен fpath (наличие данного флага не влияет на путь, который передаётся в fpath аргумента fn).

FTW_DEPTH

If set, do a post-order traversal, that is, call fn() for the directory itself after handling the contents of the directory and its subdirectories. (By default, each directory is handled before its contents.)

FTW_MOUNT

Если установлен этот флаг, то оставаться в пределах одной файловой системы (т.е. не переходить в другую точку монтирования).

FTW_PHYS

Если установлен этот флаг, то не следовать по символьным ссылкам (то, что обычно нужно). Если флаг не задан, то выполняется переход по символьным ссылкам, но ни один файл не будет обработан дважды.

Если FTW_PHYS не задан, но задан FTW_DEPTH, то функция fn() никогда не будет вызвана для каталога, который является потомком самого себя.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ¶

При успешном выполнении эти функции возвращают 0 и -1 при ошибке.

If fn() returns nonzero, then the tree walk is terminated and the value returned by fn() is returned as the result of ftw() or nftw().

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

АТРИБУТЫ¶

Описание терминов данного раздела смотрите в attributes(7).

ВЕРСИИ¶

In some implementations (e.g., glibc), ftw() will never use FTW_SL; on other systems FTW_SL occurs only for symbolic links that do not point to an existing file; and again on other systems ftw() will use FTW_SL for each symbolic link. If fpath is a symbolic link and stat(2) failed, POSIX.1-2008 states that it is undefined whether FTW_NS or FTW_SL is passed in typeflag. For predictable results, use nftw().

СТАНДАРТЫ¶

POSIX.1-2008.

ИСТОРИЯ¶

ftw()

POSIX.1-2001, SVr4, SUSv1. POSIX.1-2008 marks it as obsolete.

nftw()

glibc 2.1. POSIX.1-2001, SUSv1.

FTW_SL

POSIX.1-2001, SUSv1.

ПРИМЕЧАНИЯ¶

В POSIX.1-2008 отмечено, что результат непредсказуем, если fn не сохраняет текущий рабочий каталог.

ОШИБКИ¶

According to POSIX.1-2008, when the typeflag argument passed to fn() contains FTW_SLN, the buffer pointed to by sb should contain information about the dangling symbolic link (obtained by calling lstat(2) on the link). Early glibc versions correctly followed the POSIX specification on this point. However, as a result of a regression introduced in glibc 2.4, the contents of the buffer pointed to by sb were undefined when FTW_SLN is passed in typeflag. (More precisely, the contents of the buffer were left unchanged in this case.) This regression was eventually fixed in glibc 2.30, so that the glibc implementation (once more) follows the POSIX specification.

ПРИМЕРЫ¶

Следующая программа обходит дерево каталогов начиная с пути, указанном в первом аргументе командой строки или начиная с текущего каталога, если аргумент не указан. Она отображает различную информацию о каждом файле. Во втором параметре можно указать символы, которые управляют содержимым аргумента flags у nftw().

#define _XOPEN_SOURCE 500
#include <ftw.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.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);
}

СМОТРИТЕ ТАКЖЕ¶

stat(2), fts(3), readdir(3)

ПЕРЕВОД¶

Русский перевод этой страницы руководства разработал(и) Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, Yuri Kozlov <yuray@komyakino.ru>, Иван Павлов <pavia00@gmail.com> и Kirill Rekhov <krekhov.dev@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков.