ftw, nftw - команды перемещения по дереву каталогов

НАЗВАНИЕ
ftw, nftw - команды перемещения по дереву каталогов

СИНТАКСИС
#include

int ftw(const char *dir, int (*fn)(const char *file, const
struct stat *sb, int flag), int depth);

int nftw(const char *dir, int (*fn)(const char *file,
const struct stat *sb, int flag, struct FTW *s), int
depth, int flags);

ОПИСАНИЕ
ftw() перемещается по дереву каталогов, начиная с
указанного каталога dir. Для каждого найденного элемента
дерева вызываются: fn() с указанием полного имени этого
элемента, указатель на структуру элемента stat(2) и целое
число. Значения этого целого числа flag могут быть одним
из следующих:

FTW_F (обычный файл);

FTW_D (каталог);

FTW_DNR
(каталог, который не может быть считан);

FTW_SL (символьная ссылка);

FTW_NS (ошибка в элементе, который не является символьной
ссылкой).

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

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

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

Так как ftw() использует динамическую структуру данных, то
единственным безопасным способом для выхода из процесса
перемещения по дереву будет возврат ненулевого значения.
Для обработки прерываний, например, необходимо отметить,
что прерывание действительно произошло, и вернуть
ненулевое значение. Не следует использовать функцию
longjmp(3) до тех пор, пока программа не будет
завершаться. Функция nftw() выполняет то же самое, что и
ftw(), только имеет еще один параметр, flags, то есть
вызывает свои функции еще с одним параметром. Этот
параметр flags есть 0 или логическое ИЛИ нескольких
следующих параметров:

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

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

FTW_MOUNT
Если установлен этот флаг, то работать только в
одной файловой системе.

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

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

Функция fn() вызывается с четырьмя параметрами: а) полным
путем к элементу, б) указателем на структуру struct stat
этого элемента, в) целым, описывающим его тип, и д)
указателем на структуру struct FTW. Тип будет одним из
следующих: FTW_F, FTW_D, FTW_DNR, FTW_SL, FTW_NS (если
значение его равно описанному выше, то FTW_SL будет
работать только с указанным флагом FTW_PHYS) или

FTW_DP (элемент является каталогом, и все его потомки уже
были обработаны). Это случается, только если флаг
FTW_DEPTH запущен.

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

Структура struct FTW, на которую указывает четвертый
аргумент в fn(), имеет, по меньшей мере, поля: base -
смещение на имя файла в полном его имени, заданное в
первом параметре fn(); а также level (это глубина элемента
относительно начальной точки с глубиной 0).

ЗАМЕЧАНИЯ
Функция nftw() и использование FTW_SL с ftw() были описаны
в XPG4v2.

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

В Linux libc4, libc5 и glibc 2.0.6 будут использовать
FTW_F для работы всех объектов (файлов, символьных ссылок,
каналов и т.п.), которые могут иметь определенный статус,
но не являются директориями. Функция nftw() появилась
начиная с glibc 2.1.

СООТВЕТСТВИЕ СТАНДАРТАМ
AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2.