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-01-11 "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.
229 If set, do a post-order traversal, that is, call \fIfn\fP() for
230 the directory itself \fIafter\fP handling the contents of the directory
231 and its subdirectories.
232 (By default, each directory is handled \fIbefore\fP its contents.)
235 If set, stay within the same filesystem
236 (i.e., do not cross mount points).
239 If set, do not follow symbolic links.
240 (This is what you want.)
241 If not set, symbolic links are followed, but no file is reported twice.
243 If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set,
246 is never called for a directory that would be a descendant of itself.
248 For each entry in the directory tree,
259 may receive any of the same values as with
261 or any of the following values:
265 is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP.
270 then directories will always be visited with
275 and subdirectories within \fIfpath\fP have been processed.
279 is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP.
280 .\" To obtain the definition of this constant from
284 .\" must be defined, or
285 .\" .BR _XOPEN_SOURCE
286 .\" must be defined with a value of 500 or more.
290 is a symbolic link pointing to a nonexistent file.
291 (This occurs only if \fBFTW_PHYS\fP is not set.)
293 The fourth argument that
295 supplies when calling
297 is a structure of type \fIFTW\fP:
309 is the offset of the filename (i.e., basename component)
310 in the pathname given in
315 in the directory tree, relative to the root of the tree
319 These functions return 0 on success, and \-1 if an error occurs.
321 If \fIfn\fP() returns nonzero,
322 then the tree walk is terminated and the value returned by \fIfn\fP()
323 is returned as the result of
330 is called with the \fBFTW_ACTIONRETVAL\fP flag,
331 then the only nonzero value that should be used by \fIfn\fP()
332 to terminate the tree walk is \fBFTW_STOP\fP,
333 and that value is returned as the result of
336 POSIX.1-2001, SVr4, SUSv1.
341 POSIX.1-2001 note that the results are unspecified if
343 does not preserve the current working directory.
347 and the use of \fBFTW_SL\fP with
349 were introduced in SUSv1.
353 will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only
354 for symbolic links that do not point to an existing file,
355 and again on other systems
357 will use \fBFTW_SL\fP for each symbolic link.
358 For predictable control, use
361 Under Linux, libc4 and libc5 and glibc 2.0.6 will
362 use \fBFTW_F\fP for all objects (files, symbolic links, FIFOs, etc.)
363 that can be stat'ed but are not a directory.
367 is available since glibc 2.1.
369 \fBFTW_ACTIONRETVAL\fP is glibc-specific.
371 The following program traverses the directory tree under the path named
372 in its first command-line argument, or under the current directory
373 if no argument is supplied.
374 It displays various information about each file.
375 The second command-line argument can be used to specify characters that
376 control the value assigned to the \fIflags\fP
377 argument when calling
381 #define _XOPEN_SOURCE 500
389 display_info(const char *fpath, const struct stat *sb,
390 int tflag, struct FTW *ftwbuf)
392 printf("%\-3s %2d %7jd %\-40s %d %s\\n",
393 (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" :
394 (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" :
395 (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" :
396 (tflag == FTW_SLN) ? "sln" : "???",
397 ftwbuf\->level, (intmax_t) sb\->st_size,
398 fpath, ftwbuf\->base, fpath + ftwbuf\->base);
399 return 0; /* To tell nftw() to continue */
403 main(int argc, char *argv[])
407 if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL)
409 if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL)
412 if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
425 This page is part of release 3.68 of the Linux
428 A description of the project,
429 information about reporting bugs,
430 and the latest version of this page,
432 \%http://www.kernel.org/doc/man\-pages/.