.\" -*- coding: UTF-8 -*- '\" t .\" $NetBSD: fts.3,v 1.13.2.1 1997/11/14 02:09:32 mrg Exp $ .\" .\" Copyright (c) 1989, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" SPDX-License-Identifier: BSD-4-Clause-UC .\" .\" @(#)fts.3 8.5 (Berkeley) 4/16/94 .\" .\" 2007-12-08, mtk, Converted from mdoc to man macros .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH fts 3 "20 июля 2023 г." "Linux man\-pages 6.05.01" .SH ИМЯ fts, fts_open, fts_read, fts_children, fts_set, fts_close \- обход файловой иерархии .SH LIBRARY Standard C library (\fIlibc\fP, \fI\-lc\fP) .SH СИНТАКСИС .nf \fB#include \fP \fB#include \fP \fB#include \fP .PP \fBFTS *fts_open(char *const *\fP\fIpath_argv\fP\fB, int \fP\fIoptions\fP\fB,\fP \fB int (*_Nullable \fP\fIcompar\fP\fB)(const FTSENT **, const FTSENT **));\fP .PP \fBFTSENT *fts_read(FTS *\fP\fIftsp\fP\fB);\fP .PP \fBFTSENT *fts_children(FTS *\fP\fIftsp\fP\fB, int \fP\fIinstr\fP\fB);\fP .PP \fBint fts_set(FTS *\fP\fIftsp\fP\fB, FTSENT *\fP\fIf\fP\fB, int \fP\fIinstr\fP\fB);\fP .PP \fBint fts_close(FTS *\fP\fIftsp\fP\fB);\fP .fi .SH ОПИСАНИЕ Функции fts созданы для обхода файловой иерархии. Обзорное описание: функция \fBfts_open\fP() возвращает «описатель» (с типом \fIFTS\ *\fP), который указывает на «поток» файловой иерархии. Далее он используется другими функциями fts. Функция \fBfts_read\fP() возвращает указатель на структуру, описывающую один из файлов в файловой иерархии. Функция \fBfts_children\fP() возвращает указатель на связанный список структур, каждая из которых описывает один из файлов, содержащихся в каталоге иерархии. .PP В общем случае, каталоги обходятся двумя разными путями — в прямом порядке (перед тем, как обработаны их потомки) и в обратном порядке (после того, как обработаны все потомки). Файлы обрабатываются только один раз. Возможен «логический» обход иерархии (обрабатываются файлы, на которые указывают символьные ссылки) и «физический» (обрабатываются сами символьные ссылки), то есть обход иерархии сократится или какая\-то часть будет пройдена повторно. .PP В файле \fI\fP определены две структуры (связанные с ними типы). Первая — структура \fIFTS\fP, представляющая саму иерархию файлов. Вторая — структура \fIFTSENT\fP, представляющая файл в иерархии файлов. Обычно, структура \fIFTSENT\fP возвращается для каждого файла в файловой иерархии. В этой справочной странице понятия «файл» и «структура FTSENT» взаимозаменяемы. .PP Структура \fIFTSENT\fP содержит поля, описывающие файл. На имеет, по меньшей мере, следующие поля (есть и дополнительные поля, но для реализации они должны считаться скрытыми): .PP .in +4n .EX .\" Also: .\" ino_t fts_ino; /* inode (only for directories)*/ .\" dev_t fts_dev; /* device (only for directories)*/ .\" nlink_t fts_nlink; /* link count (only for directories)*/ .\" u_short fts_flags; /* private flags for FTSENT structure */ .\" u_short fts_instr; /* fts_set() instructions */ typedef struct _ftsent { unsigned short fts_info; /* flags for FTSENT structure */ char *fts_accpath; /* access path */ char *fts_path; /* root path */ short fts_pathlen; /* strlen(fts_path) + strlen(fts_name) */ char *fts_name; /* filename */ short fts_namelen; /* strlen(fts_name) */ short fts_level; /* depth (\-1 to N) */ int fts_errno; /* file errno */ long fts_number; /* local numeric value */ void *fts_pointer; /* local address value */ struct _ftsent *fts_parent; /* parent directory */ struct _ftsent *fts_link; /* next file structure */ struct _ftsent *fts_cycle; /* cycle structure */ struct stat *fts_statp; /* [l]stat(2) information */ } FTSENT; .EE .in .PP .\" .Bl -tag -width "fts_namelen" Эти поля определены следующим образом: .TP \fIfts_info\fP .\" .Bl -tag -width FTS_DEFAULT Одно из следующих значений описывает возвращённую структуру \fIFTSENT\fP и файл, который она представляет. За исключением каталогов без ошибок (\fBFTS_D\fP), все эти элементы являются конечными, то есть они не будут повторно обходиться, а их потомки не будут обходиться вообще. .RS .TP \fBFTS_D\fP Каталог, посещаемый в прямом порядке. .TP \fBFTS_DC\fP Каталог, вызвавший зацикливание в дереве (также будет заполнено поле \fIfts_cycle\fP структуры \fIFTSENT\fP). .TP \fBFTS_DEFAULT\fP Любая структура \fIFTSENT\fP, представляющая тип файла, неявно описываемый одним из других значений \fIfts_info\fP. .TP \fBFTS_DNR\fP Каталог, который не может быть прочитан. Это значение возвращается при ошибке, и поле \fIfts_errno\fP будет заполнено тем, что вызвало ошибку. .TP \fBFTS_DOT\fP Файл с именем «.» или «..», который не был указан в качестве имени файла в \fBfts_open\fP() (смотрите \fBFTS_SEEDOT\fP). .TP \fBFTS_DP\fP Каталог, посещаемый в обратном порядке. Содержимое структуры \fIFTSENT\fP будет неизменно, как если бы он посещался в прямом порядке, то есть значение поля \fIfts_info\fP равно \fBFTS_D\fP. .TP \fBFTS_ERR\fP Это значение возвращается при ошибке, и поле \fIfts_errno\fP будет заполнено тем, что вызвало ошибку. .TP \fBFTS_F\fP Обычный файл. .TP \fBFTS_NS\fP A file for which no [\fBl\fP]\fBstat\fP(2) information was available. The contents of the \fIfts_statp\fP field are undefined. This is an error return, and the \fIfts_errno\fP field will be set to indicate what caused the error. .TP \fBFTS_NSOK\fP A file for which no [\fBl\fP]\fBstat\fP(2) information was requested. The contents of the \fIfts_statp\fP field are undefined. .TP \fBFTS_SL\fP Символьная ссылка. .TP \fBFTS_SLNONE\fP .\" .El Символьная ссылка, указывающая на несуществующий объект. В поле \fIfts_statp\fP содержится ссылка на информацию о свойствах самой символьной ссылки. .RE .TP \fIfts_accpath\fP Путь к файлу относительно текущего каталога. .TP \fIfts_path\fP Путь к файлу относительно начального каталога обхода. Этот путь содержит в себе путь (как префикс), указанный в \fBfts_open\fP(). .TP \fIfts_pathlen\fP Сумма длин строк, на которые ссылается \fIfts_path\fP и \fIfts_name\fP. .TP \fIfts_name\fP Имя файла. .TP \fIfts_namelen\fP Длина строки, на которую ссылается \fIfts_name\fP. .TP \fIfts_level\fP Глубина погружения в дерево иерархии, от \-1 до N, на которой был обнаружен файл. Структура \fIFTSENT\fP, представляющая родительский каталог обхода (или начальный каталог), обозначена как \-1, а структура \fIFTSENT\fP для самой начальной точки поиска обозначена как 0. .TP \fIfts_errno\fP Если при возврате структуры \fIFTSENT\fP функцией \fBfts_children\fP() или \fBfts_read\fP() её поле \fIfts_info\fP равно \fBFTS_DNR\fP, \fBFTS_ERR\fP или \fBFTS_NS\fP, то в поле \fIfts_errno\fP содержится номер ошибки (то есть значение \fIerrno\fP), обозначающее причину ошибки. В других случаях, содержимое поля \fIfts_errno\fP не определено. .TP \fIfts_number\fP Это поле создано для использования пользовательским приложением и не изменяется функциями fts. При инициализации оно устанавливается в 0. .TP \fIfts_pointer\fP Это поле создано для использования пользовательским приложением и не изменяется функциями fts. При инициализации оно устанавливается в NULL. .TP \fIfts_parent\fP Указатель на структуру \fIFTSENT\fP, которая ссылается на файл в иерархии непосредственно над текущим файлом, то есть на каталог, членом которого является текущий файл. Родительский каталог начальной точки поиска также может быть доступен, однако инициализируются только поля \fIfts_level\fP, \fIfts_number\fP и \fIfts_pointer\fP. .TP \fIfts_link\fP При возврате функции \fBfts_children\fP() поле \fIfts_link\fP указывает на следующую структуру в связанном списке (заканчивающемся NULL) содержимого каталога. В другим случаях содержимое поля \fIfts_link\fP не определено. .TP \fIfts_cycle\fP Если каталог вызывает зацикливание иерархии (смотрите \fBFTS_DC\fP), либо из\-за жёсткой ссылки между двумя каталогами, либо из\-за символьной ссылки, указывающей на каталог, то поле \fIfts_cycle\fP будет указывать на структуру \fIFTSENT\fP в иерархии, которая ссылается на тот же файл, что и текущая структура \fIFTSENT\fP. В других случаях содержимое поля \fIfts_cycle\fP не определено. .TP \fIfts_statp\fP .\" .El A pointer to [\fBl\fP]\fBstat\fP(2) information for the file. .PP Для всех путей всех файлов в иерархии используется единый буфер. Следовательно, поля \fIfts_path\fP и \fIfts_accpath\fP гарантировано завершаются null \fIтолько\fP для файла, который был возвращён \fBfts_read\fP() последним. Для использования этих полей для обращения к любым файлам, представленным другими структурами \fIFTSENT\fP необходимо, чтобы буфер пути был изменён в соответствии с информацией, содержащейся в поле \fIfts_pathlen\fP структуры \fIFTSENT\fP. Любое изменение должно быть обратно восстановлено перед дальнейшими попытками вызова \fBfts_read\fP(). Поле \fIfts_name\fP всегда завершается null. .SS fts_open() Функция \fBfts_open\fP() ожидает указатель на массив символьных указателей, обозначающих один или несколько путей, образующих логическую файловую иерархию, по которой будет проводиться обход. Массив должен заканчиваться указателем null. .PP .\" .Bl -tag -width "FTS_PHYSICAL" Есть несколько флагов, должен быть указан хотя бы один (либо \fBFTS_LOGICAL\fP, либо \fBFTS_PHYSICAL\fP). Флаги, выбираемые с помощью логического объединения, имеют следующие значения: .TP \fBFTS_LOGICAL\fP This option causes the fts routines to return \fIFTSENT\fP structures for the targets of symbolic links instead of the symbolic links themselves. If this option is set, the only symbolic links for which \fIFTSENT\fP structures are returned to the application are those referencing nonexistent files: the \fIfts_statp\fP field is obtained via \fBstat\fP(2) with a fallback to \fBlstat\fP(2). .TP \fBFTS_PHYSICAL\fP This option causes the fts routines to return \fIFTSENT\fP structures for symbolic links themselves instead of the target files they point to. If this option is set, \fIFTSENT\fP structures for all symbolic links in the hierarchy are returned to the application: the \fIfts_statp\fP field is obtained via \fBlstat\fP(2). .TP \fBFTS_COMFOLLOW\fP This option causes any symbolic link specified as a root path to be followed immediately, as if via \fBFTS_LOGICAL\fP, regardless of the primary mode. .TP \fBFTS_NOCHDIR\fP As a performance optimization, the fts functions change directories as they walk the file hierarchy. This has the side\-effect that an application cannot rely on being in any particular directory during the traversal. This option turns off this optimization, and the fts functions will not change the current directory. Note that applications should not themselves change their current directory and try to access files unless \fBFTS_NOCHDIR\fP is specified and absolute pathnames were provided as arguments to \fBfts_open\fP(). .TP \fBFTS_NOSTAT\fP By default, returned \fIFTSENT\fP structures reference file characteristic information (the \fIfts_statp\fP field) for each file visited. This option relaxes that requirement as a performance optimization, allowing the fts functions to set the \fIfts_info\fP field to \fBFTS_NSOK\fP and leave the contents of the \fIfts_statp\fP field undefined. .TP \fBFTS_SEEDOT\fP По умолчанию, все файлы с именами «.» или «..», обнаруженные в файловой иерархии, игнорируются, если они не указаны как параметры пути в \fBfts_open\fP(). Данный флаг принуждает функции fts для таких файлов возвращать структуры \fIFTSENT\fP. .TP \fBFTS_XDEV\fP .\" .El Этот флаг предотвращает функции fts от вхождения в каталоги, которые имеют номер устройства, отличный от файла, с которого начался обход. .PP В параметре \fBcompar\fP() указывается определяемая пользователем функция, которая может использоваться для упорядочивания обхода иерархии. В качестве параметров ей требуется два указателя на указатели на структуры \fIFTSENT\fP, и она должна возвращать отрицательное значение, ноль или положительное значение для того, чтобы показать, расположен ли файл, на который указывает первый параметр, перед (относительно текущего упорядочивания), на одном уровне или после файла, на который указывает второй параметр. Поля \fIfts_accpath\fP, \fIfts_path\fP и \fIfts_pathlen\fP структур \fIFTSENT\fP могут быть \fIникогда\fP не использованы при таком сравнении. Если значение поля \fIfts_info\fP равно \fBFTS_NS\fP или \fBFTS_NSOK\fP, то поле \fIfts_statp\fP может не использоваться. Если значение параметра \fBcompar\fP() равно NULL, то порядок обхода каталогов определяется параметрами, указанными в \fIpath_argv\fP для корневых путей, и в порядке, перечисленном в каталоге, для всего остального. .SS fts_read() Функция \fBfts_read\fP() возвращает указатель на структуру \fIFTSENT\fP, описывающую файл в иерархии. Каталоги (корректно считанные и не образующие зацикливаний), посещаются как минимум дважды — первый раз в прямом прохождении и второй раз в обратном. Все остальные файлы посещаются минимум один раз (жёсткие ссылки между каталогами, не образующие зацикливаний, или символьные ссылки на символьные ссылки могут привести к тому, что файлы будут посещаться более одного раза, а каталоги более двух раз). .PP If all the members of the hierarchy have been returned, \fBfts_read\fP() returns NULL and sets \fIerrno\fP to 0. If an error unrelated to a file in the hierarchy occurs, \fBfts_read\fP() returns NULL and sets \fIerrno\fP to indicate the error. If an error related to a returned file occurs, a pointer to an \fIFTSENT\fP structure is returned, and \fIerrno\fP may or may not have been set (see \fIfts_info\fP). .PP Структуры \fIFTSENT\fP, возвращаемые \fBfts_read\fP(), могут быть перезаписаны после вызова \fBfts_close\fP() в том же файловом потоке иерархии или после вызова \fBfts_read\fP() в том же файловом потоке иерархии, если они не представляют файл типа «каталог»; в этом случае они не будут перезаписаны до тех пор, пока функция \fBfts_read\fP() не вернёт структуру \fIFTSENT\fP при выполнении обхода в обратном порядке. .SS fts_children() Функция \fBfts_children\fP() возвращает указатель на структуру \fIFTSENT\fP, описывающую первый член связанного списка (оканчивающегося NULL) файлов в каталоге, представленного структурой \fIFTSENT\fP, возвращённой \fBfts_read\fP() последней. Список связан через поле \fIfts_link\fP структуры \fIFTSENT\fP, и упорядочен определённой пользователем функцией сравнения, если таковая существует. Повторные вызовы \fBfts_children\fP() будут пересоздавать этот связанный список. .PP As a special case, if \fBfts_read\fP() has not yet been called for a hierarchy, \fBfts_children\fP() will return a pointer to the files in the logical directory specified to \fBfts_open\fP(), that is, the arguments specified to \fBfts_open\fP(). Otherwise, if the \fIFTSENT\fP structure most recently returned by \fBfts_read\fP() is not a directory being visited in preorder, or the directory does not contain any files, \fBfts_children\fP() returns NULL and sets \fIerrno\fP to zero. If an error occurs, \fBfts_children\fP() returns NULL and sets \fIerrno\fP to indicate the error. .PP Структура \fIFTSENT\fP, возвращаемая \fBfts_children\fP(), может быть перезаписана после вызова \fBfts_children\fP(), \fBfts_close\fP() или \fBfts_read\fP() в том же файловом потоке иерархии. .PP .\" .Bl -tag -width FTS_NAMEONLY Параметр \fIinstr\fP может принимать значение нуля или одного из следующих значений: .TP \fBFTS_NAMEONLY\fP .\" .El Необходимы только имена файлов. Содержимое всех полей в возвращаемом связанном списке структур не определено, за исключением полей \fIfts_name\fP и \fIfts_namelen\fP. .SS fts_set() Функция \fBfts_set\fP() позволяет пользовательскому приложению определять дальнейшую обработку файла \fIf\fP в потоке \fIftsp\fP. При успешном выполнении функция \fBfts_set\fP() возвращает 0 и \-1 при ошибке. .PP .\" .Bl -tag -width FTS_PHYSICAL Значением аргумента \fIinstr\fP может быть 0 («ничего не делать») или одно из следующих значений: .TP \fBFTS_AGAIN\fP Повторно посетить файл; файл любого типа может быть повторно посещён. Последующий вызов \fBfts_read\fP() возвратит файл, к которому идёт обращение. Поля \fIfts_stat\fP и \fIfts_info\fP структуры будут переинициализированы в этот момент, но никакие поля больше не будут изменены. Этот параметр значим только для последнего возвращённого файла из \fBfts_read\fP(). Обычно его используют при посещении каталогов в обратном порядке; в этом случае каталог посещается повторно (в прямом и обратном порядке), а также все его потомки. .TP \fBFTS_FOLLOW\fP Рассматриваемый файл должен быть символьной ссылкой. Если рассматриваемый файл — последний возвращённый \fBfts_read\fP(), то следующий вызов \fBfts_read\fP() возвратит файл с изменёнными полями \fIfts_info\fP и \fIfts_statp\fP, в которых будут отражать повторно инициализированные данные цели символьной ссылки, а не самой символьной ссылки. Если рассматриваемый файл — последний возвращённый \fBfts_children\fP(), то поля \fIfts_info\fP и \fIfts_statp\fP структуры при возврате из \fBfts_read\fP() будут отражать данные цели символьной ссылки, а не самой символьной ссылки. В любом случае, если цель символьной ссылки не существует, то поля возвращаемой структуры не будут меняться, а поле \fIfts_info\fP будет равно \fBFTS_SLNONE\fP. .IP Если цель ссылки — каталог, то выполняется возврат при прямом прохождении, после него возврат всех его потомков, после чего выполняется возврат в обратном порядке. .TP \fBFTS_SKIP\fP .\" .El Не посещать потомков данного файла. Файл может быть одним из последних возвращённых либо \fBfts_children\fP(), либо \fBfts_read\fP(). .SS fts_close() Функция \fBfts_close\fP() закрывает поток файловой иерархии, на который указывает \fIftsp\fP, и делает текущим каталогом тот, который был до вызова \fBfts_open\fP() для открытия \fIftsp\fP. При успешном выполнении функция \fBfts_close\fP() возвращает 0 и \-1 при ошибке. .SH ОШИБКИ Функция \fBfts_open\fP() может завершиться с ошибкой и назначить переменной \fIerrno\fP значения, перечисленные в \fBopen\fP(2) и \fBmalloc\fP(3). .PP In addition, \fBfts_open\fP() may fail and set \fIerrno\fP as follows: .TP \fBENOENT\fP Any element of \fIpath_argv\fP was an empty string. .PP Функция \fBfts_close\fP() может завершиться с ошибкой и назначить переменной \fIerrno\fP значения, перечисленные в \fBchdir\fP(2) и \fBclose\fP(2). .PP The functions \fBfts_read\fP() and \fBfts_children\fP() may fail and set \fIerrno\fP for any of the errors specified for \fBchdir\fP(2), \fBmalloc\fP(3), \fBopendir\fP(3), \fBreaddir\fP(3), and [\fBl\fP]\fBstat\fP(2). .PP Кроме того, функции \fBfts_children\fP(), \fBfts_open\fP() и \fBfts_set\fP() могут завершиться с ошибкой и назначить переменной \fIerrno\fP следующие значения: .TP \fBEINVAL\fP Некорректное значение \fIoptions\fP или \fIinstr\fP. .SH АТРИБУТЫ Описание терминов данного раздела смотрите в \fBattributes\fP(7). .TS allbox; lbx lb lb l l l. Интерфейс Атрибут Значение T{ .na .nh \fBfts_open\fP(), \fBfts_set\fP(), \fBfts_close\fP() T} Безвредность в нитях MT\-Safe T{ .na .nh \fBfts_read\fP(), \fBfts_children\fP() T} Безвредность в нитях MT\-Unsafe .TE .sp 1 .SH СТАНДАРТЫ None. .SH ИСТОРИЯ glibc 2. 4.4BSD. .SH ДЕФЕКТЫ .\" Fixed by commit 8b7b7f75d91f7bac323dd6a370aeb3e9c5c4a7d5 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=15838 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=11460 .\" .\" The following statement is years old, and seems no closer to .\" being true -- mtk .\" The .\" .I fts .\" utility is expected to be included in a future .\" POSIX.1 .\" revision. Before glibc 2.23, all of the APIs described in this man page are not safe when compiling a program using the LFS APIs (e.g., when compiling with \fI\-D_FILE_OFFSET_BITS=64\fP). .SH "СМ. ТАКЖЕ" \fBfind\fP(1), \fBchdir\fP(2), \fBlstat\fP(2), \fBstat\fP(2), \fBftw\fP(3), \fBqsort\fP(3) .PP .SH ПЕРЕВОД Русский перевод этой страницы руководства был сделан Azamat Hackimov , Dmitry Bolkhovskikh , Yuri Kozlov и Иван Павлов . .PP Этот перевод является бесплатной документацией; прочитайте .UR https://www.gnu.org/licenses/gpl-3.0.html Стандартную общественную лицензию GNU версии 3 .UE или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ. .PP Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на .MT man-pages-ru-talks@lists.sourceforge.net .ME .