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) information */
70 } FTSENT;
71 These fields are defined as follows:
73 fts_info One of the following values describing the returned FTSENT
75 structure and the file it represents. With the exception
76 of directories without errors (FTS_D), all of these entries
77 are terminal, that is, they will not be revisited, nor will
78 any of their descendants be visited.
79 FTS_D A directory being visited in preorder.
81 FTS_DC A directory that causes a cycle in the tree.
83 (The fts_cycle field of the FTSENT structure
84 will be filled in as well.)
85 FTS_DEFAULT Any FTSENT structure that represents a file
87 type not explicitly described by one of the
88 other fts_info values.
89 FTS_DNR A directory which cannot be read. This is an
91 error return, and the fts_errno field will be
92 set to indicate what caused the error.
93 FTS_DOT A file named "." or ".." which was not speci‐
95 fied as a filename to fts_open() (see FTS_SEE‐
96 DOT).
97 FTS_DP A directory being visited in postorder. The
99 contents of the FTSENT structure will be
100 unchanged from when it was returned in pre‐
101 order, that is, with the fts_info field set to
102 FTS_D.
103 FTS_ERR This is an error return, and the fts_errno
105 field will be set to indicate what caused the
106 error.
107 FTS_F A regular file.
109 FTS_NS A file for which no stat(2) information was
111 available. The contents of the fts_statp field
112 are undefined. This is an error return, and
113 the fts_errno field will be set to indicate
114 what caused the error.
115 FTS_NSOK A file for which no stat(2) information was
117 requested. The contents of the fts_statp field
118 are undefined.
119 FTS_SL A symbolic link.
121 FTS_SLNONE A symbolic link with a nonexistent target. The
123 contents of the fts_statp field reference the
124 file characteristic information for the sym‐
125 bolic link itself.
126 fts_accpath A path for accessing the file from the current directory.
128 fts_path The path for the file relative to the root of the traver‐
130 sal. This path contains the path specified to fts_open()
131 as a prefix.
132 fts_pathlen The sum of the lengths of the strings referenced by
134 fts_path and fts_name.
135 fts_name The name of the file.
137 fts_namelen The length of the string referenced by fts_name.
139 fts_level The depth of the traversal, numbered from -1 to N, where
141 this file was found. The FTSENT structure representing the
142 parent of the starting point (or root) of the traversal is
143 numbered -1, and the FTSENT structure for the root itself
144 is numbered 0.
145 fts_errno If fts_children() or fts_read() returns an FTSENT structure
147 whose fts_info field is set to FTS_DNR, FTS_ERR, or FTS_NS,
148 the fts_errno field contains the error number (i.e., the
149 errno value) specifying the cause of the error. Otherwise,
150 the contents of the fts_errno field are undefined.
151 fts_number This field is provided for the use of the application pro‐
153 gram and is not modified by the fts functions. It is ini‐
154 tialized to 0.
155 fts_pointer This field is provided for the use of the application pro‐
157 gram and is not modified by the fts functions. It is ini‐
158 tialized to NULL.
159 fts_parent A pointer to the FTSENT structure referencing the file in
161 the hierarchy immediately above the current file, that is,
162 the directory of which this file is a member. A parent
163 structure for the initial entry point is provided as well,
164 however, only the fts_level, fts_number, and fts_pointer
165 fields are guaranteed to be initialized.
166 fts_link Upon return from the fts_children() function, the fts_link
168 field points to the next structure in the NULL-terminated
169 linked list of directory members. Otherwise, the contents
170 of the fts_link field are undefined.
171 fts_cycle If a directory causes a cycle in the hierarchy (see
173 FTS_DC), either because of a hard link between two directo‐
174 ries, or a symbolic link pointing to a directory, the
175 fts_cycle field of the structure will point to the FTSENT
176 structure in the hierarchy that references the same file as
177 the current FTSENT structure. Otherwise, the contents of
178 the fts_cycle field are undefined.
179 fts_statp A pointer to stat(2) information for the file.
181 A single buffer is used for all of the paths of all of the files in the
183 file hierarchy. Therefore, the fts_path and fts_accpath fields are
184 guaranteed to be null-terminated only for the file most recently
185 returned by fts_read(). To use these fields to reference any files
186 represented by other FTSENT structures will require that the path buf‐
187 fer be modified using the information contained in that FTSENT struc‐
188 ture's fts_pathlen field. Any such modifications should be undone
189 before further calls to fts_read() are attempted. The fts_name field
190 is always null-terminated.
191 fts_open()
193 The fts_open() function takes a pointer to an array of character point‐
194 ers naming one or more paths which make up a logical file hierarchy to
195 be traversed. The array must be terminated by a null pointer.
196 There are a number of options, at least one of which (either FTS_LOGI‐
198 CAL or FTS_PHYSICAL) must be specified. The options are selected by
199 ORing the following values:
200 FTS_COMFOLLOW This option causes any symbolic link specified as a root
202 path to be followed immediately whether or not FTS_LOGI‐
203 CAL is also specified.
204 FTS_LOGICAL This option causes the fts routines to return FTSENT
206 structures for the targets of symbolic links instead of
207 the symbolic links themselves. If this option is set,
208 the only symbolic links for which FTSENT structures are
209 returned to the application are those referencing nonex‐
210 istent files. Either FTS_LOGICAL or FTS_PHYSICAL must be
211 provided to the fts_open() function.
212 FTS_NOCHDIR As a performance optimization, the fts functions change
214 directories as they walk the file hierarchy. This has
215 the side-effect that an application cannot rely on being
216 in any particular directory during the traversal. The
217 FTS_NOCHDIR option turns off this optimization, and the
218 fts functions will not change the current directory.
219 Note that applications should not themselves change their
220 current directory and try to access files unless
221 FTS_NOCHDIR is specified and absolute pathnames were pro‐
222 vided as arguments to fts_open().
223 FTS_NOSTAT By default, returned FTSENT structures reference file
225 characteristic information (the statp field) for each
226 file visited. This option relaxes that requirement as a
227 performance optimization, allowing the fts functions to
228 set the fts_info field to FTS_NSOK and leave the contents
229 of the statp field undefined.
230 FTS_PHYSICAL This option causes the fts routines to return FTSENT
232 structures for symbolic links themselves instead of the
233 target files they point to. If this option is set,
234 FTSENT structures for all symbolic links in the hierarchy
235 are returned to the application. Either FTS_LOGICAL or
236 FTS_PHYSICAL must be provided to the fts_open() function.
237 FTS_SEEDOT By default, unless they are specified as path arguments
239 to fts_open(), any files named "." or ".." encountered
240 in the file hierarchy are ignored. This option causes
241 the fts routines to return FTSENT structures for them.
242 FTS_XDEV This option prevents fts from descending into directories
244 that have a different device number than the file from
245 which the descent began.
246 The argument compar() specifies a user-defined function which may be
248 used to order the traversal of the hierarchy. It takes two pointers to
249 pointers to FTSENT structures as arguments and should return a negative
250 value, zero, or a positive value to indicate if the file referenced by
251 its first argument comes before, in any order with respect to, or
252 after, the file referenced by its second argument. The fts_accpath,
253 fts_path, and fts_pathlen fields of the FTSENT structures may never be
254 used in this comparison. If the fts_info field is set to FTS_NS or
255 FTS_NSOK, the fts_statp field may not either. If the compar() argument
256 is NULL, the directory traversal order is in the order listed in
257 path_argv for the root paths, and in the order listed in the directory
258 for everything else.
259 fts_read()
261 The fts_read() function returns a pointer to an FTSENT structure
262 describing a file in the hierarchy. Directories (that are readable and
263 do not cause cycles) are visited at least twice, once in preorder and
264 once in postorder. All other files are visited at least once. (Hard
265 links between directories that do not cause cycles or symbolic links to
266 symbolic links may cause files to be visited more than once, or direc‐
267 tories more than twice.)
268 If all the members of the hierarchy have been returned, fts_read()
270 returns NULL and sets the external variable errno to 0. If an error
271 unrelated to a file in the hierarchy occurs, fts_read() returns NULL
272 and sets errno appropriately. If an error related to a returned file
273 occurs, a pointer to an FTSENT structure is returned, and errno may or
274 may not have been set (see fts_info).
275 The FTSENT structures returned by fts_read() may be overwritten after a
277 call to fts_close() on the same file hierarchy stream, or, after a call
278 to fts_read() on the same file hierarchy stream unless they represent a
279 file of type directory, in which case they will not be overwritten
280 until after a call to fts_read() after the FTSENT structure has been
281 returned by the function fts_read() in postorder.
282 fts_children()
284 The fts_children() function returns a pointer to an FTSENT structure
285 describing the first entry in a NULL-terminated linked list of the
286 files in the directory represented by the FTSENT structure most
287 recently returned by fts_read(). The list is linked through the
288 fts_link field of the FTSENT structure, and is ordered by the user-
289 specified comparison function, if any. Repeated calls to fts_chil‐
290 dren() will re-create this linked list.
291 As a special case, if fts_read() has not yet been called for a hierar‐
293 chy, fts_children() will return a pointer to the files in the logical
294 directory specified to fts_open(), that is, the arguments specified to
295 fts_open(). Otherwise, if the FTSENT structure most recently returned
296 by fts_read() is not a directory being visited in preorder, or the
297 directory does not contain any files, fts_children() returns NULL and
298 sets errno to zero. If an error occurs, fts_children() returns NULL
299 and sets errno appropriately.
300 The FTSENT structures returned by fts_children() may be overwritten
302 after a call to fts_children(), fts_close(), or fts_read() on the same
303 file hierarchy stream.
304 The instr argument is either zero or the following value:
306 FTS_NAMEONLY Only the names of the files are needed. The contents of
308 all the fields in the returned linked list of structures
309 are undefined with the exception of the fts_name and
310 fts_namelen fields.
311 fts_set()
313 The function fts_set() allows the user application to determine further
314 processing for the file f of the stream ftsp. The fts_set() function
315 returns 0 on success, and -1 if an error occurs.
316 The instr argument is either 0 (meaning "do nothing") or one of the
318 following values:
319 FTS_AGAIN Revisit the file; any file type may be revisited. The
321 next call to fts_read() will return the referenced file.
322 The fts_stat and fts_info fields of the structure will be
323 reinitialized at that time, but no other fields will have
324 been changed. This option is meaningful only for the most
325 recently returned file from fts_read(). Normal use is for
326 postorder directory visits, where it causes the directory
327 to be revisited (in both preorder and postorder) as well
328 as all of its descendants.
329 FTS_FOLLOW The referenced file must be a symbolic link. If the ref‐
331 erenced file is the one most recently returned by
332 fts_read(), the next call to fts_read() returns the file
333 with the fts_info and fts_statp fields reinitialized to
334 reflect the target of the symbolic link instead of the
335 symbolic link itself. If the file is one of those most
336 recently returned by fts_children(), the fts_info and
337 fts_statp fields of the structure, when returned by
338 fts_read(), will reflect the target of the symbolic link
339 instead of the symbolic link itself. In either case, if
340 the target of the symbolic link does not exist, the fields
341 of the returned structure will be unchanged and the
342 fts_info field will be set to FTS_SLNONE.
343 If the target of the link is a directory, the preorder
345 return, followed by the return of all of its descendants,
346 followed by a postorder return, is done.
347 FTS_SKIP No descendants of this file are visited. The file may be
349 one of those most recently returned by either fts_chil‐
350 dren() or fts_read().
351 fts_close()
353 The fts_close() function closes the file hierarchy stream referred to
354 by ftsp and restores the current directory to the directory from which
355 fts_open() was called to open ftsp. The fts_close() function returns 0
356 on success, and -1 if an error occurs.
357
359 The function fts_open() may fail and set errno for any of the errors
360 specified for open(2) and malloc(3).
361 The function fts_close() may fail and set errno for any of the errors
363 specified for chdir(2) and close(2).
364 The functions fts_read() and fts_children() may fail and set errno for
366 any of the errors specified for chdir(2), malloc(3), opendir(3), read‐
367 dir(3), and stat(2).
368 In addition, fts_children(), fts_open(), and fts_set() may fail and set
370 errno as follows:
371 EINVAL options or instr was invalid.
373
375 These functions are available in Linux since glibc2.
376
378 For an explanation of the terms used in this section, see
379 attributes(7).
380 ┌───────────────────────────────────┬───────────────┬───────────┐
382 │Interface │ Attribute │ Value │
383 ├───────────────────────────────────┼───────────────┼───────────┤
384 │fts_open(), fts_set(), fts_close() │ Thread safety │ MT-Safe │
385 ├───────────────────────────────────┼───────────────┼───────────┤
386 │fts_read(), fts_children() │ Thread safety │ MT-Unsafe │
387 └───────────────────────────────────┴───────────────┴───────────┘
388
390 4.4BSD.
391
393 In versions of glibc before 2.23, all of the APIs described in this man
394 page are not safe when compiling a program using the LFS APIs (e.g.,
395 when compiling with -D_FILE_OFFSET_BITS=64).
396
398 find(1), chdir(2), stat(2), ftw(3), qsort(3)
399
401 This page is part of release 4.16 of the Linux man-pages project. A
402 description of the project, information about reporting bugs, and the
403 latest version of this page, can be found at
404 https://www.kernel.org/doc/man-pages/.
405Linux 2018-02-02 FTS(3)