1ftw(3C) Standard C Library Functions ftw(3C)
2
6 ftw, nftw - walk a file tree
7
9 #include <ftw.h>
10 int ftw(const char *path, int (*fn) (const char *,
12 const struct stat *, int), int depth);
13 int nftw(const char *path, int (*fn) (const char *,
16 const struct stat *, int, struct FTW *), int depth,
17 int flags);
18
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. Pos‐
26 sible values of the integer, defined in the <ftw.h> header, are:
27 FTW_F The object is a file.
29 FTW_D The object is a directory.
32 FTW_DNR The object is a directory that cannot be read. Descendants
35 of the directory are not processed.
36 FTW_NS The stat() function failed on the object because of lack of
39 appropriate permission or the object is a symbolic link that
40 points to a non-existent file. The stat buffer passed to fn
41 is undefined.
42 The ftw() function visits a directory before visiting any of its
46 descendants.
47 The tree traversal continues until the tree is exhausted, an invocation
50 of fn returns a non-zero value, or some error is detected within ftw()
51 (such as an I/O error). If the tree is exhausted, ftw() returns 0. If
52 fn returns a non-zero value, ftw() stops its tree traversal and returns
53 whatever value was returned by fn.
54 The nftw() function is similar to ftw() except that it takes the addi‐
57 tional argument flags, which is a bitwise-inclusive OR of zero or more
58 of the following flags:
59 FTW_CHDIR If set, nftw() changes the current working directory to
61 each directory as it reports files in that directory. If
62 clear, nftw() does not change the current working direc‐
63 tory.
64 FTW_DEPTH If set, nftw() reports all files in a directory before
67 reporting the directory itself. If clear, nftw() reports
68 any directory before reporting the files in that direc‐
69 tory.
70 FTW_MOUNT If set, nftw() reports only files in the same file system
73 as path. If clear, nftw() reports all files encountered
74 during the walk.
75 FTW_PHYS If set, nftw() performs a physical walk and does not fol‐
78 low symbolic links.
79 If FTW_PHYS is clear and FTW_DEPTH is set, nftw() follows links instead
83 of reporting them, but does not report any directory that would be a
84 descendant of itself. If FTW_PHYS is clear and FTW_DEPTH is clear,
85 nftw() follows links instead of reporting them, but does not report the
86 contents of any directory that would be a descendant of itself.
87 At each file it encounters, nftw() calls the user-supplied function fn
90 with four arguments:
91 o The first argument is the pathname of the object.
93 o The second argument is a pointer to the stat buffer contain‐
95 ing information on the object.
96 o The third argument is an integer giving additional informa‐
98 tion. Its value is one of the following:
99 FTW_F The object is a file.
102 FTW_D The object is a directory.
105 FTW_DP The object is a directory and subdirectories have
108 been visited. (This condition only occurs if the
109 FTW_DEPTH flag is included in flags.)
110 FTW_SL The object is a symbolic link. (This condition
113 only occurs if the FTW_PHYS flag is included in
114 flags.)
115 FTW_SLN The object is a symbolic link that points to a
118 non-existent file. (This condition only occurs if
119 the FTW_PHYS flag is not included in flags.)
120 FTW_DNR The object is a directory that cannot be read.
123 The user-defined function fn will not be called
124 for any of its descendants.
125 FTW_NS The stat() function failed on the object because
128 of lack of appropriate permission. The stat buf‐
129 fer passed to fn is undefined. Failure of stat()
130 for any other reason is considered an error and
131 nftw() returns −1.
132 o The fourth argument is a pointer to an FTW structure that
136 contains the following members:
137 int base;
139 int level;
140 The base member is the offset of the object's filename in
142 the pathname passed as the first argument to fn(). The value
143 of level indicates the depth relative to the root of the
144 walk, where the root level is 0.
145 The results are unspecified if the application-supplied fn()
147 function does not preserve the current working directory.
148 Both ftw() and nftw() use one file descriptor for each level in the
151 tree. The depth argument limits the number of file descriptors used. If
152 depth is zero or negative, the effect is the same as if it were 1. It
153 must not be greater than the number of file descriptors currently
154 available for use. The ftw() function runs faster if depth is at least
155 as large as the number of levels in the tree. Both ftw() and nftw() are
156 able to descend to arbitrary depths in a file hierarchy and do not fail
157 due to path length limitations unless either the length of the path
158 name pointed to by the path argument exceeds {PATH_MAX} requirements,
159 or for ftw(), the specified depth is less than 2, or for nftw(), the
160 specified depth is less than 2 and FTW_CHDIR is not set. When ftw() and
161 nftw() return, they close any file descriptors they have opened; they
162 do not close any file descriptors that might have been opened by fn.
163
165 If the tree is exhausted, ftw() and nftw() return 0. If the function
166 pointed to by fn returns a non-zero value, ftw() and nftw() stop their
167 tree traversal and return whatever value was returned by the function
168 pointed to by fn. If ftw() and nftw() detect an error, they return −1
169 and set errno to indicate the error.
170 If ftw() and nftw() encounter an error other than EACCES (see FTW_DNR
173 and FTW_NS above), they return −1 and set errno to indicate the error.
174 The external variable errno can contain any error value that is possi‐
175 ble when a directory is opened or when one of the stat functions is
176 executed on a directory or file.
177
179 The ftw() and nftw() functions will fail if:
180 ELOOP A loop exists in symbolic links encountered during res‐
182 olution of the path argument
183 ENAMETOOLONG The length of the path name pointed to by the path
186 argument exceeds {PATH_MAX}, or a path name component
187 is longer than {NAME_MAX}.
188 ENOENT A component of path does not name an existing file or
191 path is an empty string.
192 ENOTDIR A component of path is not a directory.
195 EOVERFLOW A field in the stat structure cannot be represented
198 correctly in the current programming environment for
199 one or more files found in the file hierarchy.
200 The ftw() function will fail if:
204 EACCES Search permission is denied for any component of path
206 or read permission is denied for path.
207 ENAMETOOLONG The ftw() function has descended to a path that exceeds
210 {PATH_MAX} and the depth argument specified by the
211 application is less than 2 and FTW_CHDIR is not set.
212 The nftw() function will fail if:
216 EACCES Search permission is denied for any component of path or read
218 permission is denied for path, or fn() returns −1 and does
219 not reset errno.
220 The nftw() and ftw() functions may fail if:
224 ELOOP Too many symbolic links were encountered during resolu‐
226 tion of the path argument.
227 ENAMETOOLONG Pathname resolution of a symbolic link in the path name
230 pointed to by the path argument produced an intermedi‐
231 ate result whose length exceeds {PATH_MAX}.
232 The ftw() function may fail if:
236 EINVAL The value of the depth argument is invalid.
238 The nftw() function may fail if:
242 EMFILE There are {OPEN_MAX} file descriptors currently open in the
244 calling process.
245 ENFILE Too many files are currently open in the system.
248 If the function pointed to by fn encounters system errors, errno may be
252 set accordingly.
253
255 Example 1 Walk a directory structure using ftw().
256 The following example walks the current directory structure, calling
259 the fn() function for every directory entry, using at most 10 file
260 descriptors:
261 #include <ftw.h>
264 ...
265 if (ftw(".", fn, 10) != 0) {
266 perror("ftw"); exit(2);
267 }
268 Example 2 Walk a directory structure using nftw().
271 The following example walks the /tmp directory and its subdirectories,
274 calling the nftw() function for every directory entry, to a maximum of
275 5 levels deep.
276 #include <ftw.h>
279 ...
280 int nftwfunc(const char *, const struct stat *, int, struct FTW *);
281 int nftwfunc(const char *filename, const struct stat *statptr,
282 int fileflags, struct FTW *pfwt)
283 {
284 return 0;
285 }
286 ...
287 char *startpath = "/tmp";
288 int depth = 5;
289 int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
290 int ret;
291 ret = nftw(startpath, nftwfunc, depth, flags);
292
295 Because ftw() and nftw() are recursive, they can terminate with a mem‐
296 ory fault when applied by a thread with a small stack to very deep file
297 structures.
298 The ftw() and nftw() functions allocate resources (memory, file
301 descriptors) during their operation. If ftw() they are forcibly termi‐
302 nated, such as by longjmp(3C) being executed by fn or an interrupt rou‐
303 tine, they will not have a chance to free those resources, so they
304 remain permanently allocated. A safe way to handle interrupts is to
305 store the fact that an interrupt has occurred and arrange to have fn
306 return a non-zero value at its next invocation.
307 The ftw() and nftw() functions have transitional interfaces for 64-bit
310 file offsets. See lf64(5).
311 The ftw() function is safe in multithreaded applications. The nftw()
314 function is safe in multithreaded applications when the FTW_CHDIR flag
315 is not set.
316
318 See attributes(5) for descriptions of the following attributes:
319 ┌─────────────────────────────┬─────────────────────────────┐
324 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
325 ├─────────────────────────────┼─────────────────────────────┤
326 │Interface Stability │Standard │
327 ├─────────────────────────────┼─────────────────────────────┤
328 │MT-Level │MT-Safe with exceptions │
329 └─────────────────────────────┴─────────────────────────────┘
330
332 stat(2), longjmp(3C), attributes(5), lf64(5), standards(5)
333SunOS 5.11 30 Jan 2007 ftw(3C)