nftw(), nftw64()

Обойти файловое дерево

Прототип:

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

Аргументы:

path

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

fn

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

depth

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

flags

Значение flags собирается с помощью побитового ИЛИ из значений из следующего списка, определенных в заголовочном файле <ftw.h>.

FTW_CHDIR

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

FTW_DEPTH

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

FTW_MOUNT

Если установлен, nftw() обходит файлы только в файловой системе, определяемой path.

FTW_PHYS

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

Библиотека:

libc

Описание:

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

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

  FTW_F

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

  FTW_D

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

  FTW_DNR

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

  FTW_DP

  Объект является директорией, все его потомки уже обработаны. Смотрите флаг FTW_DEPTH выше.

  FTW_NS

  Структура stat() некорректна из-за несоответствующих прав доступа. Содержимое буфера stat(), передаваемого в fn(), не определено.

  FTW_SL

  Объект является символической ссылкой. Смотрите флаг FTW_PHYS выше.

  FTW_SLN

  Объект является символической ссылкой, которая указывает на несуществующий файл.

• указатель на структуру struct FTW.

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

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

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

0

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

-1

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

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

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

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

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

Да

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

Нет

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

Да

В потоке

Да

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

Из-за того, что функция nftw() рекурсивна, она может завершиться с ошибкой памяти при достаточно глубокой файловой структуре дерева.

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

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

struct stat, struct FTW, ftw(), longjmp(), malloc(), stat()

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