| FTS(3) | Руководство программиста Linux | FTS(3) |
fts, fts_open, fts_read, fts_children, fts_set, fts_close - обход файловой иерархии
#include <sys/types.h> #include <sys/stat.h> #include <fts.h>
FTS *fts_open(char * const *path_argv, int options,
int (*compar)(const FTSENT **, const FTSENT **));
FTSENT *fts_read(FTS *ftsp);
FTSENT *fts_children(FTS *ftsp, int instr);
int fts_set(FTS *ftsp, FTSENT *f, int instr);
int fts_close(FTS *ftsp);
Функции fts созданы для обхода файловой иерархии. Обзорное описание: функция fts_open() возвращает «описатель» (с типом FTS *), который указывает на «поток» файловой иерархии. Далее он используется другими функциями fts. Функция fts_read() возвращает указатель на структуру, описывающую один из файлов в файловой иерархии. Функция fts_children() возвращает указатель на связанный список структур, каждая из которых описывает один из файлов, содержащихся в каталоге иерархии.
В общем случае, каталоги обходятся двумя разными путями — в прямом порядке (перед тем, как обработаны их потомки) и в обратном порядке (после того, как обработаны все потомки). Файлы обрабатываются только один раз. Возможен «логический» обход иерархии (обрабатываются файлы, на которые указывают символьные ссылки) и «физический» (обрабатываются сами символьные ссылки), то есть обход иерархии сократится или какая-то часть будет пройдена повторно.
В файле <fts.h> определены две структуры (связанные с ними типы). Первая — структура FTS, представляющая саму иерархию файлов. Вторая — структура FTSENT, представляющая файл в иерархии файлов. Обычно, структура FTSENT возвращается для каждого файла в файловой иерархии. В этой справочной странице понятия «файл» и «структура FTSENT» взаимозаменяемы.
Структура FTSENT содержит поля, описывающие файл. На имеет, по меньшей мере, следующие поля (есть и дополнительные поля, но для реализации они должны считаться скрытыми):
typedef struct _ftsent {
unsigned short fts_info; /* флаги для структуры FTSENT */
char *fts_accpath; /* путь доступа */
char *fts_path; /* начальный путь */
short fts_pathlen; /* strlen(fts_path) +
strlen(fts_name) */
char *fts_name; /* имя файла */
short fts_namelen; /* strlen(fts_name) */
short fts_level; /* глубина (от -1 до N) */
int fts_errno; /* файловый errno */
long fts_number; /* локальное числовое значение */
void *fts_pointer; /* локальное значение адреса */
struct _ftsent *fts_parent; /* родительский каталог */
struct _ftsent *fts_link; /* структура следующего файла */
struct _ftsent *fts_cycle; /* циклическая структура */
struct stat *fts_statp; /* информация stat(2) */
} FTSENT;
Эти поля определены следующим образом:
Для всех путей всех файлов в иерархии используется единый буфер. Следовательно, поля fts_path и fts_accpath гарантировано завершаются null только для файла, который был возвращён fts_read() последним. Для использования этих полей для обращения к любым файлам, представленным другими структурами FTSENT необходимо, чтобы буфер пути был изменён в соответствии с информацией, содержащейся в поле fts_pathlen структуры FTSENT. Любое изменение должно быть обратно восстановлено перед дальнейшими попытками вызова fts_read(). Поле fts_name всегда завершается null.
Функция fts_open() ожидает указатель на массив символьных указателей, обозначающих один или несколько путей, образующих логическую файловую иерархию, по которой будет проводиться обход. Массив должен заканчиваться указателем null.
Есть несколько флагов, должен быть указан хотя бы один (либо FTS_LOGICAL, либо FTS_PHYSICAL). Флаги, выбираемые с помощью логического объединения, имеют следующие значения:
В параметре compar() указывается определяемая пользователем функция, которая может использоваться для упорядочивания обхода иерархии. В качестве параметров ей требуется два указателя на указатели на структуры FTSENT, и она должна возвращать отрицательное значение, ноль или положительное значение для того, чтобы показать, расположен ли файл, на который указывает первый параметр, перед (относительно текущего упорядочивания), на одном уровне или после файла, на который указывает второй параметр. Поля fts_accpath, fts_path и fts_pathlen структур FTSENT могут быть никогда не использованы при таком сравнении. Если значение поля fts_info равно FTS_NS или FTS_NSOK, то поле fts_statp может не использоваться. Если значение параметра compar() равно NULL, то порядок обхода каталогов определяется параметрами, указанными в path_argv для корневых путей, и в порядке, перечисленном в каталоге, для всего остального.
Функция fts_read() возвращает указатель на структуру FTSENT, описывающую файл в иерархии. Каталоги (корректно считанные и не образующие зацикливаний), посещаются как минимум дважды — первый раз в прямом прохождении и второй раз в обратном. Все остальные файлы посещаются минимум один раз (жёсткие ссылки между каталогами, не образующие зацикливаний, или символьные ссылки на символьные ссылки могут привести к тому, что файлы будут посещаться более одного раза, а каталоги более двух раз).
Когда все члены иерархии возвращены, fts_read() возвращает NULL и устанавливает внешнюю переменную errno равной 0. Если происходит ошибка, не имеющая отношения к файлу в иерархии, fts_read() возвращает NULL и устанавливает errno в соответствующее значение. Если происходит ошибка, связанная с возвращённым файлом, то возвращается указатель на структуру FTSENT, а errno может быть установлена в какое-то значение (а может и не быть, смотрите fts_info).
Структуры FTSENT, возвращаемые fts_read(), могут быть перезаписаны после вызова fts_close() в том же файловом потоке иерархии или после вызова fts_read() в том же файловом потоке иерархии, если они не представляют файл типа «каталог»; в этом случае они не будут перезаписаны до тех пор, пока функция fts_read() не вернёт структуру FTSENT при выполнении обхода в обратном порядке.
Функция fts_children() возвращает указатель на структуру FTSENT, описывающую первый член связанного списка (оканчивающегося NULL) файлов в каталоге, представленного структурой FTSENT, возвращённой fts_read() последней. Список связан через поле fts_link структуры FTSENT, и упорядочен определённой пользователем функцией сравнения, если таковая существует. Повторные вызовы fts_children() будут пересоздавать этот связанный список.
В особом случае, если fts_read() ещё не вызывалась для иерархии, то fts_children() возвратит указатель на файлы в логическом каталоге, заданном fts_open(), т.е. параметры, переданные функции fts_open(). В противном случае, если последняя возвращённая fts_read() структура FTSENT не является каталогом, просмотренном в прямом порядке, и не каталогом файлов, то fts_children() возвратит NULL и установит errno равным 0. Если произойдёт ошибка, то fts_children() возвратит NULL и установит errno в соответствующее значение.
Структура FTSENT, возвращаемая fts_children(), может быть перезаписана после вызова fts_children(), fts_close() или fts_read() в том же файловом потоке иерархии.
Параметр instr может принимать значение нуля или одного из следующих значений:
Функция fts_set() позволяет пользовательскому приложению определять дальнейшую обработку файла f в потоке ftsp. При успешном выполнении функция fts_set() возвращает 0 и -1 при ошибке.
Значением аргумента instr может быть 0 («ничего не делать») или одно из следующих значений:
Функция fts_close() закрывает поток файловой иерархии, на который указывает ftsp, и делает текущим каталогом тот, который был до вызова fts_open() для открытия ftsp. При успешном выполнении функция fts_close() возвращает 0 и -1 при ошибке.
Функция fts_open() может завершиться с ошибкой и назначить переменной errno значения, перечисленные в open(2) и malloc(3).
Функция fts_close() может завершиться с ошибкой и назначить переменной errno значения, перечисленные в chdir(2) и close(2).
Функции fts_read() и fts_children() могут завершиться с ошибкой и назначить переменной errno значения, перечисленные в chdir(2), malloc(3), opendir(3), readdir(3) и stat(2).
Кроме того, функции fts_children(), fts_open() и fts_set() могут завершиться с ошибкой и назначить переменной errno следующие значения:
Эти функции доступны в версиях Linux начиная с glibc2.
Описание терминов данного раздела смотрите в attributes(7).
| Интерфейс | Атрибут | Значение |
| fts_open(), fts_set(), fts_close() | Безвредность в нитях | MT-Safe |
| fts_read(), fts_children() | Безвредность в нитях | MT-Unsafe |
4.4BSD.
В версиях glibc до 2.23 весь описанный здесь программный интерфейс небезопасен, если компиляция программы производится с программным интерфейсом LFS (например, когда компиляция выполняется с -D_FILE_OFFSET_BITS=64).
| 2018-02-02 | Linux |