ftw(), ftw64()

Переместиться по дереву каталогов

Прототип:

#include <ftw.h>
                                       
int ftw( const char *path, 
         int (*fn)( const char *fname,
                    const struct stat *sbuf,
                    int flags ),
         int depth );

Аргументы:

path

Путь к директории, чье файловое дерево необходимо обойти.

fn

Указатель на функцию, которую нужно вызвать для каждого файла.

depth

Максимальное количество файловых дескрипторов, которые tw() может использовать. Функция ftw() использует один файловый дескриптор для каждого уровня дерева. Если depth равна нулю или отрицательна, это аналогично тому, если бы она была бы равна 1. depth не должна превышать количество файловых дескрипторов, доступных в данный момент для использования. Функция ftw() работает быстрее, если depth как минимум равна высоте дерева.

Библиотека:

libc

Описание:

Функция ftw() рекурсивно спускается по иерархии директорий, определяемой path. Для каждого объекта в иерархии ftw() вызывает определяемую пользователем функцию fn(), передавая туда:

• указатель на завершаемую NULL строку, содержащую имя объекта
• указатель на структуру struct stat, содержащую информацию об объекте
• целочисленное значение. Возможные значения определены в заголовочном файле <ftw.h>:

  FTW_F

  Объект является файлом.

  FTW_D

  Объект является директорией.

  FTW_DNR

  Объект является директорией, недоступной для чтения. Внутренние директории не обрабатываются.

  FTW_NS

  Ошибка в stat() для объекта вследствие отустствия необходимых прав доступа, или объект представляет собой символическую ссылку на несуществующий файл. Объект stat(), передающийся в fn(), не определен.

Функция ftw() обрабатывает директорию перед обработкой всех ее внутренних директорий.

Обход дерева продолжается до тех пор, пока дерево не закончится, вызов fn() вернет ненулевое значение или какая-либо ошибка не возникнет внутри ftw() (например, ошибка ввода/вывода). Если дерево закончилось, ftw() вернет нулевое значение. Если fn() вернет ненулевое значение, ftw() останавливает обход дерева и возвращает значение, которое вернула fn().

Когда ftw() завершается, она закрываает все файловые дескрипторы, которые открыла; она не закрывает файловые дескрипторы, которые могли быть открыты fn().

Возвращаемое значение:

0

Успешное завершение.

-1

Возникла ошибка (отличная от EACCESS). Код ошибки записан в errno.

Классификация:

ftw() — POSIX 1003.1 X/Open Systems Interfaces Extension; ftw64() — Поддержка больших файлов

Безопасность использования

Точка остановки потока

Да

Обработчик прерываний

Нет

Обработчик сигналов

Да

В потоке

Да

Предостережения:

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

Данная функция использует malloc() для выделения динамического хранилища во время своих операций. Если ftw() принудительно завершается, например, из-за выполнения longjmp() в fn() или функции прерывания, ftw() не имеет возможности освободить выделенную память, поэтому она остается выделенной. Безопасный вариант обработки прерываний - сохранить факт, что прерывание произошло, и вренуть из fn() ненулевое значение при следующем вызове.

Тематические ссылки:

struct stat, longjmp(), malloc(), nftw(), stat()

Предыдущий раздел: Описание API системной библиотеки