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 .\" This is free documentation; you can redistribute it and/or
7 .\" modify it under the terms of the GNU General Public License as
8 .\" published by the Free Software Foundation; either version 2 of
9 .\" the License, or (at your option) any later version.
11 .\" The GNU General Public License's references to "object code"
12 .\" and "executables" are to be interpreted as the output of any
13 .\" document formatting or typesetting system, including
14 .\" intermediate and printed output.
16 .\" This manual is distributed in the hope that it will be useful,
17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 .\" GNU General Public License for more details.
21 .\" You should have received a copy of the GNU General Public
22 .\" License along with this manual; if not, write to the Free
23 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
26 .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu)
27 .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net>
28 .\" document FTW_ACTIONRETVAL; include .SH "RETURN VALUE";
29 .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> and
30 .\" Michael Kerrisk <mtk.manpages@gmail.com>
31 .\" reorganized and rewrote much of the page
32 .\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com>
33 .\" Added an example program.
34 .TH FTW 3 2010-06-10 "Linux" "Linux Programmer's Manual"
36 ftw, nftw \- file tree walk
41 .BI "int ftw(const char *" dirpath ,
42 .BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
43 .BI " int " typeflag ),
44 .BI " int " nopenfd );
46 .B #define _XOPEN_SOURCE 500
49 .BI "int nftw(const char *" dirpath ,
50 .BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
51 .BI " int " typeflag ", struct FTW *" ftwbuf ),
52 .BI " int " nopenfd ", int " flags );
56 walks through the directory tree that is
57 located under the directory \fIdirpath\fP,
58 and calls \fIfn\fP() once for each entry in the tree.
59 By default, directories are handled before the files and
60 subdirectories they contain (preorder traversal).
62 To avoid using up all of the calling process's file descriptors,
63 \fInopenfd\fP specifies the maximum number of directories that
65 will hold open simultaneously.
67 the search depth exceeds this,
69 will become slower because
70 directories have to be closed and reopened.
73 one file descriptor for each level in the directory tree.
75 For each entry found in the tree,
78 \fIfn\fP() with three arguments:
84 is the pathname of the entry,
85 and is expressed either as a pathname relative to the calling process's
86 current working directory at the time of the call to
90 was expressed as a relative pathname,
91 or as an absolute pathname, if
93 was expressed as an absolute pathname.
97 structure returned by a call to
102 is an integer that has one of the following values:
114 is a directory which can't be read.
121 which is not a symbolic link.
125 is a symbolic link and
127 failed, POSIX.1-2001 states
128 that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP (see below)
132 To stop the tree walk, \fIfn\fP() returns a nonzero value; this
133 value will become the return value of
135 As long as \fIfn\fP() returns 0,
137 will continue either until it has traversed the entire tree,
138 in which case it will return zero,
139 or until it encounters an error (such as a
141 failure), in which case it will return \-1.
145 uses dynamic data structures, the only safe way to
146 exit out of a tree walk is to return a nonzero value from \fIfn\fP().
147 To allow a signal to terminate the walk without causing a memory leak,
148 have the handler set a global flag that is checked by \fIfn\fP().
151 unless the program is going to terminate.
157 except that it has one additional argument, \fIflags\fP,
158 and calls \fIfn\fP() with one more argument, \fIftwbuf\fP.
160 This \fIflags\fP argument is formed by ORing zero or more of the
163 .BR FTW_ACTIONRETVAL " (since glibc 2.3.3)"
164 If this glibc-specific flag is set, then
166 handles the return value from
170 should return one of the following values:
176 to continue normally.
179 If \fIfn\fP() returns this value, then
180 siblings of the current entry will be skipped,
181 and processing continues in the parent.
182 .\" If \fBFTW_DEPTH\fP
183 .\" is set, the entry's parent directory is processed next (with
184 .\" \fIflag\fP set to \fBFTW_DP\fP).
187 If \fIfn\fP() is called with an entry that is a directory
188 (\fItypeflag\fP is \fBFTW_D\fP), this return
189 value will prevent objects within that directory from being passed as
190 arguments to \fIfn\fP().
192 continues processing with the next sibling of the directory.
197 to return immediately with the return value
200 Other return values could be associated with new actions in the future;
201 \fIfn\fP() should not return values other than those listed above.
203 The feature test macro
205 must be defined in order to
206 obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP.
212 to each directory before handling its contents.
213 This is useful if the program needs to perform some action
214 in the directory in which \fIfpath\fP resides.
217 If set, do a post-order traversal, that is, call \fIfn\fP() for
218 the directory itself \fIafter\fP handling the contents of the directory
219 and its subdirectories.
220 (By default, each directory is handled \fIbefore\fP its contents.)
223 If set, stay within the same file system
224 (i.e., do not cross mount points).
227 If set, do not follow symbolic links.
228 (This is what you want.)
229 If not set, symbolic links are followed, but no file is reported twice.
231 If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set,
234 is never called for a directory that would be a descendant of itself.
236 For each entry in the directory tree,
247 may receive any of the same values as with
249 or any of the following values:
253 is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP.
255 and subdirectories within \fIfpath\fP have been processed.
259 is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP.
260 .\" To obtain the definition of this constant from
264 .\" must be defined, or
265 .\" .BR _XOPEN_SOURCE
266 .\" must be defined with a value of 500 or more.
270 is a symbolic link pointing to a nonexistent file.
271 (This occurs only if \fBFTW_PHYS\fP is not set.)
273 The fourth argument that
275 supplies when calling
277 is a structure of type \fIFTW\fP:
289 is the offset of the filename (i.e., basename component)
290 in the pathname given in
295 in the directory tree, relative to the root of the tree
299 These functions return 0 on success, and \-1 if an error occurs.
301 If \fIfn\fP() returns nonzero,
302 then the tree walk is terminated and the value returned by \fIfn\fP()
303 is returned as the result of
310 is called with the \fBFTW_ACTIONRETVAL\fP flag,
311 then the only nonzero value that should be used by \fIfn\fP()
312 to terminate the tree walk is \fBFTW_STOP\fP,
313 and that value is returned as the result of
316 POSIX.1-2001, SVr4, SUSv1.
321 POSIX.1-2001 note that the results are unspecified if
323 does not preserve the current working directory.
327 and the use of \fBFTW_SL\fP with
329 were introduced in SUSv1.
333 will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only
334 for symbolic links that do not point to an existing file,
335 and again on other systems
337 will use \fBFTW_SL\fP for each symbolic link.
338 For predictable control, use
341 Under Linux, libc4 and libc5 and glibc 2.0.6 will
342 use \fBFTW_F\fP for all objects (files, symbolic links, FIFOs, etc.)
343 that can be stat'ed but are not a directory.
347 is available since glibc 2.1.
349 \fBFTW_ACTIONRETVAL\fP is glibc-specific.
351 The following program traverses the directory tree under the path named
352 in its first command-line argument, or under the current directory
353 if no argument is supplied.
354 It displays various information about each file.
355 The second command-line argument can be used to specify characters that
356 control the value assigned to the \fIflags\fP
357 argument when calling
361 #define _XOPEN_SOURCE 500
369 display_info(const char *fpath, const struct stat *sb,
370 int tflag, struct FTW *ftwbuf)
372 printf("%\-3s %2d %7jd %\-40s %d %s\\n",
373 (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" :
374 (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" :
375 (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" :
376 (tflag == FTW_SLN) ? "sln" : "???",
377 ftwbuf\->level, (intmax_t) sb\->st_size,
378 fpath, ftwbuf\->base, fpath + ftwbuf\->base);
379 return 0; /* To tell nftw() to continue */
383 main(int argc, char *argv[])
387 if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL)
389 if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL)
392 if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
404 .BR feature_test_macros (7)