1NFTW(3P) POSIX Programmer's Manual NFTW(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 nftw - walk a file tree
13
15 #include <ftw.h>
16 int nftw(const char *path, int (*fn)(const char *,
18 const struct stat *, int, struct FTW *), int depth, int flags);
19
22 The nftw() function shall recursively descend the directory hierarchy
23 rooted in path. The nftw() function has a similar effect to ftw()
24 except that it takes an additional argument flags, which is a bitwise-
25 inclusive OR of zero or more of the following flags:
26 FTW_CHDIR
28 If set, nftw() shall change the current working directory to
29 each directory as it reports files in that directory. If clear,
30 nftw() shall not change the current working directory.
31 FTW_DEPTH
33 If set, nftw() shall report all files in a directory before
34 reporting the directory itself. If clear, nftw() shall report
35 any directory before reporting the files in that directory.
36 FTW_MOUNT
38 If set, nftw() shall only report files in the same file system
39 as path. If clear, nftw() shall report all files encountered
40 during the walk.
41 FTW_PHYS
43 If set, nftw() shall perform a physical walk and shall not fol‐
44 low symbolic links.
45 If FTW_PHYS is clear and FTW_DEPTH is set, nftw() shall follow links
48 instead of reporting them, but shall not report any directory that
49 would be a descendant of itself. If FTW_PHYS is clear and FTW_DEPTH is
50 clear, nftw() shall follow links instead of reporting them, but shall
51 not report the contents of any directory that would be a descendant of
52 itself.
53 At each file it encounters, nftw() shall call the user-supplied func‐
55 tion fn with four arguments:
56 * The first argument is the pathname of the object.
58 * The second argument is a pointer to the stat buffer containing
60 information on the object.
61 * The third argument is an integer giving additional information. Its
63 value is one of the following:
64 FTW_F
66 The object is a file.
67 FTW_D
69 The object is a directory.
70 FTW_DP
72 The object is a directory and subdirectories have been visited.
73 (This condition shall only occur if the FTW_DEPTH flag is
74 included in flags.)
75 FTW_SL
77 The object is a symbolic link. (This condition shall only occur
78 if the FTW_PHYS flag is included in flags.)
79 FTW_SLN
81 The object is a symbolic link that does not name an existing
82 file. (This condition shall only occur if the FTW_PHYS flag is
83 not included in flags.)
84 FTW_DNR
86 The object is a directory that cannot be read. The fn function
87 shall not be called for any of its descendants.
88 FTW_NS
90 The stat() function failed on the object because of lack of
91 appropriate permission. The stat buffer passed to fn is unde‐
92 fined. Failure of stat() for any other reason is considered an
93 error and nftw() shall return -1.
94 * The fourth argument is a pointer to an FTW structure. The value of
97 base is the offset of the object's filename in the pathname passed
98 as the first argument to fn. The value of level indicates depth rel‐
99 ative to the root of the walk, where the root level is 0.
100 The results are unspecified if the application-supplied fn function
102 does not preserve the current working directory.
103 The argument depth sets the maximum number of file descriptors that
105 shall be used by nftw() while traversing the file tree. At most one
106 file descriptor shall be used for each directory level.
107 The nftw() function need not be reentrant. A function that is not
109 required to be reentrant is not required to be thread-safe.
110
112 The nftw() function shall continue until the first of the following
113 conditions occurs:
114 * An invocation of fn shall return a non-zero value, in which case
116 nftw() shall return that value.
117 * The nftw() function detects an error other than [EACCES] (see
119 FTW_DNR and FTW_NS above), in which case nftw() shall return -1 and
120 set errno to indicate the error.
121 * The tree is exhausted, in which case nftw() shall return 0.
123
125 The nftw() function shall fail if:
126 EACCES Search permission is denied for any component of path or read
128 permission is denied for path, or fn returns -1 and does not
129 reset errno.
130 ELOOP A loop exists in symbolic links encountered during resolution of
132 the path argument.
133 ENAMETOOLONG
135 The length of the path argument exceeds {PATH_MAX} or a pathname
136 component is longer than {NAME_MAX}.
137 ENOENT A component of path does not name an existing file or path is an
139 empty string.
140 ENOTDIR
142 A component of path is not a directory.
143 EOVERFLOW
145 A field in the stat structure cannot be represented correctly in
146 the current programming environment for one or more files found
147 in the file hierarchy.
148 The nftw() function may fail if:
151 ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
153 resolution of the path argument.
154 EMFILE {OPEN_MAX} file descriptors are currently open in the calling
156 process.
157 ENAMETOOLONG
159 Pathname resolution of a symbolic link produced an intermediate
160 result whose length exceeds {PATH_MAX}.
161 ENFILE Too many files are currently open in the system.
163 In addition, errno may be set if the function pointed to by fn causes
166 errno to be set.
167 The following sections are informative.
169
171 The following example walks the /tmp directory and its subdirectories,
172 calling the nftw() function for every directory entry, to a maximum of
173 5 levels deep.
174 #include <ftw.h>
177 ...
178 int nftwfunc(const char *, const struct stat *, int, struct FTW *);
179 int nftwfunc(const char *filename, const struct stat *statptr,
182 int fileflags, struct FTW *pfwt)
183 {
184 return 0;
185 }
186 ...
187 char *startpath = "/tmp";
188 int depth = 5;
189 int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
190 int ret;
191 ret = nftw(startpath, nftwfunc, depth, flags);
194
196 None.
197
199 None.
200
202 None.
203
205 lstat(), opendir(), readdir(), stat(), the Base Definitions volume of
206 IEEE Std 1003.1-2001, <ftw.h>
207
209 Portions of this text are reprinted and reproduced in electronic form
210 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
211 -- Portable Operating System Interface (POSIX), The Open Group Base
212 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
213 Electrical and Electronics Engineers, Inc and The Open Group. In the
214 event of any discrepancy between this version and the original IEEE and
215 The Open Group Standard, the original IEEE and The Open Group Standard
216 is the referee document. The original Standard can be obtained online
217 at http://www.opengroup.org/unix/online.html .
218IEEE/The Open Group 2003 NFTW(3P)