.\" Copyright (c) 1989 The Regents of the University of California.
.\" Redistribution and use in source and binary forms are permitted
.\" provided that the above copyright notice and this paragraph are
.\" duplicated in all such forms and that any documentation,
.\" advertising materials, and other materials related to such
.\" distribution and use acknowledge that the software was developed
.\" by the University of California, Berkeley. The name of the
.\" University may not be used to endorse or promote products derived
.\" from this software without specific prior written permission.
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\" @(#)fts.3 5.5 (Berkeley) %G%
fts \- traverse a file hierarchy
ftsopen(path_argv, options, compar)
int options, (*compar)();
utilities are provided for traversing UNIX file hierarchies.
Two structures are defined (and typedef'd) in the include file <\fIfts.h\fP>.
The first is FTS, the structure that defines the file hierarchy stream.
The second is FTSENT, the structure that defines a file in the file
routine takes a pointer to an array of character pointers (``argv'')
naming the file hierarchies to be traversed.
The array must be terminated by a pointer to a NULL string.
one or more of the following values:
by default, to determine the status of each file.
If this option is set, the only symbolic links returned to the application
are those referencing non-existent files.
Either FTS_LOGICAL or FTS_PHYSICAL
As a performance optimization,
changes directories as it descends the hierarchy.
This has the side-effect that applications cannot rely on being
in any particular directory.
The FTS_NOCHDIR option turns off this optimization.
Note that applications should not change the current directory
(even if FTS_NOCHDIR is specified) unless absolute pathnames were
provide file characteristic information (the
field) for each file they return.
This option relaxes that requirement; the contents of the
field may be undefined, and the
field may be set to FTS_NS.
by default, to determine the status of each file.
If this option is set, all symbolic links are returned to the application
Either FTS_LOGICAL or FTS_PHYSICAL
This option causes the routine
to return structures for the directory entries ``.'' and ``..''.
By default they are ignored unless specified as an argument to
from descending into directories that have a different device number
than the file the descent began from.
specifies a user-defined routine which is used to order the traversal
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.
fields of the FTSENT structures may not be used in this comparison.
field may not be used as well.
argument is NULL the directory traversal order is unspecified except
for the root paths which are traversed in the order listed in
routine closes a file hierarchy stream and changes the current
directory to the directory
returns 0 on success, and -1 if an error occurs.
routine returns a pointer to an FTSENT structure describing a file in
Directories (that are readable, searchable and do not cause cycles)
are visited at least twice, before any of their descendants have been
visited (pre-order) and after all their descendants have been visited
All other files are visited at least once.
The FTSENT structure contains at least the following fields:
.ta .5i +.5i +\w'struct ftsent *parent;\0\0\0'u
struct ftsent *fts_parent; /* parent structure */
struct ftsent *fts_link; /* cycle or file structure */
long number; /* local numeric value */
void *pointer; /* local address value */
char *fts_accpath; /* path from current directory */
char *fts_path; /* path from starting directory */
char *fts_name; /* file name */
short fts_pathlen; /* strlen(path) */
short fts_namelen; /* strlen(name) */
short fts_level; /* depth (\-1 to N) */
unsigned short fts_info; /* flags for entry */
struct stat fts_statb; /* stat(2) information */
The fields are as follows:
A pointer to a structure referencing the file in the hierarchy
immediately above the current file/structure.
A parent structure for the initial entry point is provided as well,
fields are guaranteed to be initialized.
If a directory causes a cycle in the hierarchy, either because of a
hard link between two directories, or a symbolic link pointing to a
field of the structure will point to the structure in the hierarchy
that references the same file as the current structure.
field points to the next structure in the linked list of entries
Otherwise, the contents of the
This field is provided for the use of the application program.
It can be used to store either a long value or an address.
A path that can be used to access the file.
The path for the file relative to the root of the traversal.
The basename of the file.
The length of the string referenced by
The length of the string referenced by
The depth of the traversal, numbered from \-1 to N.
The parent structure of the root of the traversal is numbered \-1, and
the structure for the root of the traversal is numbered 0.
Information describing the file.
With the exception of directories (FTS_D), all of these entries are
terminal, i.e. they will not be revisited, nor will their descendants
be visited (if they have not been visited already).
A directory being visited in pre-order.
A directory that causes a cycle.
field of the structure will be filled in as well.
Anything that's not one of the others.
A directory that cannot be read.
A directory that cannot be searched.
A file named ``.'' or ``..'' with a
field not equal to zero, i.e. one not specified as an argument to
A directory that is being visited in post-order.
The contents of the structure will be unchanged from when the
directory was visited in pre-order.
An error indicator; the external variable
contains an error number indicating the reason for the error.
information is available at this time (see FTS_NOSTAT); the
A symbolic link with a non-existent target.
information for the file.
fields are guaranteed to be NULL-terminated
for the file most recently returned by
field is always NULL-terminated.
To use these fields to reference any other active files may require
that they be modified using the information contained in the
Any such modifications should be undone before further calls to
If all the members of the hierarchy have been returned,
returns NULL and sets the external variable
If an error unrelated to a file in the hierarchy occurs,
returns NULL and sets errno appropriately.
Otherwise, a pointer to an FTSENT structure is returned, and an
error may or may not have occurred; see FTS_ERR above.
When the most recently returned file from
is a directory being visited in pre-order,
returns a pointer to the first entry in a linked list (sorted by
the comparison routine, if provided) of the directory entries
The linked list is linked through the
field of the FTSENT structure.
Note, cycles are not detected until a directory is actually visited,
will never return a structure with an
If the current file is not a directory being visited in pre-order,
or if an error occurs, or the file does not contain any entries
sets errno appropriately, otherwise it sets errno to zero.
point to structures which may be overwritten.
may be overwritten after a call to
on the same file hierarchy.
Otherwise, structures returned by
will not be overwritten until a subsequent call to either
on the same file hierarchy.
will not not be overwritten until a subsequent call to
on the same file hierarchy stream, unless it represents a file of type
directory, in which case it will not be overwritten until after a
after it has been returned by the function
allows the user application to determine further processing for the
returns 0 on success, and -1 if an error occurs.
may be set to any one of the following values.
Re-visit the file; any file type may be re-visited.
will return the referenced file.
fields of the structure will be reinitialized at that time,
but no other fields will have been modified.
This option is meaningful only for the most recently returned
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
The referenced file must be a symbolic link.
If the referenced file is the one most recently returned by
returns the file with the
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
fields of the structure, when returned by
will reflect the target of the symbolic link instead of the symbolic link
In either case, 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.
No descendants of this file are visited.
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.
may fail and set errno for any of the errors specified for the library
may fail and set errno for any of the errors specified for the library
may fail and set errno for any of the errors specified for the library
find(1), chdir(2), stat(2), qsort(3)
utility is expected to be a superset of the POSIX 1003.1 specification.
projects / unix-history / blob