FTW(3C)

НАЗВАНИЕ
ftw - обход дерева файлов

СИНТАКСИС

	#include <ftw.h>

	

	int ftw (path, fn, depth)

	char *path;

	int (*fn) ( );

	int depth;

ОПИСАНИЕ
Функция ftw рекурсивно обходит иерархию каталогов, имеющую своим корнем каталог с маршрутным именем, на которое указывает аргумент path. Для каждого объекта иерархии ftw вызывает функцию fn, передавая ей три аргумента: указатель на цепочку символов, ограниченную нулевым байтом и содержащую имя объекта; указатель на структуру stat [см. stat(2)], содержащую информацию об объекте; тип объекта (целое число). Возможны следующие значения типа объекта, описанные во включаемом файле :

FTW_F	Обычный файл.
FTW_D	Каталог.
FTW_DNR	Каталог, недоступный на чтение.
FTW_NS	объект, для которого stat не может выполниться успешно.

Если тип объекта есть FTW_DNR, подкаталоги этого каталога не просматриваются. Если тип есть FTW_NS, то структура stat будет содержать мусор. Примером объекта, который вызовет передачу fn типа FTW_NS, является файл в каталоге, доступном на чтение, но недоступном для поиска.

Функция ftw обрабатывает каталог перед обработкой его элементов.

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

Функция ftw использует по одному дескриптору файла на каждый уровень дерева. Аргумент depth ограничивает количество используемых таким образом дескрипторов. Если он не больше нуля, то используется один дескриптор. Значение аргумента depth не должно быть больше, чем количество доступных для использования дескрипторов. Функция ftw будет работать быстрее, если значение depth не меньше глубины дерева.

СМ. ТАКЖЕ
stat(2), malloc(3C).

СЮРПРИЗЫ
Так как функция ftw рекурсивна, возможно аварийное завершение работы из-за выхода за границы памяти при обходе слишком глубокой файловой структуры.

ОГРАНИЧЕНИЯ
Функция ftw использует для динамического выделения памяти malloc(3C). Если ftw завершена насильственно, например, при выполнении из fn вызова longjmp или по прерыванию, то она не имеет возможности освободить память, так что выделенная память останется занятой. Безопасный способ обработки прерываний заключается в том, чтобы зафиксировать факт получения прерывания и при ближайшем вызове fn заставить ее вернуть ненулевое значение.