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