FTS(3) | Library Functions Manual | FTS(3) |
fts
— traverse a
file hierarchy
Standard C Library (libc, -lc)
#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 **));
FTS *
fts_open_b
(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);
The fts
functions are provided for
traversing UNIX file hierarchies. A simple overview is that the
fts_open
()
and
fts_open_b
()
functions return a “handle” on a file hierarchy, which is then
supplied to the other fts
functions. The function
fts_read
() returns a pointer to a structure
describing one of the files in the file hierarchy. The function
fts_children
() returns a pointer to a linked list of
structures, each of which describes one of the files contained in a
directory in the hierarchy. In general, directories are visited two
distinguishable times; in pre-order (before any of their descendants are
visited) and in post-order (after all of their descendants have been
visited). Files are visited once. It is possible to walk the hierarchy
“logically” (ignoring symbolic links) or physically (visiting
symbolic links), order the walk of the hierarchy or prune and/or re-visit
portions of the hierarchy.
Two structures are defined (and typedef'd) in the include file ⟨fts.h⟩. The first is FTS, the structure that represents the file hierarchy itself. The second is FTSENT, the structure that represents a file in the file hierarchy. Normally, an FTSENT structure is returned for every file in the file hierarchy. In this manual page, “file” and “FTSENT structure” are generally interchangeable. The FTSENT structure contains at least the following fields, which are described in greater detail below:
typedef struct _ftsent { u_short fts_info; /* flags for FTSENT structure */ char *fts_accpath; /* access path */ char *fts_path; /* root path */ u_short fts_pathlen; /* strlen(fts_path) */ char *fts_name; /* file name */ u_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; /* stat(2) information */ } FTSENT;
These fields are defined as follows:
FTS_D
), all of these entries are terminal, that
is, they will not be revisited, nor will any of their descendants be
visited.
FTS_D
FTS_DC
FTS_DEFAULT
FTS_DNR
FTS_DOT
.
’ or
‘..
’ which was not specified as
a file name to
fts_open
()
or
fts_open_b
()
(see FTS_SEEDOT
).FTS_DP
FTS_D
.FTS_ERR
FTS_F
FTS_NS
FTS_NSOK
FTS_SL
FTS_SLNONE
fts_open
() or
fts_open_b
() as a prefix.FTS_ROOTPARENTLEVEL
(-1), and the
FTSENT structure for the root itself is numbered
FTS_ROOTLEVEL
(0).fts_children
() or
fts_read
() functions, with its
fts_info field set to
FTS_DNR
, FTS_ERR
or
FTS_NS
, the fts_errno field
contains the value of the external variable errno
specifying the cause of the error. Otherwise, the contents of the
fts_errno field are undefined.fts
functions. It is initialized
to 0.fts
functions. It is initialized
to NULL
.fts_children
() function, the
fts_link field points to the next structure in the
NULL-terminated linked list of directory members. Otherwise, the contents
of the fts_link field are undefined.FTS_DC
), either because of a hard link between two
directories, or a symbolic link pointing to a directory, the
fts_cycle field of the structure will point to the
FTSENT structure in the hierarchy that references
the same file as the current FTSENT structure.
Otherwise, the contents of the fts_cycle field are
undefined.A single buffer is used for all of the paths of all of
the files in the file hierarchy. Therefore, the
fts_path and fts_accpath fields
are guaranteed to be NUL
-terminated
only for the file
most recently returned by
fts_read
().
To use these fields to reference any files represented by other
FTSENT structures will require that the path buffer be
modified using the information contained in that
FTSENT structure's fts_pathlen
field. Any such modifications should be undone before further calls to
fts_read
() are attempted. The
fts_name field is always
NUL
-terminated.
The fts_open
() function takes a pointer to
an array of character pointers naming one or more paths which make up a
logical file hierarchy to be traversed. The array must be terminated by a
NULL
pointer.
There are a number of options, at least one of which
(either FTS_LOGICAL
or
FTS_PHYSICAL
) must be specified. The options are
selected by or'ing the
following values:
FTS_COMFOLLOW
FTS_LOGICAL
is
also specified.FTS_LOGICAL
fts
routines to return
FTSENT structures for the targets of symbolic links
instead of the symbolic links themselves. If this option is set, the only
symbolic links for which FTSENT structures are
returned to the application are those referencing non-existent files.
Either FTS_LOGICAL
or
FTS_PHYSICAL
must be provided to
the
fts_open
()
function.FTS_NOCHDIR
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. The FTS_NOCHDIR
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 FTS_NOCHDIR
is specified and absolute
pathnames were provided as arguments to
fts_open
().FTS_NOSTAT
fts
functions will set the
fts_info field to FTS_NSOK
;
otherwise fts_info will be set to the correct file
information value corresponding to the
stat(2) information. In any case, the
statp field will always be undefined. Note that
because fts
detects directory cycles and dangling
symbolic links, stat(2) is always
called for directories and is called for symbolic links when
FTS_LOGICAL
is set.FTS_NOSTAT_TYPE
FTS_NOSTAT
but if the file type is returned
by readdir(3), the corresponding
file information value is returned in fts_info
instead of FTS_NSOK
.FTS_PHYSICAL
fts
routines to return
FTSENT structures for symbolic links themselves
instead of the target files they point to. If this option is set,
FTSENT structures for all symbolic links in the
hierarchy are returned to the application. Either
FTS_LOGICAL
or
FTS_PHYSICAL
must be provided to
the fts_open
() function.FTS_SEEDOT
fts_open
(), any files named
‘.
’ or
‘..
’ encountered in the file
hierarchy are ignored. This option causes the fts
routines to return FTSENT structures for them.FTS_XDEV
fts
from descending into
directories that have a different device number than the file from which
the descent began.The argument
compar
()
specifies a user-defined function which may be used to order the traversal
of the hierarchy. It takes two pointers to pointers to
FTSENT structures as arguments and should return a
negative value, zero, or a positive value to indicate if the file referenced
by its first argument comes before, in any order with respect to, or after,
the file referenced by its second argument. The
fts_accpath, fts_path and
fts_pathlen fields of the FTSENT
structures may
never be
used in this comparison. If the fts_info field is set
to FTS_NS
or FTS_NSOK
, the
fts_statp field may not either. If the
compar
() argument is NULL
,
the directory traversal order is in the order listed in
path_argv for the root paths, and in the order listed
in the directory for everything else.
The fts_open_b
() function is like
fts_open
() except compar is a
block pointer instead of a function pointer. This block is passed to
qsort_b(3) (whereas
fts_open
() passes its function pointer to
qsort(3)).
Block_copy
()
function (defined in
<Blocks.h>
) is used by
fts_open_b
() to make a copy of the block, especially
for the case when a stack-based block might go out of scope when the
subroutine returns.The fts_read
() function returns a pointer
to an FTSENT structure describing a file in the
hierarchy. Directories (that are readable and do not cause cycles) are
visited at least twice, once in pre-order and once in post-order. All other
files are visited at least once. (Hard links between directories that do not
cause cycles or symbolic links to symbolic links may cause files to be
visited more than once, or directories more than twice.)
If all the members of the hierarchy have been
returned,
fts_read
()
returns NULL
and sets the external variable
errno to 0. If an error unrelated to a file in the
hierarchy occurs, fts_read
() returns
NULL
and sets errno
appropriately. If an error related to a returned file occurs, a pointer to
an FTSENT structure is returned, and
errno may or may not have been set (see
fts_info).
The FTSENT structures
returned by
fts_read
()
may be overwritten after a call to
fts_close
()
on the same file hierarchy stream, or, after a call to
fts_read
() on the same file hierarchy stream unless
they represent a file of type directory, in which case they will not be
overwritten until after a call to fts_read
() after
the FTSENT structure has been returned by the function
fts_read
() in post-order.
The fts_children
() function returns a
pointer to an FTSENT structure describing the first
entry in a NULL-terminated linked list of the files in the directory
represented by the FTSENT structure most recently
returned by fts_read
(). The list is linked through
the fts_link field of the FTSENT
structure, and is ordered by the user-specified comparison function, if any.
Repeated calls to fts_children
() will recreate this
linked list.
As a special case, if
fts_read
()
has not yet been called for a hierarchy,
fts_children
() will return a pointer to the files in
the logical directory specified to fts_open
(), i.e.
the arguments specified to fts_open
(). Otherwise, if
the FTSENT structure most recently returned by
fts_read
() is not a directory being visited in
pre-order, or the directory does not contain any files,
fts_children
() returns NULL
and sets errno to zero. If an error occurs,
fts_children
() returns NULL
and sets errno appropriately.
The FTSENT structures
returned by
fts_children
()
may be overwritten after a call to fts_children
(),
fts_close
() or fts_read
() on
the same file hierarchy stream.
Option may be set to the following value:
FTS_NAMEONLY
The function
fts_set
()
allows the user application to determine further processing for the file
f of the stream ftsp. The
fts_set
() function returns 0 on success, and -1 if
an error occurs. Option must be set to one of the
following values:
FTS_AGAIN
fts_read
() will return the referenced file. The
fts_stat and fts_info fields
of the structure will be reinitialized at that time, but no other fields
will have been changed. This option is meaningful only for the most
recently returned file from fts_read
(). Normal use
is for post-order directory visits, where it causes the directory to be
re-visited (in both pre and post-order) as well as all of its
descendants.FTS_FOLLOW
fts_read
(), the next
call to fts_read
() returns the file with the
fts_info and fts_statp fields
reinitialized to reflect the target of the symbolic link instead of the
symbolic link itself. If the file is one of those most recently returned
by fts_children
(), the
fts_info and fts_statp fields
of the structure, when returned by fts_read
(),
will reflect the target of the symbolic link instead of the symbolic link
itself. In either case, if the target of the symbolic link does not exist
the fields of the returned structure will be unchanged and the
fts_info field will be set to
FTS_SLNONE
.
If the target of the link is a directory, the pre-order return, followed by the return of all of its descendants, followed by a post-order return, is done.
FTS_SKIP
fts_children
()
or fts_read
().The fts_close
() function closes a file
hierarchy stream ftsp and restores the current
directory to the directory from which fts_open
() was
called to open ftsp. The
fts_close
() function returns 0 on success, and -1 if
an error occurs.
The function fts_open
() may fail and set
errno for any of the errors specified for the library
functions open(2) and
malloc(3).
The function fts_close
() may fail and set
errno for any of the errors specified for the library
functions chdir(2) and
close(2).
The functions fts_read
() and
fts_children
() may fail and set
errno for any of the errors specified for the library
functions chdir(2),
malloc(3),
opendir(3),
readdir(3) and
stat(2).
In addition, fts_children
(),
fts_open
() and fts_set
() may
fail and set errno as follows:
EINVAL
]The fts
utility is expected to be included
in a future IEEE Std 1003.1-1988
(“POSIX.1”) revision.
Sept 24, 2012 | macOS 14.6 |