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 options);
20 int fts_set(FTS *ftsp, FTSENT *f, int options);
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" on a
28 file hierarchy, which is then supplied to the other fts functions. The
29 function fts_read() returns a pointer to a structure describing one of
30 the files in the file hierarchy. The function fts_children() returns a
31 pointer to a linked list of structures, each of which describes one of
32 the files contained in a directory in the hierarchy. In general,
33 directories are visited two distinguishable times; in preorder (before
34 any of their descendants are visited) and in postorder (after all of
35 their descendants have been visited). Files are visited once. It is
36 possible to walk the hierarchy "logically" (visiting the files that
37 symbolic links point to) or physically (visiting the symbolic links
38 themselves), order the walk of the hierarchy or prune and/or revisit
39 portions of the hierarchy.
40 Two structures are defined (and typedef'd) in the include file <fts.h>.
42 The first is FTS, the structure that represents the file hierarchy
43 itself. The second is FTSENT, the structure that represents a file in
44 the file hierarchy. Normally, an FTSENT structure is returned for
45 every file in the file hierarchy. In this manual page, "file" and
46 "FTSENT structure" are generally interchangeable. The FTSENT structure
47 contains at least the following fields, which are described in greater
48 detail below:
49 typedef struct _ftsent {
51 unsigned short fts_info; /* flags for FTSENT structure */
52 char *fts_accpath; /* access path */
53 char *fts_path; /* root path */
54 short fts_pathlen; /* strlen(fts_path) */
55 char *fts_name; /* filename */
56 short fts_namelen; /* strlen(fts_name) */
57 short fts_level; /* depth (-1 to N) */
58 int fts_errno; /* file errno */
59 long fts_number; /* local numeric value */
60 void *fts_pointer; /* local address value */
61 struct ftsent *fts_parent; /* parent directory */
62 struct ftsent *fts_link; /* next file structure */
63 struct ftsent *fts_cycle; /* cycle structure */
64 struct stat *fts_statp; /* stat(2) information */
65 } FTSENT;
66 These fields are defined as follows:
68 fts_info One of the following flags describing the returned FTSENT
70 structure and the file it represents. With the exception
71 of directories without errors (FTS_D), all of these entries
72 are terminal, that is, they will not be revisited, nor will
73 any of their descendants be visited.
74 FTS_D A directory being visited in preorder.
76 FTS_DC A directory that causes a cycle in the tree.
78 (The fts_cycle field of the FTSENT structure
79 will be filled in as well.)
80 FTS_DEFAULT Any FTSENT structure that represents a file
82 type not explicitly described by one of the
83 other fts_info values.
84 FTS_DNR A directory which cannot be read. This is an
86 error return, and the fts_errno field will be
87 set to indicate what caused the error.
88 FTS_DOT A file named "." or ".." which was not speci‐
90 fied as a filename to fts_open() (see FTS_SEE‐
91 DOT).
92 FTS_DP A directory being visited in postorder. The
94 contents of the FTSENT structure will be
95 unchanged from when it was returned in pre‐
96 order, that is, with the fts_info field set to
97 FTS_D.
98 FTS_ERR This is an error return, and the fts_errno
100 field will be set to indicate what caused the
101 error.
102 FTS_F A regular file.
104 FTS_NS A file for which no stat(2) information was
106 available. The contents of the fts_statp field
107 are undefined. This is an error return, and
108 the fts_errno field will be set to indicate
109 what caused the error.
110 FTS_NSOK A file for which no stat(2) information was
112 requested. The contents of the fts_statp field
113 are undefined.
114 FTS_SL A symbolic link.
116 FTS_SLNONE A symbolic link with a nonexistent target. The
118 contents of the fts_statp field reference the
119 file characteristic information for the sym‐
120 bolic link itself.
121 fts_accpath A path for accessing the file from the current directory.
123 fts_path The path for the file relative to the root of the traver‐
125 sal. This path contains the path specified to fts_open()
126 as a prefix.
127 fts_pathlen The length of the string referenced by fts_path.
129 fts_name The name of the file.
131 fts_namelen The length of the string referenced by fts_name.
133 fts_level The depth of the traversal, numbered from -1 to N, where
135 this file was found. The FTSENT structure representing the
136 parent of the starting point (or root) of the traversal is
137 numbered -1, and the FTSENT structure for the root itself
138 is numbered 0.
139 fts_errno Upon return of a FTSENT structure from the fts_children()
141 or fts_read() functions, with its fts_info field set to
142 FTS_DNR, FTS_ERR or FTS_NS, the fts_errno field contains
143 the value of the external variable errno specifying the
144 cause of the error. Otherwise, the contents of the
145 fts_errno field are undefined.
146 fts_number This field is provided for the use of the application pro‐
148 gram and is not modified by the fts functions. It is ini‐
149 tialized to 0.
150 fts_pointer This field is provided for the use of the application pro‐
152 gram and is not modified by the fts functions. It is ini‐
153 tialized to NULL.
154 fts_parent A pointer to the FTSENT structure referencing the file in
156 the hierarchy immediately above the current file, that is,
157 the directory of which this file is a member. A parent
158 structure for the initial entry point is provided as well,
159 however, only the fts_level, fts_number and fts_pointer
160 fields are guaranteed to be initialized.
161 fts_link Upon return from the fts_children() function, the fts_link
163 field points to the next structure in the NULL-terminated
164 linked list of directory members. Otherwise, the contents
165 of the fts_link field are undefined.
166 fts_cycle If a directory causes a cycle in the hierarchy (see
168 FTS_DC), either because of a hard link between two directo‐
169 ries, or a symbolic link pointing to a directory, the
170 fts_cycle field of the structure will point to the FTSENT
171 structure in the hierarchy that references the same file as
172 the current FTSENT structure. Otherwise, the contents of
173 the fts_cycle field are undefined.
174 fts_statp A pointer to stat(2) information for the file.
176 A single buffer is used for all of the paths of all of the files in the
178 file hierarchy. Therefore, the fts_path and fts_accpath fields are
179 guaranteed to be null-terminated only for the file most recently
180 returned by fts_read(). To use these fields to reference any files
181 represented by other FTSENT structures will require that the path buf‐
182 fer be modified using the information contained in that FTSENT struc‐
183 ture's fts_pathlen field. Any such modifications should be undone
184 before further calls to fts_read() are attempted. The fts_name field
185 is always null-terminated.
186 fts_open()
188 The fts_open() function takes a pointer to an array of character point‐
189 ers naming one or more paths which make up a logical file hierarchy to
190 be traversed. The array must be terminated by a NULL pointer.
191 There are a number of options, at least one of which (either FTS_LOGI‐
193 CAL or FTS_PHYSICAL) must be specified. The options are selected by
194 ORing the following values:
195 FTS_COMFOLLOW
197 This option causes any symbolic link specified as a root
198 path to be followed immediately whether or not FTS_LOGICAL
199 is also specified.
200 FTS_LOGICAL This option causes the fts routines to return FTSENT
202 structures for the targets of symbolic links instead of
203 the symbolic links themselves. If this option is set, the
204 only symbolic links for which FTSENT structures are
205 returned to the application are those referencing nonexis‐
206 tent files. Either FTS_LOGICAL or FTS_PHYSICAL must be
207 provided to the fts_open() function.
208 FTS_NOCHDIR As a performance optimization, the fts functions change
210 directories as they walk the file hierarchy. This has the
211 side-effect that an application cannot rely on being in
212 any particular directory during the traversal. The
213 FTS_NOCHDIR option turns off this optimization, and the
214 fts functions will not change the current directory. Note
215 that applications should not themselves change their cur‐
216 rent directory and try to access files unless FTS_NOCHDIR
217 is specified and absolute pathnames were provided as argu‐
218 ments to fts_open().
219 FTS_NOSTAT By default, returned FTSENT structures reference file
221 characteristic information (the statp field) for each file
222 visited. This option relaxes that requirement as a per‐
223 formance optimization, allowing the fts functions to set
224 the fts_info field to FTS_NSOK and leave the contents of
225 the statp field undefined.
226 FTS_PHYSICAL This option causes the fts routines to return FTSENT
228 structures for symbolic links themselves instead of the
229 target files they point to. If this option is set, FTSENT
230 structures for all symbolic links in the hierarchy are
231 returned to the application. Either FTS_LOGICAL or
232 FTS_PHYSICAL must be provided to the fts_open() function.
233 FTS_SEEDOT By default, unless they are specified as path arguments to
235 fts_open(), any files named "." or ".." encountered in
236 the file hierarchy are ignored. This option causes the
237 fts routines to return FTSENT structures for them.
238 FTS_XDEV This option prevents fts from descending into directories
240 that have a different device number than the file from
241 which the descent began.
242 The argument compar() specifies a user-defined function which may be
244 used to order the traversal of the hierarchy. It takes two pointers to
245 pointers to FTSENT structures as arguments and should return a negative
246 value, zero, or a positive value to indicate if the file referenced by
247 its first argument comes before, in any order with respect to, or
248 after, the file referenced by its second argument. The fts_accpath,
249 fts_path and fts_pathlen fields of the FTSENT structures may never be
250 used in this comparison. If the fts_info field is set to FTS_NS or
251 FTS_NSOK, the fts_statp field may not either. If the compar() argument
252 is NULL, the directory traversal order is in the order listed in
253 path_argv for the root paths, and in the order listed in the directory
254 for everything else.
255 fts_read()
257 The fts_read() function returns a pointer to an FTSENT structure
258 describing a file in the hierarchy. Directories (that are readable and
259 do not cause cycles) are visited at least twice, once in preorder and
260 once in postorder. All other files are visited at least once. (Hard
261 links between directories that do not cause cycles or symbolic links to
262 symbolic links may cause files to be visited more than once, or direc‐
263 tories more than twice.)
264 If all the members of the hierarchy have been returned, fts_read()
266 returns NULL and sets the external variable errno to 0. If an error
267 unrelated to a file in the hierarchy occurs, fts_read() returns NULL
268 and sets errno appropriately. If an error related to a returned file
269 occurs, a pointer to an FTSENT structure is returned, and errno may or
270 may not have been set (see fts_info).
271 The FTSENT structures returned by fts_read() may be overwritten after a
273 call to fts_close() on the same file hierarchy stream, or, after a call
274 to fts_read() on the same file hierarchy stream unless they represent a
275 file of type directory, in which case they will not be overwritten
276 until after a call to fts_read() after the FTSENT structure has been
277 returned by the function fts_read() in postorder.
278 fts_children()
280 The fts_children() function returns a pointer to an FTSENT structure
281 describing the first entry in a NULL-terminated linked list of the
282 files in the directory represented by the FTSENT structure most
283 recently returned by fts_read(). The list is linked through the
284 fts_link field of the FTSENT structure, and is ordered by the user-
285 specified comparison function, if any. Repeated calls to fts_chil‐
286 dren() will recreate this linked list.
287 As a special case, if fts_read() has not yet been called for a hierar‐
289 chy, fts_children() will return a pointer to the files in the logical
290 directory specified to fts_open(), that is, the arguments specified to
291 fts_open(). Otherwise, if the FTSENT structure most recently returned
292 by fts_read() is not a directory being visited in preorder, or the
293 directory does not contain any files, fts_children() returns NULL and
294 sets errno to zero. If an error occurs, fts_children() returns NULL
295 and sets errno appropriately.
296 The FTSENT structures returned by fts_children() may be overwritten
298 after a call to fts_children(), fts_close() or fts_read() on the same
299 file hierarchy stream.
300 Option may be set to the following value:
302 FTS_NAMEONLY Only the names of the files are needed. The contents of
304 all the fields in the returned linked list of structures
305 are undefined with the exception of the fts_name and
306 fts_namelen fields.
307 fts_set()
309 The function fts_set() allows the user application to determine further
310 processing for the file f of the stream ftsp. The fts_set() function
311 returns 0 on success, and -1 if an error occurs. Option must be set to
312 one of the following values:
313 FTS_AGAIN Revisit the file; any file type may be revisited. The
315 next call to fts_read() will return the referenced file.
316 The fts_stat and fts_info fields of the structure will be
317 reinitialized at that time, but no other fields will have
318 been changed. This option is meaningful only for the most
319 recently returned file from fts_read(). Normal use is for
320 postorder directory visits, where it causes the directory
321 to be revisited (in both preorder and postorder) as well
322 as all of its descendants.
323 FTS_FOLLOW The referenced file must be a symbolic link. If the ref‐
325 erenced file is the one most recently returned by
326 fts_read(), the next call to fts_read() returns the file
327 with the fts_info and fts_statp fields reinitialized to
328 reflect the target of the symbolic link instead of the
329 symbolic link itself. If the file is one of those most
330 recently returned by fts_children(), the fts_info and
331 fts_statp fields of the structure, when returned by
332 fts_read(), will reflect the target of the symbolic link
333 instead of the symbolic link itself. In either case, if
334 the target of the symbolic link does not exist the fields
335 of the returned structure will be unchanged and the
336 fts_info field will be set to FTS_SLNONE.
337 If the target of the link is a directory, the preorder
339 return, followed by the return of all of its descendants,
340 followed by a postorder return, is done.
341 FTS_SKIP No descendants of this file are visited. The file may be
343 one of those most recently returned by either fts_chil‐
344 dren() or fts_read().
345 fts_close()
347 The fts_close() function closes a file hierarchy stream ftsp and
348 restores the current directory to the directory from which fts_open()
349 was called to open ftsp. The fts_close() function returns 0 on suc‐
350 cess, and -1 if an error occurs.
351
353 The function fts_open() may fail and set errno for any of the errors
354 specified for open(2) and malloc(3).
355 The function fts_close() may fail and set errno for any of the errors
357 specified for chdir(2) and close(2).
358 The functions fts_read() and fts_children() may fail and set errno for
360 any of the errors specified for chdir(2), malloc(3), opendir(3), read‐
361 dir(3) and stat(2).
362 In addition, fts_children(), fts_open() and fts_set() may fail and set
364 errno as follows:
365 EINVAL The options were invalid.
367
369 These functions are available in Linux since glibc2.
370
372 4.4BSD.
373
375 find(1), chdir(2), stat(2), ftw(3), qsort(3)
376
378 This page is part of release 3.53 of the Linux man-pages project. A
379 description of the project, and information about reporting bugs, can
380 be found at http://www.kernel.org/doc/man-pages/.
381Linux 2012-10-25 FTS(3)