1FTW(3) Linux Programmer's Manual FTW(3)
2
6 ftw, nftw - file tree walk
7
9 #include <ftw.h>
10 int ftw(const char *dirpath,
12 int (*fn) (const char *fpath, const struct stat *sb,
13 int typeflag),
14 int nopenfd);
15 #define _XOPEN_SOURCE 500
17 #include <ftw.h>
18 int nftw(const char *dirpath,
20 int (*fn) (const char *fpath, const struct stat *sb,
21 int typeflag, struct FTW *ftwbuf),
22 int nopenfd, int flags);
23
25 ftw() walks through the directory tree that is located under the direc‐
26 tory dirpath, and calls fn() once for each entry in the tree. By
27 default, directories are handled before the files and subdirectories
28 they contain (pre-order traversal).
29 To avoid using up all of the calling process's file descriptors,
31 nopenfd specifies the maximum number of directories that ftw() will
32 hold open simultaneously. When the search depth exceeds this, ftw()
33 will become slower because directories have to be closed and reopened.
34 ftw() uses at most one file descriptor for each level in the directory
35 tree.
36 For each entry found in the tree, ftw() calls fn() with three argu‐
38 ments: fpath, sb, and typeflag. fpath is the pathname of the entry
39 relative to dirpath. sb is a pointer to the stat structure returned by
40 a call to stat(2) for fpath. typeflag is an integer that has one of
41 the following values:
42 FTW_F fpath is a regular file.
44 FTW_D fpath is a directory.
46 FTW_DNR
48 fpath is a directory which can't be read.
49 FTW_NS The stat(2) call failed on fpath, which is not a symbolic link.
51 If fpath is a symbolic link and stat(2) failed, POSIX.1-2001
53 states that it is undefined whether FTW_NS or FTW_SL (see below)
54 is passed in typeflag.
55 To stop the tree walk, fn() returns a non-zero value; this value will
57 become the return value of ftw(). As long as fn() returns 0, ftw()
58 will continue either until it has traversed the entire tree, in which
59 case it will return zero, or until it encounters an error (such as a
60 malloc(3) failure), in which case it will return -1.
61 Because ftw() uses dynamic data structures, the only safe way to exit
63 out of a tree walk is to return a non-zero value from fn(). To allow a
64 signal to terminate the walk without causing a memory leak, have the
65 handler set a global flag that is checked by fn(). Don't use
66 longjmp(3) unless the program is going to terminate.
67 nftw()
69 The function nftw() is the same as ftw(), except that it has one addi‐
70 tional argument, flags, and calls fn() with one more argument, ftwbuf.
71 This flags argument is formed by ORing zero or more of the following
73 flags:
74 FTW_ACTIONRETVAL (since glibc 2.3.3)
76 If this glibc-specific flag is set, then nftw() handles the
77 return value from fn() differently. fn() should return one of
78 the following values:
79 FTW_CONTINUE
81 Instructs nftw() to continue normally.
82 FTW_SKIP_SIBLINGS
84 If fn() returns this value, then siblings of the current
85 entry will be skipped, and processing continues in the
86 parent.
87 FTW_SKIP_SUBTREE
89 If fn() is called with an entry that is a directory
90 (typeflag is FTW_D), this return value will prevent
91 objects within that directory from being passed as argu‐
92 ments to fn(). nftw() continues processing with the next
93 sibling of the directory.
94 FTW_STOP
96 Causes nftw() to return immediately with the return value
97 FTW_STOP.
98 Other return values could be associated with new actions in the
100 future; fn() should not return values other than those listed
101 above.
102 The feature test macro _GNU_SOURCE must be defined in order to
104 obtain the definition of FTW_ACTIONRETVAL from <ftw.h>.
105 FTW_CHDIR
107 If set, do a chdir(2) to each directory before handling its con‐
108 tents. This is useful if the program needs to perform some
109 action in the directory in which fpath resides.
110 FTW_DEPTH
112 If set, do a post-order traversal, that is, call fn() for the
113 directory itself after handling the contents of the directory
114 and its subdirectories. (By default, each directory is handled
115 before its contents.)
116 FTW_MOUNT
118 If set, stay within the same file system (i.e., do not cross
119 mount points).
120 FTW_PHYS
122 If set, do not follow symbolic links. (This is what you want.)
123 If not set, symbolic links are followed, but no file is reported
124 twice.
125 If FTW_PHYS is not set, but FTW_DEPTH is set, then the function
127 fn() is never called for a directory that would be a descendant
128 of itself.
129 For each entry in the directory tree, nftw() calls fn() with four argu‐
131 ments. fpath and sb are as for ftw(). typeflag may receive any of the
132 same values as with ftw(), or any of the following values:
133 FTW_DP fpath is a directory, and FTW_DEPTH was specified in flags. All
135 of the files and subdirectories within fpath have been pro‐
136 cessed.
137 FTW_SL fpath is a symbolic link, and FTW_PHYS was set in flags.
139 FTW_SLN
141 fpath is a symbolic link pointing to a nonexistent file. (This
142 occurs only if FTW_PHYS is not set.)
143 The fourth argument that nftw() supplies when calling fn() is a struc‐
145 ture of type FTW:
146 struct FTW {
148 int base;
149 int level;
150 };
151 base is the offset of the filename (i.e., basename component) in the
153 pathname given in fpath. level is the depth of fpath in the directory
154 tree, relative to the root of the tree (dirpath, which has depth 0).
155
157 These functions return 0 on success, and -1 if an error occurs.
158 If fn() returns non-zero, then the tree walk is terminated and the
160 value returned by fn() is returned as the result of ftw() or nftw().
161 If nftw() is called with the FTW_ACTIONRETVAL flag, then the only non-
163 zero value that should be used by fn() to terminate the tree walk is
164 FTW_STOP, and that value is returned as the result of nftw().
165
167 POSIX.1-2001, SVr4, SUSv1. POSIX.1-2008 marks ftw() as obsolete.
168
170 The function nftw() and the use of FTW_SL with ftw() were introduced in
171 SUSv1.
172 On some systems ftw() will never use FTW_SL, on other systems FTW_SL
174 occurs only for symbolic links that do not point to an existing file,
175 and again on other systems ftw() will use FTW_SL for each symbolic
176 link. For predictable control, use nftw().
177 Under Linux, libc4 and libc5 and glibc 2.0.6 will use FTW_F for all
179 objects (files, symbolic links, FIFOs, etc.) that can be stat'ed but
180 are not a directory.
181 The function nftw() is available since glibc 2.1.
183 FTW_ACTIONRETVAL is glibc-specific.
185
187 The following program traverses the directory tree under the path named
188 in its first command-line argument, or under the current directory if
189 no argument is supplied. It displays various information about each
190 file. The second command-line argument can be used to specify charac‐
191 ters that control the value assigned to the flags argument when calling
192 nftw().
193 #define _XOPEN_SOURCE 500
195 #include <ftw.h>
196 #include <stdio.h>
197 #include <stdlib.h>
198 #include <string.h>
199 #include <stdint.h>
200 static int
202 display_info(const char *fpath, const struct stat *sb,
203 int tflag, struct FTW *ftwbuf)
204 {
205 printf("%-3s %2d %7jd %-40s %d %s\n",
206 (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" :
207 (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" :
208 (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" :
209 (tflag == FTW_SLN) ? "sln" : "???",
210 ftwbuf->level, (intmax_t) sb->st_size,
211 fpath, ftwbuf->base, fpath + ftwbuf->base);
212 return 0; /* To tell nftw() to continue */
213 }
214 int
216 main(int argc, char *argv[])
217 {
218 int flags = 0;
219 if (argc > 2 && strchr(argv[2], 'd') != NULL)
221 flags |= FTW_DEPTH;
222 if (argc > 2 && strchr(argv[2], 'p') != NULL)
223 flags |= FTW_PHYS;
224 if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
226 == -1) {
227 perror("nftw");
228 exit(EXIT_FAILURE);
229 }
230 exit(EXIT_SUCCESS);
231 }
232
234 stat(2), fts(3), readdir(3), feature_test_macros(7)
235
237 This page is part of release 3.22 of the Linux man-pages project. A
238 description of the project, and information about reporting bugs, can
239 be found at http://www.kernel.org/doc/man-pages/.
240Linux 2008-08-06 FTW(3)