1FTS(3) Linux Programmer's Manual FTS(3)
2
6 fts, fts_open, fts_read, fts_children, fts_set, fts_close - traverse a
7 file hierarchy
8
10 #include <sys/types.h>
11 #include <sys/stat.h>
12 #include <fts.h>
13 FTS *fts_open(char * const *path_argv, int options,
15 int (*compar)(const FTSENT **, const FTSENT **));
16 FTSENT *fts_read(FTS *ftsp);
18 FTSENT *fts_children(FTS *ftsp, int instr);
20 int fts_set(FTS *ftsp, FTSENT *f, int instr);
22 int fts_close(FTS *ftsp);
24
26 The fts functions are provided for traversing file hierarchies. A sim‐
27 ple overview is that the fts_open() function returns a "handle" (of
28 type FTS *) that refers to a file hierarchy "stream". This handle is
29 then supplied to the other fts functions. The function fts_read()
30 returns a pointer to a structure describing one of the files in the
31 file hierarchy. The function fts_children() returns a pointer to a
32 linked list of structures, each of which describes one of the files
33 contained in a directory in the hierarchy.
34 In general, directories are visited two distinguishable times; in pre‐
36 order (before any of their descendants are visited) and in postorder
37 (after all of their descendants have been visited). Files are visited
38 once. It is possible to walk the hierarchy "logically" (visiting the
39 files that symbolic links point to) or physically (visiting the sym‐
40 bolic links themselves), order the walk of the hierarchy or prune
41 and/or revisit portions of the hierarchy.
42 Two structures (and associated types) are defined in the include file
44 <fts.h>. The first type is FTS, the structure that represents the file
45 hierarchy itself. The second type is FTSENT, the structure that repre‐
46 sents a file in the file hierarchy. Normally, an FTSENT structure is
47 returned for every file in the file hierarchy. In this manual page,
48 "file" and "FTSENT structure" are generally interchangeable.
49 The FTSENT structure contains fields describing a file. The structure
51 contains at least the following fields (there are additional fields
52 that should be considered private to the implementation):
53 typedef struct _ftsent {
55 unsigned short fts_info; /* flags for FTSENT structure */
56 char *fts_accpath; /* access path */
57 char *fts_path; /* root path */
58 short fts_pathlen; /* strlen(fts_path) +
59 strlen(fts_name) */
60 char *fts_name; /* filename */
61 short fts_namelen; /* strlen(fts_name) */
62 short fts_level; /* depth (-1 to N) */
63 int fts_errno; /* file errno */
64 long fts_number; /* local numeric value */
65 void *fts_pointer; /* local address value */
66 struct _ftsent *fts_parent; /* parent directory */
67 struct _ftsent *fts_link; /* next file structure */
68 struct _ftsent *fts_cycle; /* cycle structure */
69 struct stat *fts_statp; /* stat(2)