1 FTW(3C) Standard C Library Functions FTW(3C)
2
3
4
5 NAME
6 ftw, nftw - walk a file tree
7
8 SYNOPSIS
9 #include <ftw.h>
10
11 int ftw(const char *path, int (*fn) (const char *,
12 const struct stat *, int), int depth);
13
14
15 int nftw(const char *path, int (*fn) (const char *,
16 const struct stat *, int, struct FTW *), int depth,
17 int flags);
18
19
20 DESCRIPTION
21 The ftw() function recursively descends the directory hierarchy rooted
22 in path. For each object in the hierarchy, ftw() calls the user-defined
23 function fn, passing it a pointer to a null-terminated character string
24 containing the name of the object, a pointer to a stat structure (see
25 stat(2)) containing information about the object, and an integer.
26 Possible values of the integer, defined in the <ftw.h> header, are:
27
28 FTW_F
29 The object is a file.
30
31
32 FTW_D
33 The object is a directory.
34
35
36 FTW_DNR
37 The object is a directory that cannot be read. Descendants
38 of the directory are not processed.
39
40
41 FTW_NS
42 The stat() function failed on the object because of lack of
43 appropriate permission or the object is a symbolic link that
44 points to a non-existent file. The stat buffer passed to fn
45 is undefined.
46
47
48
49 The ftw() function visits a directory before visiting any of its
50 descendants.
51
52
53 The tree traversal continues until the tree is exhausted, an invocation
54 of fn returns a non-zero value, or some error is detected within ftw()
55 (such as an I/O error). If the tree is exhausted, ftw() returns 0. If
56 fn returns a non-zero value, ftw() stops its tree traversal and returns
57 whatever value was returned by fn.
58
59
60 The nftw() function is similar to ftw() except that it takes the
61 additional argument flags, which is a bitwise-inclusive OR of zero or
62 more of the following flags:
63
64 FTW_CHDIR
65 If set, nftw() changes the current working directory to
66 each directory as it reports files in that directory. If
67 clear, nftw() does not change the current working
68 directory.
69
70
71 FTW_DEPTH
72 If set, nftw() reports all files in a directory before
73 reporting the directory itself. If clear, nftw() reports
74 any directory before reporting the files in that
75 directory.
76
77
78 FTW_MOUNT
79 If set, nftw() reports only files in the same file system
80 as path. If clear, nftw() reports all files encountered
81 during the walk.
82
83
84 FTW_PHYS
85 If set, nftw() performs a physical walk and does not
86 follow symbolic links.
87
88
89
90 If FTW_PHYS is clear and FTW_DEPTH is set, nftw() follows links instead
91 of reporting them, but does not report any directory that would be a
92 descendant of itself. If FTW_PHYS is clear and FTW_DEPTH is clear,
93 nftw() follows links instead of reporting them, but does not report the
94 contents of any directory that would be a descendant of itself.
95
96
97 At each file it encounters, nftw() calls the user-supplied function fn
98 with four arguments:
99
100 o The first argument is the pathname of the object.
101
102 o The second argument is a pointer to the stat buffer
103 containing information on the object.
104
105 o The third argument is an integer giving additional
106 information. Its value is one of the following:
107
108
109 FTW_F
110 The object is a file.
111
112
113 FTW_D
114 The object is a directory.
115
116
117 FTW_DP
118 The object is a directory and subdirectories have
119 been visited. (This condition only occurs if the
120 FTW_DEPTH flag is included in flags.)
121
122
123 FTW_SL
124 The object is a symbolic link. (This condition
125 only occurs if the FTW_PHYS flag is included in
126 flags.)
127
128
129 FTW_SLN
130 The object is a symbolic link that points to a
131 non-existent file. (This condition only occurs if
132 the FTW_PHYS flag is not included in flags.)
133
134
135 FTW_DNR
136 The object is a directory that cannot be read.
137 The user-defined function fn will not be called
138 for any of its descendants.
139
140
141 FTW_NS
142 The stat() function failed on the object because
143 of lack of appropriate permission. The stat
144 buffer passed to fn is undefined. Failure of
145 stat() for any other reason is considered an
146 error and nftw() returns 1.
147
148
149
150 o The fourth argument is a pointer to an FTW structure that
151 contains the following members:
152
153 int quit;
154 int base;
155 int level;
156
157 The quit member has a default value of 0, but can be set to
158 the following values:
159
160
161 FTW_SKIP or FTW_PRUNE
162 This object and its descendants are pruned from
163 the search.
164
165
166 FTW_FOLLOW
167 If this object is a symbolic link, follow the
168 link to its physical counterpart.
169
170
171 The base member is the offset of the object's filename in
172 the pathname passed as the first argument to fn(). The value
173 of level indicates the depth relative to the root of the
174 walk, where the root level is 0.
175
176 The results are unspecified if the application-supplied fn()
177 function does not preserve the current working directory.
178
179
180 Both ftw() and nftw() use one file descriptor for each level in the
181 tree. The depth argument limits the number of file descriptors
182 used. If depth is zero or negative, the effect is the same as if it
183 were 1. It must not be greater than the number of file descriptors
184 currently available for use. The ftw() function runs faster if
185 depth is at least as large as the number of levels in the tree.
186 Both ftw() and nftw() are able to descend to arbitrary depths in a
187 file hierarchy and do not fail due to path length limitations
188 unless either the length of the path name pointed to by the path
189 argument exceeds {PATH_MAX} requirements, or for ftw(), the
190 specified depth is less than 2, or for nftw(), the specified depth
191 is less than 2 and FTW_CHDIR is not set. When ftw() and nftw()
192 return, they close any file descriptors they have opened; they do
193 not close any file descriptors that might have been opened by fn.
194
195 RETURN VALUES
196 If the tree is exhausted, ftw() and nftw() return 0. If the function
197 pointed to by fn returns a non-zero value, ftw() and nftw() stop their
198 tree traversal and return whatever value was returned by the function
199 pointed to by fn. If ftw() and nftw() detect an error, they return1
200 and set errno to indicate the error.
201
202
203 If ftw() and nftw() encounter an error other than EACCES (see FTW_DNR
204 and FTW_NS above), they return1 and set errno to indicate the error.
205 The external variable errno can contain any error value that is
206 possible when a directory is opened or when one of the stat functions
207 is executed on a directory or file.
208
209 ERRORS
210 The ftw() and nftw() functions will fail if:
211
212 ELOOP
213 A loop exists in symbolic links encountered during
214 resolution of the path argument
215
216
217 ENAMETOOLONG
218 The length of the path name pointed to by the path
219 argument exceeds {PATH_MAX}, or a path name component
220 is longer than {NAME_MAX}.
221
222
223 ENOENT
224 A component of path does not name an existing file or
225 path is an empty string.
226
227
228 ENOTDIR
229 A component of path is not a directory.
230
231
232 EOVERFLOW
233 A field in the stat structure cannot be represented
234 correctly in the current programming environment for
235 one or more files found in the file hierarchy.
236
237
238
239 The ftw() function will fail if:
240
241 EACCES
242 Search permission is denied for any component of path
243 or read permission is denied for path.
244
245
246 ENAMETOOLONG
247 The ftw() function has descended to a path that exceeds
248 {PATH_MAX} and the depth argument specified by the
249 application is less than 2 and FTW_CHDIR is not set.
250
251
252
253 The nftw() function will fail if:
254
255 EACCES
256 Search permission is denied for any component of path or read
257 permission is denied for path, or fn() returns 1 and does not
258 reset errno.
259
260
261
262 The nftw() and ftw() functions may fail if:
263
264 ELOOP
265 Too many symbolic links were encountered during
266 resolution of the path argument.
267
268
269 ENAMETOOLONG
270 Pathname resolution of a symbolic link in the path name
271 pointed to by the path argument produced an
272 intermediate result whose length exceeds {PATH_MAX}.
273
274
275
276 The ftw() function may fail if:
277
278 EINVAL
279 The value of the depth argument is invalid.
280
281
282
283 The nftw() function may fail if:
284
285 EMFILE
286 There are {OPEN_MAX} file descriptors currently open in the
287 calling process.
288
289
290 ENFILE
291 Too many files are currently open in the system.
292
293
294
295 If the function pointed to by fn encounters system errors, errno may be
296 set accordingly.
297
298 EXAMPLES
299 Example 1 Walk a directory structure using ftw().
300
301
302 The following example walks the current directory structure, calling
303 the fn() function for every directory entry, using at most 10 file
304 descriptors:
305
306
307 #include <ftw.h>
308 ...
309 if (ftw(".", fn, 10) != 0) {
310 perror("ftw"); exit(2);
311 }
312
313
314 Example 2 Walk a directory structure using nftw().
315
316
317 The following example walks the /tmp directory and its subdirectories,
318 calling the nftw() function for every directory entry, to a maximum of
319 5 levels deep.
320
321
322 #include <ftw.h>
323 ...
324 int nftwfunc(const char *, const struct stat *, int, struct FTW *);
325 int nftwfunc(const char *filename, const struct stat *statptr,
326 int fileflags, struct FTW *pfwt)
327 {
328 return 0;
329 }
330 ...
331 char *startpath = "/tmp";
332 int depth = 5;
333 int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
334 int ret;
335 ret = nftw(startpath, nftwfunc, depth, flags);
336
337
338 USAGE
339 Because ftw() and nftw() are recursive, they can terminate with a
340 memory fault when applied by a thread with a small stack to very deep
341 file structures.
342
343
344 The ftw() and nftw() functions allocate resources (memory, file
345 descriptors) during their operation. If ftw() they are forcibly
346 terminated, such as by longjmp(3C) being executed by fn or an interrupt
347 routine, they will not have a chance to free those resources, so they
348 remain permanently allocated. A safe way to handle interrupts is to
349 store the fact that an interrupt has occurred and arrange to have fn
350 return a non-zero value at its next invocation.
351
352
353 The ftw() and nftw() functions have transitional interfaces for 64-bit
354 file offsets. See lf64(5).
355
356
357 The ftw() function is safe in multithreaded applications. The nftw()
358 function is safe in multithreaded applications when the FTW_CHDIR flag
359 is not set.
360
361 ATTRIBUTES
362 See attributes(5) for descriptions of the following attributes:
363
364
365
366
367 +--------------------+-------------------------+
368 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
369 +--------------------+-------------------------+
370 |Interface Stability | Standard |
371 +--------------------+-------------------------+
372 |MT-Level | MT-Safe with exceptions |
373 +--------------------+-------------------------+
374
375 SEE ALSO
376 stat(2), longjmp(3C), attributes(5), lf64(5), standards(5)
377
378
379
380 January 30, 2007 FTW(3C)