1 .\" Copyright (c) 1993 Michael Haardt (michael@moria.de)
2 .\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
3 .\" and copyright (c) 2006 Justin Pryzby <justinpryzby@users.sf.net>
4 .\" and copyright (c) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
6 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
7 .\" This is free documentation; you can redistribute it and/or
8 .\" modify it under the terms of the GNU General Public License as
9 .\" published by the Free Software Foundation; either version 2 of
10 .\" the License, or (at your option) any later version.
12 .\" The GNU General Public License's references to "object code"
13 .\" and "executables" are to be interpreted as the output of any
14 .\" document formatting or typesetting system, including
15 .\" intermediate and printed output.
17 .\" This manual is distributed in the hope that it will be useful,
18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 .\" GNU General Public License for more details.
22 .\" You should have received a copy of the GNU General Public
23 .\" License along with this manual; if not, see
24 .\" <http://www.gnu.org/licenses/>.
27 .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu)
28 .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net>
29 .\" document FTW_ACTIONRETVAL; include .SH "RETURN VALUE";
30 .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> and
31 .\" Michael Kerrisk <mtk.manpages@gmail.com>
32 .\" reorganized and rewrote much of the page
33 .\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com>
34 .\" Added an example program.
35 .TH FTW 3 2014-12-31 "Linux" "Linux Programmer's Manual"
37 ftw, nftw \- file tree walk
42 .BI "int ftw(const char *" dirpath ,
43 .BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
44 .BI " int " typeflag ),
45 .BI " int " nopenfd );
47 .BR "#define _XOPEN_SOURCE 500" " /* See feature_test_macros(7) */"
50 .BI "int nftw(const char *" dirpath ,
51 .BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
52 .BI " int " typeflag ", struct FTW *" ftwbuf ),
53 .BI " int " nopenfd ", int " flags );
57 walks through the directory tree that is
58 located under the directory \fIdirpath\fP,
59 and calls \fIfn\fP() once for each entry in the tree.
60 By default, directories are handled before the files and
61 subdirectories they contain (preorder traversal).
63 To avoid using up all of the calling process's file descriptors,
64 \fInopenfd\fP specifies the maximum number of directories that
66 will hold open simultaneously.
68 the search depth exceeds this,
70 will become slower because
71 directories have to be closed and reopened.
74 one file descriptor for each level in the directory tree.
76 For each entry found in the tree,
79 \fIfn\fP() with three arguments:
85 is the pathname of the entry,
86 and is expressed either as a pathname relative to the calling process's
87 current working directory at the time of the call to
91 was expressed as a relative pathname,
92 or as an absolute pathname, if
94 was expressed as an absolute pathname.
98 structure returned by a call to
103 is an integer that has one of the following values:
115 is a directory which can't be read.
122 which is not a symbolic link.
123 The probable cause for this is that the caller had read permission
124 on the parent directory, so that the filename
127 but did not have execute permission,
128 so that the file could not be reached for
133 is a symbolic link and
135 failed, POSIX.1-2001 states
136 that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP (see below)
140 To stop the tree walk, \fIfn\fP() returns a nonzero value; this
141 value will become the return value of
143 As long as \fIfn\fP() returns 0,
145 will continue either until it has traversed the entire tree,
146 in which case it will return zero,
147 or until it encounters an error (such as a
149 failure), in which case it will return \-1.
153 uses dynamic data structures, the only safe way to
154 exit out of a tree walk is to return a nonzero value from \fIfn\fP().
155 To allow a signal to terminate the walk without causing a memory leak,
156 have the handler set a global flag that is checked by \fIfn\fP().
159 unless the program is going to terminate.
165 except that it has one additional argument, \fIflags\fP,
166 and calls \fIfn\fP() with one more argument, \fIftwbuf\fP.
168 This \fIflags\fP argument is formed by ORing zero or more of the
171 .BR FTW_ACTIONRETVAL " (since glibc 2.3.3)"
172 If this glibc-specific flag is set, then
174 handles the return value from
178 should return one of the following values:
184 to continue normally.
187 If \fIfn\fP() returns this value, then
188 siblings of the current entry will be skipped,
189 and processing continues in the parent.
190 .\" If \fBFTW_DEPTH\fP
191 .\" is set, the entry's parent directory is processed next (with
192 .\" \fIflag\fP set to \fBFTW_DP\fP).
195 If \fIfn\fP() is called with an entry that is a directory
196 (\fItypeflag\fP is \fBFTW_D\fP), this return
197 value will prevent objects within that directory from being passed as
198 arguments to \fIfn\fP().
200 continues processing with the next sibling of the directory.
205 to return immediately with the return value
208 Other return values could be associated with new actions in the future;
209 \fIfn\fP() should not return values other than those listed above.
211 The feature test macro
218 obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP.
224 to each directory before handling its contents.
225 This is useful if the program needs to perform some action
226 in the directory in which \fIfpath\fP resides.
227 (Specifying this flag has no effect on the pathname that is passed in the
233 If set, do a post-order traversal, that is, call \fIfn\fP() for
234 the directory itself \fIafter\fP handling the contents of the directory
235 and its subdirectories.
236 (By default, each directory is handled \fIbefore\fP its contents.)
239 If set, stay within the same filesystem
240 (i.e., do not cross mount points).
243 If set, do not follow symbolic links.
244 (This is what you want.)
245 If not set, symbolic links are followed, but no file is reported twice.
247 If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set,
250 is never called for a directory that would be a descendant of itself.
252 For each entry in the directory tree,
263 may receive any of the same values as with
265 or any of the following values:
269 is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP.
274 then directories will always be visited with
279 and subdirectories within \fIfpath\fP have been processed.
283 is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP.
284 .\" To obtain the definition of this constant from
288 .\" must be defined, or
289 .\" .BR _XOPEN_SOURCE
290 .\" must be defined with a value of 500 or more.
294 is a symbolic link pointing to a nonexistent file.
295 (This occurs only if \fBFTW_PHYS\fP is not set.)
297 The fourth argument that
299 supplies when calling
301 is a structure of type \fIFTW\fP:
313 is the offset of the filename (i.e., basename component)
314 in the pathname given in
319 in the directory tree, relative to the root of the tree
323 These functions return 0 on success, and \-1 if an error occurs.
325 If \fIfn\fP() returns nonzero,
326 then the tree walk is terminated and the value returned by \fIfn\fP()
327 is returned as the result of
334 is called with the \fBFTW_ACTIONRETVAL\fP flag,
335 then the only nonzero value that should be used by \fIfn\fP()
336 to terminate the tree walk is \fBFTW_STOP\fP,
337 and that value is returned as the result of
341 is available under glibc since version 2.1.
343 POSIX.1-2001, SVr4, SUSv1.
348 POSIX.1-2001 note that the results are unspecified if
350 does not preserve the current working directory.
354 and the use of \fBFTW_SL\fP with
356 were introduced in SUSv1.
360 will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only
361 for symbolic links that do not point to an existing file,
362 and again on other systems
364 will use \fBFTW_SL\fP for each symbolic link.
365 For predictable control, use
368 \fBFTW_F\fP is returned for all objects (files, symbolic links, FIFOs, etc.)
369 that can be stat'ed but are not a directory.
371 \fBFTW_ACTIONRETVAL\fP is glibc-specific.
373 The following program traverses the directory tree under the path named
374 in its first command-line argument, or under the current directory
375 if no argument is supplied.
376 It displays various information about each file.
377 The second command-line argument can be used to specify characters that
378 control the value assigned to the \fIflags\fP
379 argument when calling
383 #define _XOPEN_SOURCE 500
391 display_info(const char *fpath, const struct stat *sb,
392 int tflag, struct FTW *ftwbuf)
394 printf("%\-3s %2d %7jd %\-40s %d %s\\n",
395 (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" :
396 (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" :
397 (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" :
398 (tflag == FTW_SLN) ? "sln" : "???",
399 ftwbuf\->level, (intmax_t) sb\->st_size,
400 fpath, ftwbuf\->base, fpath + ftwbuf\->base);
401 return 0; /* To tell nftw() to continue */
405 main(int argc, char *argv[])
409 if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL)
411 if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL)
414 if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
427 This page is part of release 3.78 of the Linux
430 A description of the project,
431 information about reporting bugs,
432 and the latest version of this page,
434 \%http://www.kernel.org/doc/man\-pages/.