[ новости /+++ | форум | теги | ]

НАЗВАНИЕ

СИНТАКСИС

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 options);

int
fts_set (FTS *ftsp FTSENT *f int options);

int
fts_close (FTS *ftsp);
 

ОПИСАНИЕ

Определены две структуры (типа typedef) в include-файле Aq Pa fts.h . Первая - структура Fa FTS , представляющая собственно иерархию файлов. Вторая - структура Fa FTSENT , представляющая иерархию файлов в файлах. Обычно, стуктура Fa FTSENT возвращается для каждого файла в файловой иерархии. В этом руководстве понятия "файл" и "структура FTSENT" в общем взаимозаменяемы. Структура Fa FTSENT содержит по меньшей мере следующие поля, подробнее описанные ниже:

typedef struct _ftsent {
        u_short fts_info;               /* флаги для структуры FTSENT */
        char *fts_accpath;              /* путь доступа */
        char *fts_path;                 /* начальный путь */
        short fts_pathlen;              /* strlen(fts_path) */
        char *fts_name;                 /* имя файла */
        short fts_namelen;              /* strlen(fts_name) */
        short fts_level;                /* глубина (от -1 до N) */
        int fts_errno;                  /* номер ошибки в файле (file 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;

Эти поля определяются таким образом:

Fa fts_info

Один из последующих флагов описывает возвращенное значение стурктуры Fa FTSENT и файла, который ею характеризуется. За исключением каталогов, в которых нет ошибок (FTS_D ) все эти элементы являются терминалом, то есть они не будут повторно обходиться, а их потомки не будут обходиться вообще.

FTS_D

Каталог, посещаемый в прямом порядке.

FTS_DC

Каталог, вызвавший зацикливание по дереву. (Поле Fa fts_cycle структуры Fa FTSENT будет заполнено.)

FTS_DEFAULT

Любая структура Fa FTSENT , представляющая тип файла, неявно описанного одним из значений Fa fts_info .

FTS_DNR

Каталог, который не может быть прочитан. Это значение возвращается при ошибке, и поле Fa fts_errno будет заполнено тем, что вызвало ошибку.

FTS_DOT

Файл, названный `.' или `..' который не был определен как файловое имя в fts_open ();
(см. FTS_SEEDOT )

FTS_DP

Каталог, посещаемый в обратном порядке. Содержимое структуры Fa FTSENT будет неизменно, как если-бы он посещался в прямом порядке, то есть с полем Fa fts_info , установленным в FTS_D

FTS_ERR

Это значение возвращается при ошибке, и поле Fa fts_errno будет заполнено тем, что вызвало ошибку.

FTS_F

Простой файл.

FTS_NS

Файл, для которого нет доступной информации stat(2). Содержимое поля Fa fts_statp не определено. Это значение возвращается при ошибке, и поле Fa fts_errno будет заполнено тем, что вызвало ошибку.

FTS_NSOK

Файл, для которого информация о stat(2) не была запрошена. Содержимое поля Fa fts_statp не определено.

FTS_SL

Символьная ссылка.

FTS_SLNONE

Символьная ссылка, указывающая на несуществующий объект. Содержимое поля Fa fts_statp определяет ссылку на информацию о свойствах файла для самой символьной ссылки.

Fa fts_accpath

Путь к файлу относительно текущего каталога.

Fa fts_path

Путь к файлу относительно начального каталога. Этот путь содержит в себе (как приставку) путь, определенный в fts_open (.);

Fa fts_pathlen

Длина строки, на которую ссылается Fa fts_path .

Fa fts_name

Имя файла.

Fa fts_namelen

Длина строки, на которую ссылается Fa fts_name .

Fa fts_level

Глубина погружения в дерево иерархии, пронумерованная от -1 до N, на которой был обнаружен файл. Структура Fa FTSENT , представляющая родительский каталог относительно начальной точки поиска, обозначена как -1, а структура Fa FTSENT для самой начальной точки поиска обозначена как 0.

Fa fts_errno

До возврата структуры Fa FTSENT от функций fts_children ();
или fts_read (, );
с его полем Fa fts_info , установленным в FTS_DNR FTS_ERR или FTS_NS поле Fa fts_errno содержит значение внешней переменной errno , обозначающей причину ошибки. В другом случае, содержание поля Fa fts_errno не определено.

Fa fts_number

Это поле создано для использования приложениями и не модифицируется функциями fts При инициализации оно устанавливается в 0.

Fa fts_pointer

Это поле создано для использования приложениями и не модифицируется функциями fts При инициализации оно устанавливается в NULL

Fa fts_parent

Указатель на структуру Fa FTSENT , обращающейся в иерархии к файлу непосредственно над текущим файлом, то есть к каталогу, членом которого является текущий файл. Родительский каталог начальной точки поиска также может быть доступен, правда только при условии, что поля Fa fts_level , Fa fts_number и Fa fts_pointer будут проинициализированы.

Fa fts_link

До возврата от функции fts_children (, );
поле Fa fts_link указывает на следующую структуру в связанном списке содержимого каталога (заканчивавающихся NULL). Иначе, содержимое поля Fa fts_link не определено.

Fa fts_cycle

Если каталог вызывает зацикливание по иерархии (смотри FTS_DC ), либо из-за жесткой связи между двумя каталогами, либо символьной сслыкой, указывающей на каталог, то поле Fa fts_cycle структуры будет указывать на структуру Fa FTSENT в иерархии, которая ссылается на такой-же файл, что и текущая структура Fa FTSENT . Иначе, содержимое поля Fa fts_cycle не определено.

Fa fts_statp

Указатель на stat(2), информацию о файле.

Единственный буфер, используемый для всех путей всех файлов в иерархии. Следовательно, поля Fa fts_path и Fa fts_accpath должны быть NULL -terminated только для файлов, к которым чаще всего обращается fts_read (.);
Для использования этих полей для обращения к любым файлам, представленных другими структурами Fa FTSENT необходимо, чтобы буфер пути был изменен, используя информацию, содержащуюся в поле Fa fts_pathlen структуры Fa FTSENT . Любое изменение должно быть обратно восстановлено перед дальнейшими попытками вызыва fts_read (.);
Поле Fa fts_name всегда NULL -terminated.  

FTS_OPEN

Из нескольких существующих параметров хотя-бы один (либо FTS_LOGICAL либо FTS_PHYSICAL должен быть указан. С помощью or параметрам присваиваются значения:

FTS_COMFOLLOW

Этот параметр принуждает перемещаться по любой символьной ссылке, определенной как корневой путь, несмотря на то, определен или нет флаг FTS_LOGICAL

FTS_LOGICAL

Этот параметр принуждает функции fts выдавать структуру Fa FTSENT для целей символьной ссылки вместо самой символьной ссылки. Если этот флаг включен, то единственные символьные ссылки, для которых приложениям выдаются структуры Fa FTSENT - это ссылки, указывающие на несуществуюшие файлы. Также FTS_LOGICAL или FTS_PHYSICAL должны присутствовать для работы функции fts_open (.);

FTS_NOCHDIR

Для оптимизации работы функции fts меняют каталоги, по которым они следуют по файловой иерархии. Это имеет один побочный эффект - приложения не могут точно определять, что они находятся в одном каталоге во время перемещения по дереву. Флаг FTS_NOCHDIR выключает такую оптимизацию, и функции fts не будут при нем менять текущий каталог. Обратите внимание, что приложения сами не должны изменять свой текущий каталог и пытаться получить доступ к файлам, пока не указан флаг FTS_NOCHDIR и функции fts_open ();
не переданы абсолютные пути в качестве параметров.

FTS_NOSTAT

По умолчанию, возвращаемые структуры Fa FTSENT обращаются к информации о файлах (поле Fa statp ) в каждом просмотренном файле. Данный параметр снимает это требование (для оптимизации процесса), позволяя функциям fts установить поле Fa fts_info в значение FTS_NSOK и оставлять содержание поля Fa statp неопределенным.

FTS_PHYSICAL

Этот параметр принуждает функции fts выдавать структуру Fa FTSENT самих символьных ссылкок вместо файлов, на которые они указывают. Если этот флаг установлен, то для всех символьных ссылок в файловой иерархии их структуры Fa FTSENT возвращаются приложениям. Также FTS_LOGICAL или FTS_PHYSICAL должны присутствовать для работы функции fts_open (.);

FTS_SEEDOT

По умолчанию, до тех пор, пока не указаны как параметры пути к fts_open (,);
любые файлы с именами `.' или `..' , обнаруженные в файловой иерархии, игнорируются. Данный флаг принуждает фукнции fts возвращать структуры Fa FTSENT для таких файлов.

FTS_XDEV

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

Параметр compar ();
задает определяемую пользователем функцию, которая используется для упорядочивания прохождения по иерархии. Ему требуется два указателя на указатели к структурам Fa FTSENT как параметры, и он должен возвращать отрицательное значение, ноль, или положительное число для того, чтобы показать, расположен ли файл, на который указывает первый параметр, перед (относительно текущего упорядочивания), на одном уровне, или после файла, на который указывает второй параметр. Поля Fa fts_accpath , Fa fts_path и Fa fts_pathlen структуры Fa FTSENT могут быть никогда не использованы в таком сравнении. Если поле Fa fts_info установлено в FTS_NS или FTS_NSOK то поле Fa fts_statp может не использоваться. Если параметр compar ();
установлен в NULL то порядок прохождения каталогов определяется параметрами, указанными в Fa path_argv для корневого пути, и в порядке, перечисленном в каталоге для всего остального.  

FTS_READ

Когда все члены иерархии возвращены, fts_read ();
возвращает NULL и устанавливает внешнюю переменную errno в 0. Если происходит ошибка, не имеющая отношения к файлу в иерархии, fts_read ();
возвращает NULL и устанавливает соответсвенно errno в некоторое значение. Если происходит ошибка, связанная с возвращенным файлом, то возвращается указатель на структуру Fa FTSENT , а errno может быть установлен в какое-то значение, а может и не быть (см. Fa fts_info ) .

Структура Fa FTSENT , возвращаемая fts_read ();
может быть переписана после вызова fts_close ();
в том же файловом потоке иерархии, или, после вызова fts_read ();
в том же файловом потоке иерархии, пока они не представляют файл типа "каталог", в этом случае они не будут переписаны до вызова fts_read ();
после того, как структура Fa FTSENT будет возвращена функцией fts_read ();
в прямом порядке.  

FTS_CHILDREN

В особом случае, если fts_read ();
еще не вызывалась для иерархии, то fts_children ();
возвратит указатель на файлы в логическом каталоге, что соответствует fts_open (,);
т.е. параметры, переданные функции fts_open (.);
Иначе, если структура Fa FTSENT , слишком часто возвращаемая функцией fts_read ();
не каталог, посещаемый в прямом порядке, и не пустой каталог (не содержащий файлов), то fts_children ();
возвратит NULL и установит errno в ноль. Если произойдет сбой, то fts_children ();
возвратит NULL и соответственно установит errno в нужное значение.

Структура Fa FTSENT , возвращаемая fts_children (, );
может быть переписана после вызова fts_children (,);
fts_close ();
или fts_read ();
в том же файловом потоке иерархии.

Параметр должен быть установлен в следующих значений:

FTS_NAMEONLY

Тут необходимы только имена файлов. Содержимое всех полей в возвращаемом связанном списке структур неопределено, за исключением полей Fa fts_name и Fa fts_namelen .

FTS_SET

FTS_AGAIN

Повторно посетить файл; файл любого типа может быть повторно посещен. Последующий вызов fts_read ();
возвратит файл, к которому идет обращение. Поля Fa fts_stat и Fa fts_info структуры будут переинициализированы в этот момент, но никакие поля больше не должны будут меняться. Эта опция значима только для наиболее часто возвращаемых файлов от fts_read (.);
Обычно используют ее для посещения каталогов в обратном порядке, тогда она принуждает повторно посетить каталог (в прямом и обратном порядке), а также все его потомки.

FTS_FOLLOW

Ссылочный файл должен быть символьной ссылкой. Если ссылочный файл - один из наиболее часто возвращаемых fts_read (,);
то следующий вызов fts_read ();
возвратит файл с полями Fa fts_info и Fa fts_statp , повторно инициализированными, для показа цели символьной ссылки вместо самой символьной ссылки. Если ссылочный файл - один из наиболее часто возвращаемых fts_children (,);
то поля Fa fts_info и Fa fts_statp структуры, при возврате от fts_read (,);
будут показывать цель символьной ссылки вместо самой символьной ссылки. В любом случае, если цель символьной ссылки не существует, то поля возвращаемой структуры не будут меняться, а поле Fa fts_info будет установлено в FTS_SLNONE

Если цель ссылки - каталог, то возврат прямого прохождения, сопровождаемый возвратом всех его потомков, сопровождаемый возвратом в обратном порядке, закончен.

FTS_SKIP

Никакие потомки данного файла не посещены. Файл может быть одним из наиболее часто возвращаемых либо структурой fts_children ();
либо fts_read (.);

FTS_CLOSE

СООБЩЕНИЕ ОБ ОШИБКАХ

В случае неудачного завершения функции 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 будет установлена в одно из следующих значений:

Bq Er EINVAL

Параметры были неправильными.

СМ. ТАКЖЕ

СООТВЕТСТВИЕ СТАНДАРТАМ

ДОСТУПНОСТЬ

Index

НАЗВАНИЕ

СИНТАКСИС

ОПИСАНИЕ

FTS_OPEN

FTS_READ

FTS_CHILDREN

FTS_SET

FTS_CLOSE

СООБЩЕНИЕ ОБ ОШИБКАХ

СМ. ТАКЖЕ

СООТВЕТСТВИЕ СТАНДАРТАМ

ДОСТУПНОСТЬ

Партнёры:

Хостинг: