4.3BSD-Reno/share/man/cat3/fts.0
FTS(3) 1990 FTS(3)
NNAAMMEE
fts - traverse a file hierarchy
SSYYNNOOPPSSIISS
##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
##iinncclluuddee <<ssyyss//ssttaatt..hh>>
##iinncclluuddee <<ffttss..hh>>
FFTTSS **
ffttssooppeenn((ppaatthh__aarrggvv,, ooppttiioonnss,, ccoommppaarr))
cchhaarr **ppaatthh__aarrggvv[[]];;
iinntt ooppttiioonnss,, ((**ccoommppaarr))(());;
FFTTSSEENNTT **
ffttssrreeaadd((ffttsspp));;
FFTTSS **ffttsspp;;
FFTTSSEENNTT **
ffttsscchhiillddrreenn((ffttsspp))
FFTTSS **ffttsspp;;
ffttsssseett((ffttsspp,, ff,, ooppttiioonnss))
FFTTSS **ffttsspp;;
FFTTSSEENNTT **ff;;
iinntt ooppttiioonnss;;
ffttsscclloossee((ffttsspp))
FFTTSS **ffttsspp;;
DDEESSCCRRIIPPTTIIOONN
The _f_t_s(3) utilities are provided for traversing UNIX file
hierarchies. Two structures are defined (and typedef'd) in
the include file <_f_t_s._h>. 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
hierarchy.
The _f_t_s_o_p_e_n 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.
The _o_p_t_i_o_n_s specified are formed by _o_r'ing one or more of
the following values:
FTS_LOGICAL
This option causes _f_t_s_r_e_a_d to use the function _s_t_a_t(2),
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 mmuusstt be pro-
vided to the _f_t_s_o_p_e_n routine.
Printed 7/27/90 June 1
FTS(3) 1990 FTS(3)
FTS_NOCHDIR
As a performance optimization, _f_t_s_r_e_a_d changes direc-
tories 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 provided
as arguments to _f_t_s_o_p_e_n.
FTS_NOSTAT
By default, _f_t_s_r_e_a_d and _f_t_s_c_h_i_l_d_r_e_n provide file
characteristic information (the _s_t_a_t_b field) for each
file they return. This option relaxes that require-
ment; the contents of the _s_t_a_t_b field may be undefined,
and the _i_n_f_o field may be set to FTS_NS.
FTS_PHYSICAL
This option causes _f_t_s_r_e_a_d to use the function
_l_s_t_a_t(2), by default, to determine the status of each
file. If this option is set, all symbolic links are
returned to the application program. Either
FTS_LOGICAL or FTS_PHYSICAL mmuusstt be provided to the
_f_t_s_o_p_e_n routine.
FTS_SEEDOT
This option causes the routine _f_t_s_r_e_a_d to return struc-
tures for the directory entries ``.'' and ``..''. By
default they are ignored unless specified as an argu-
ment to _f_t_s_o_p_e_n.
FTS_XDEV
This option keeps _f_t_s from descending into directories
that have a different device number than the file the
descent began from.
The argument _c_o_m_p_a_r specifies a user-defined routine which
is used to order the traversal of directories. _C_o_m_p_a_r 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 argu-
ment comes before, in any order with respect to, or after,
the file referenced by its second argument.
The _f_t_s__a_c_c_p_a_t_h and _f_t_s__p_a_t_h fields of the FTSENT structures
may not be used in this comparison. If the option
_F_T_S__N_O_S_T_A_T is specified, the _f_t_s__s_t_a_b field may not be used
as well. If the _c_o_m_p_a_r argument is NULL the directory
traversal order is unspecified except for the root paths
which are traversed in the order listed in _p_a_t_h__a_r_g_v.
Printed 7/27/90 June 2
FTS(3) 1990 FTS(3)
The _f_t_s_c_l_o_s_e routine closes a file hierarchy stream and
changes the current directory to the directory _f_t_s_o_p_e_n was
called from. _F_t_s_c_l_o_s_e returns 0 on success, and -1 if an
error occurs.
Each call to the _f_t_s_r_e_a_d routine returns a pointer to an
FTSENT structure describing a file in the hierarchy. Direc-
tories (that are readable, searchable and do not cause
cycles) are visited at least twice, before any of their des-
cendants have been visited (pre-order) and after all their
descendants have been visited (post-order). All other files
are visited at least once.
The FTSENT structure contains at least the following fields:
typedef struct ftsent {
struct ftsent *fts_parent; /* parent structure */
struct ftsent *fts_link; /* cycle or file structure */
union {
long number; /* local numeric value */
void *pointer; /* local address value */
} fts_local;
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 */
} FTSENT;
The fields are as follows:
fts_parent
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 pro-
vided as well, however, only the _f_t_s__l_o_c_a_l and
_f_t_s__l_e_v_e_l fields are guaranteed to be initialized.
fts_link
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 directory, the _f_t_s__l_i_n_k
field of the structure will point to the structure in
the hierarchy that references the same file as the
current structure. Upon return from the _f_t_s_c_h_i_l_d_r_e_n
routine, the _f_t_s__l_i_n_k field points to the next struc-
ture in the linked list of entries from the directory.
Otherwise, the contents of the _f_t_s__l_i_n_k field are unde-
fined.
Printed 7/27/90 June 3
FTS(3) 1990 FTS(3)
fts_local
This field is provided for the use of the application
program. It can be used to store either a long value
or an address.
fts_accpath
A path that can be used to access the file.
fts_path
The path for the file relative to the root of the
traversal.
fts_name
The basename of the file.
fts_pathlen
The length of the string referenced by _f_t_s__p_a_t_h.
fts_namelen
The length of the string referenced by _f_t_s__n_a_m_e.
fts_level
The depth of the traversal, numbered from -1 to N. The
parent structure of the root of the traversal is num-
bered -1, and the structure for the root of the traver-
sal is numbered 0.
fts_info
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 descen-
dants be visited (if they have not been visited
already).
FTS_D
A directory being visited in pre-order.
FTS_DC
A directory that causes a cycle. The _f_t_s__l_i_n_k
field of the structure will be filled in as well.
FTS_DEFAULT
Anything that's not one of the others.
FTS_DNR
A directory that cannot be read.
FTS_DNX
A directory that cannot be searched.
FTS_DOT
A file named ``.'' or ``..'' with a _f_t_s__l_e_v_e_l
Printed 7/27/90 June 4
FTS(3) 1990 FTS(3)
field not equal to zero, i.e. one not specified as
an argument to _f_t_s_o_p_e_n. (See FTS_SEEDOT.)
FTS_DP
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.
FTS_ERR
An error indicator; the external variable _e_r_r_n_o
contains an error number indicating the reason for
the error.
FTS_F
A regular file.
FTS_NS
No _s_t_a_t(2) information is available at this time
(see FTS_NOSTAT); the contents of the _f_t_s__s_t_a_t_b
field are undefined.
FTS_SL
A symbolic link.
FTS_SLNONE
A symbolic link with a non-existent target.
fts_statb
_S_t_a_t(2) information for the file.
The _f_t_s__a_c_c_p_a_t_h and _f_t_s__p_a_t_h fields are guaranteed to be
NULL-terminated oonnllyy for the file most recently returned by
_f_t_s_r_e_a_d. The _f_t_s__n_a_m_e field is always NULL-terminated. To
use these fields to reference any other active files may
require that they be modified using the information con-
tained in the _f_t_s__p_a_t_h_l_e_n field. Any such modifications
should be undone before further calls to _f_t_s_r_e_a_d are
attempted.
If all the members of the hierarchy have been returned,
_f_t_s_r_e_a_d returns NULL and sets the external variable _e_r_r_n_o to
0. If an error unrelated to a file in the hierarchy occurs,
_f_t_s_r_e_a_d returns NULL and sets errno appropriately. Other-
wise, 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 _f_t_s_r_e_a_d is a
directory being visited in pre-order, _f_t_s_c_h_i_l_d_r_e_n returns a
pointer to the first entry in a linked list (sorted by the
comparison routine, if provided) of the directory entries it
contains. The linked list is linked through the _f_t_s__l_i_n_k
field of the FTSENT structure. Each call to _f_t_s_c_h_i_l_d_r_e_n
Printed 7/27/90 June 5
FTS(3) 1990 FTS(3)
recreates the list. Note, cycles are not detected until a
directory is actually visited, therefore _f_t_s_c_h_i_l_d_r_e_n will
never return a structure with an _f_t_s__i_n_f_o field set to
FTS_DC. 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 _f_t_s_c_h_i_l_d_r_e_n returns NULL. If
an error occurs, _f_t_s_c_h_i_l_d_r_e_n sets errno appropriately, oth-
erwise it sets errno to zero.
The pointers returned by _f_t_s_r_e_a_d and _f_t_s_c_h_i_l_d_r_e_n point to
structures which may be overwritten. Structures returned by
_f_t_s_c_h_i_l_d_r_e_n and _f_t_s_r_e_a_d may be overwritten after a call to
_f_t_s_c_l_o_s_e on the same file hierarchy. Otherwise, structures
returned by _f_t_s_c_h_i_l_d_r_e_n will not be overwritten until a sub-
sequent call to either _f_t_s_c_h_i_l_d_r_e_n or _f_t_s_r_e_a_d on the same
file hierarchy. Structures returned by _f_t_s_r_e_a_d will not not
be overwritten until a subsequent call to _f_t_s_r_e_a_d 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 subsequent call to _f_t_s_r_e_a_d after it has been
returned by the function _f_t_s_r_e_a_d in post-order.
The routine _f_t_s_s_e_t allows the user application to determine
further processing for the file _f of the stream _f_t_s_p.
_F_t_s_s_e_t returns 0 on success, and -1 if an error occurs.
_O_p_t_i_o_n may be set to any one of the following values.
FTS_AGAIN
Re-visit the file; any file type may be re-visited.
The next call to _f_t_s_r_e_a_d will return the referenced
file. The _f_t_s__s_t_a_t and _f_t_s__i_n_f_o fields of the struc-
ture will be reinitialized at that time, but no other
fields will have been modified. This option is mean-
ingful only for the most recently returned file from
_f_t_s_r_e_a_d. 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 des-
cendants.
FTS_FOLLOW
The referenced file must be a symbolic link. If the
referenced file is the one most recently returned by
_f_t_s_r_e_a_d, the next call to _f_t_s_r_e_a_d returns the file with
the _f_t_s__i_n_f_o and _f_t_s__s_t_a_t_b 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 _f_t_s_c_h_i_l_d_r_e_n, the _f_t_s__i_n_f_o and
_f_t_s__s_t_a_t_b fields of the structure, when returned by
_f_t_s_r_e_a_d, will reflect the target of the symbolic link
instead of the symbolic link itself. In either case,
if the target of the link is a directory, the pre-order
return, followed by the return of all of its
Printed 7/27/90 June 6
FTS(3) 1990 FTS(3)
descendants, followed by a post-order return, is done.
FTS_SKIP
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.
EERRRROORRSS
_F_t_s_o_p_e_n may fail and set errno for any of the errors speci-
fied for the library routine _m_a_l_l_o_c(3).
_F_t_s_c_l_o_s_e may fail and set errno for any of the errors speci-
fied for the library routine _c_h_d_i_r(2).
_F_t_s_r_e_a_d and _f_t_s_c_h_i_l_d_r_e_n may fail and set errno for any of
the errors specified for the library routines _c_h_d_i_r(2), _g_e_t_-
_g_r_o_u_p_s(2), _m_a_l_l_o_c(3), _o_p_e_n_d_i_r(3), _r_e_a_d_d_i_r(3) and _s_t_a_t(2).
SSEEEE AALLSSOO
find(1), chdir(2), stat(2), qsort(3)
SSTTAANNDDAARRDDSS
The _f_t_s utility is expected to be a superset of the POSIX
1003.1 specification.
Printed 7/27/90 June 7