fts (3) - Linux Manuals
fts: traverse a file hierarchy
NAME
fts, fts_open, fts_read, fts_children, fts_set, fts_close - traverse a file hierarchy
SYNOPSIS
#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);
DESCRIPTION
The fts functions are provided for traversing file hierarchies. A simple overview is that the fts_open() function returns a "handle" (of type FTS *) that refers to a file hierarchy "stream". This handle 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 preorder (before any of their descendants are visited) and in postorder (after all of their descendants have been visited). Files are visited once. It is possible to walk the hierarchy "logically" (visiting the files that symbolic links point to) or physically (visiting the symbolic links themselves), order the walk of the hierarchy or prune and/or revisit portions of the hierarchy.
Two structures (and associated types) are defined in the include file <fts.h>. The first type is FTS, the structure that represents the file hierarchy itself. The second type 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 fields describing a file. The structure contains at least the following fields (there are additional fields that should be considered private to the implementation):
typedef struct _ftsent {
These fields are defined as follows:
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
null-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
null-terminated.
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 ORing
the following values:
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.
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 postorder.
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(),
that is, the arguments specified to
fts_open().
Otherwise, if the
FTSENT
structure most recently returned by
fts_read()
is not a directory being visited in preorder,
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.
The
instr
argument is either zero or the following value:
The
instr
argument is either 0 (meaning "do nothing") or one of the following values:
The function
fts_close()
may fail and set
errno
for any of the errors specified for
chdir(2)
and
close(2).
The functions
fts_read()
and
fts_children()
may fail and set
errno
for any of the errors specified for
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:
fts_open()
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.
fts_read()
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 preorder and once in postorder.
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.)
fts_children()
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 re-create this linked list.
fts_set()
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.
fts_close()
The
fts_close()
function closes the file hierarchy stream referred to by
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.
ERRORS
The function
fts_open()
may fail and set
errno
for any of the errors specified for
open(2)
and
malloc(3).
VERSIONS
These functions are available in Linux since glibc2.
ATTRIBUTES
For an explanation of the terms used in this section, see
attributes(7).
Interface Attribute Value
fts_open(),
fts_set(),
fts_close()
Thread safety MT-Safe
fts_read(),
fts_children()
Thread safety MT-Unsafe CONFORMING TO
4.4BSD.
BUGS
In versions of glibc before 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
-D_FILE_OFFSET_BITS=64).
COLOPHON
This page is part of release 5.10 of the Linux
man-pages
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
https://www.kernel.org/doc/man-pages/.