При обходе дерева каталога функция nftw() открывает по меньшей мере один файловый дескриптор для каждого уровня этого дерева. Аргумент nopenfd задает максимальное количество файловых дескрипторов, которые может использовать функция nftw(). Если глубина каталога превосходит данный максимум, функция nftw() выполняет своего рода учет системных ресурсов, закрывая и заново открывая дескрипторы, чтобы избежать ситуации, при которой одновременно открыто более nopenfd дескрипторов (в результате функция работает медленнее). Необходимость этого аргумента была важна в старых реализациях UNIX; часть из них устанавливали предел — 20 открытых файловых дескрипторов на процесс. Современные реализации UNIX позволяют процессу открывать большое количество дескрипторов, и поэтому можно не скупиться на их количество (указав, скажем, 10 или больше).
Аргумент flags для функции nftw() создается с помощью операции ИЛИ (|), которая применяется к нескольким (или ни к одной) из перечисленных ниже констант, меняющих работу данной функции.
• FTW_CHDIR — выполнить функцию chdir() в каждом каталоге перед обработкой ее содержимого. Это удобно, если функция func предназначена для выполнения некой работы в том каталоге, где расположен файл, указанный в аргументе pathname.
• FTW_DEPTH — выполнить обход в обратном порядке в глубину дерева каталога. Это значит, что функция nftw() вызывает функцию func для всех файлов (и подкаталогов) внутри какого-либо каталога, прежде чем выполнить функцию func для самого каталога. (Название флага немного сбивает с толку: функция nftw() всегда выполняет обход дерева каталога сначала в глубину, а затем в ширину. Все, что делает данный флаг, заключается в изменении порядка обхода с прямого на обратный.)
• FTW_MOUNT — не перемещаться внутрь другой файловой системы. Следовательно, если один из подкаталогов данного дерева является точкой монтирования, его обход не выполняется.
• FTW_PHYS — по умолчанию функция nftw() разыменовывает символические ссылки. Данный флаг запрещает такое поведение. Вместо этого ссылка передается функции func со значением FTW_SL для аргумента typeflag, как описано ниже.
Для каждого файла функция nftw() передает четыре аргумента при вызове функции func. Первый из них, pathname, является именем пути к данному файлу. Это имя может быть абсолютным, если аргумент dirpath был указан как абсолютное имя пути, или относительным по отношению к текущему рабочему каталогу вызывающего процесса на момент вызова функции ntfw(), если аргумент dirpath выражен относительным именем пути. Второй аргумент, statbuf, является указателем на структуру stat (см. раздел 15.1), содержащую информацию о данном файле. Третий аргумент, typeflag, содержит дополнительную информацию о файле и имеет одно из следующих значений:
• FTW_D — каталог;
• FTW_DNR — каталог, который нельзя прочитать (и поэтому функция nftw() не обходит его каталоги-потомки);
• FTW_DP — мы выполняем обход каталога в обратном порядке (FTW_DEPTH), и текущий элемент является каталогом, файлы и подкаталоги которого уже были обработаны;
• FTW_F — файл любого типа, кроме каталога или символической ссылки;
• FTW_NS — вызов stat() для данного файла завершился ошибкой, вероятно, вследствие ограниченных прав доступа. Значение statbuf не определено;
• FTW_SL — символическая ссылка. Данное значение возвращается, только если функция nftw() вызвана с флагом FTW_PHYS;
• FTW_SLN — этот элемент является зависшей символической ссылкой. Данное значение появляется, только если не был указан флаг FTW_PHYS в качестве аргумента flags.
Четвертый аргумент функции func, ftwbuf, является указателем на структуру, определяемую следующим образом:
struct FTW {
int base; /* Смещение относительно базовой части имени пути */
int level; /* Глубина файла внутри обхода дерева */
};
Поле base данной структуры является целочисленным смещением компонента с именем файла (компонент, следующий за последним слешем) в аргументе pathname функции func. Поле level является глубиной этого элемента относительно начальной точки обхода (для которой уровень равен 0).
При каждом вызове функция func должна возвращать целочисленное значение, которое интерпретируется функцией nftw(). Если возвращен 0, то функция nftw() продолжает обход дерева, и если все вызовы функции func возвращают 0, то и сама nftw() возвращает 0 вызывающему процессу. Если возвращено ненулевое значение, то функция nftw() немедленно прекращает обход дерева и возвращает упомянутое ненулевое значение.
Поскольку функция nftw() задействует динамически выделяемые структуры данных, единственный способ, с помощью которого программа может преждевременно прервать обход дерева, заключается в возврате ненулевого значения функцией func. Использование функции longjmp() (см. раздел 6.8) может привести к непредсказуемым результатам — по меньшей мере к утечке памяти в программе.
Листинг 18.3 демонстрирует применение функции nftw().
