Print this page
1438 ftw(3C) should mention `quit' member of struct FTW and possible values
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/ftw.3c.man.txt
+++ new/usr/src/man/man3c/ftw.3c.man.txt
1 1 FTW(3C) Standard C Library Functions FTW(3C)
2 2
3 3
4 4
5 5 NAME
6 6 ftw, nftw - walk a file tree
7 7
8 8 SYNOPSIS
9 9 #include <ftw.h>
10 10
11 11 int ftw(const char *path, int (*fn) (const char *,
12 12 const struct stat *, int), int depth);
13 13
14 14
15 15 int nftw(const char *path, int (*fn) (const char *,
16 16 const struct stat *, int, struct FTW *), int depth,
17 17 int flags);
18 18
19 19
20 20 DESCRIPTION
21 21 The ftw() function recursively descends the directory hierarchy rooted
22 22 in path. For each object in the hierarchy, ftw() calls the user-defined
23 23 function fn, passing it a pointer to a null-terminated character string
24 24 containing the name of the object, a pointer to a stat structure (see
25 25 stat(2)) containing information about the object, and an integer.
26 26 Possible values of the integer, defined in the <ftw.h> header, are:
27 27
28 28 FTW_F
29 29 The object is a file.
30 30
31 31
32 32 FTW_D
33 33 The object is a directory.
34 34
35 35
36 36 FTW_DNR
37 37 The object is a directory that cannot be read. Descendants
38 38 of the directory are not processed.
39 39
40 40
41 41 FTW_NS
42 42 The stat() function failed on the object because of lack of
43 43 appropriate permission or the object is a symbolic link that
44 44 points to a non-existent file. The stat buffer passed to fn
45 45 is undefined.
46 46
47 47
48 48
49 49 The ftw() function visits a directory before visiting any of its
50 50 descendants.
51 51
52 52
53 53 The tree traversal continues until the tree is exhausted, an invocation
54 54 of fn returns a non-zero value, or some error is detected within ftw()
55 55 (such as an I/O error). If the tree is exhausted, ftw() returns 0. If
56 56 fn returns a non-zero value, ftw() stops its tree traversal and returns
57 57 whatever value was returned by fn.
58 58
59 59
60 60 The nftw() function is similar to ftw() except that it takes the
61 61 additional argument flags, which is a bitwise-inclusive OR of zero or
62 62 more of the following flags:
63 63
64 64 FTW_CHDIR
65 65 If set, nftw() changes the current working directory to
66 66 each directory as it reports files in that directory. If
67 67 clear, nftw() does not change the current working
68 68 directory.
69 69
70 70
71 71 FTW_DEPTH
72 72 If set, nftw() reports all files in a directory before
73 73 reporting the directory itself. If clear, nftw() reports
74 74 any directory before reporting the files in that
75 75 directory.
76 76
77 77
78 78 FTW_MOUNT
79 79 If set, nftw() reports only files in the same file system
80 80 as path. If clear, nftw() reports all files encountered
81 81 during the walk.
82 82
83 83
84 84 FTW_PHYS
85 85 If set, nftw() performs a physical walk and does not
86 86 follow symbolic links.
87 87
88 88
89 89
90 90 If FTW_PHYS is clear and FTW_DEPTH is set, nftw() follows links instead
91 91 of reporting them, but does not report any directory that would be a
92 92 descendant of itself. If FTW_PHYS is clear and FTW_DEPTH is clear,
93 93 nftw() follows links instead of reporting them, but does not report the
94 94 contents of any directory that would be a descendant of itself.
95 95
96 96
97 97 At each file it encounters, nftw() calls the user-supplied function fn
98 98 with four arguments:
99 99
100 100 o The first argument is the pathname of the object.
101 101
102 102 o The second argument is a pointer to the stat buffer
103 103 containing information on the object.
104 104
105 105 o The third argument is an integer giving additional
106 106 information. Its value is one of the following:
107 107
108 108
109 109 FTW_F
110 110 The object is a file.
111 111
112 112
113 113 FTW_D
114 114 The object is a directory.
115 115
116 116
117 117 FTW_DP
118 118 The object is a directory and subdirectories have
119 119 been visited. (This condition only occurs if the
120 120 FTW_DEPTH flag is included in flags.)
121 121
122 122
123 123 FTW_SL
124 124 The object is a symbolic link. (This condition
125 125 only occurs if the FTW_PHYS flag is included in
126 126 flags.)
127 127
128 128
129 129 FTW_SLN
130 130 The object is a symbolic link that points to a
131 131 non-existent file. (This condition only occurs if
132 132 the FTW_PHYS flag is not included in flags.)
133 133
134 134
135 135 FTW_DNR
136 136 The object is a directory that cannot be read.
137 137 The user-defined function fn will not be called
138 138 for any of its descendants.
139 139
140 140
141 141 FTW_NS
142 142 The stat() function failed on the object because
|
↓ open down ↓ |
142 lines elided |
↑ open up ↑ |
143 143 of lack of appropriate permission. The stat
144 144 buffer passed to fn is undefined. Failure of
145 145 stat() for any other reason is considered an
146 146 error and nftw() returns 1.
147 147
148 148
149 149
150 150 o The fourth argument is a pointer to an FTW structure that
151 151 contains the following members:
152 152
153 + int quit;
153 154 int base;
154 155 int level;
155 156
157 + The quit member has a default value of 0, but can be set to
158 + the following values:
159 +
160 +
161 + FTW_SKIP or FTW_PRUNE
162 + This object and its descendants are pruned from
163 + the search.
164 +
165 +
166 + FTW_FOLLOW
167 + If this object is a symbolic link, follow the
168 + link to its physical counterpart.
169 +
170 +
156 171 The base member is the offset of the object's filename in
157 172 the pathname passed as the first argument to fn(). The value
158 173 of level indicates the depth relative to the root of the
159 174 walk, where the root level is 0.
160 175
161 176 The results are unspecified if the application-supplied fn()
162 177 function does not preserve the current working directory.
163 178
164 179
165 - Both ftw() and nftw() use one file descriptor for each level in the
166 - tree. The depth argument limits the number of file descriptors used. If
167 - depth is zero or negative, the effect is the same as if it were 1. It
168 - must not be greater than the number of file descriptors currently
169 - available for use. The ftw() function runs faster if depth is at least
170 - as large as the number of levels in the tree. Both ftw() and nftw() are
171 - able to descend to arbitrary depths in a file hierarchy and do not fail
172 - due to path length limitations unless either the length of the path
173 - name pointed to by the path argument exceeds {PATH_MAX} requirements,
174 - or for ftw(), the specified depth is less than 2, or for nftw(), the
175 - specified depth is less than 2 and FTW_CHDIR is not set. When ftw() and
176 - nftw() return, they close any file descriptors they have opened; they
177 - do not close any file descriptors that might have been opened by fn.
180 + Both ftw() and nftw() use one file descriptor for each level in the
181 + tree. The depth argument limits the number of file descriptors
182 + used. If depth is zero or negative, the effect is the same as if it
183 + were 1. It must not be greater than the number of file descriptors
184 + currently available for use. The ftw() function runs faster if
185 + depth is at least as large as the number of levels in the tree.
186 + Both ftw() and nftw() are able to descend to arbitrary depths in a
187 + file hierarchy and do not fail due to path length limitations
188 + unless either the length of the path name pointed to by the path
189 + argument exceeds {PATH_MAX} requirements, or for ftw(), the
190 + specified depth is less than 2, or for nftw(), the specified depth
191 + is less than 2 and FTW_CHDIR is not set. When ftw() and nftw()
192 + return, they close any file descriptors they have opened; they do
193 + not close any file descriptors that might have been opened by fn.
178 194
179 195 RETURN VALUES
180 196 If the tree is exhausted, ftw() and nftw() return 0. If the function
181 197 pointed to by fn returns a non-zero value, ftw() and nftw() stop their
182 198 tree traversal and return whatever value was returned by the function
183 199 pointed to by fn. If ftw() and nftw() detect an error, they return1
184 200 and set errno to indicate the error.
185 201
186 202
187 203 If ftw() and nftw() encounter an error other than EACCES (see FTW_DNR
188 204 and FTW_NS above), they return1 and set errno to indicate the error.
189 205 The external variable errno can contain any error value that is
190 206 possible when a directory is opened or when one of the stat functions
191 207 is executed on a directory or file.
192 208
193 209 ERRORS
194 210 The ftw() and nftw() functions will fail if:
195 211
196 212 ELOOP
197 213 A loop exists in symbolic links encountered during
198 214 resolution of the path argument
199 215
200 216
201 217 ENAMETOOLONG
202 218 The length of the path name pointed to by the path
203 219 argument exceeds {PATH_MAX}, or a path name component
204 220 is longer than {NAME_MAX}.
205 221
206 222
207 223 ENOENT
208 224 A component of path does not name an existing file or
209 225 path is an empty string.
210 226
211 227
212 228 ENOTDIR
213 229 A component of path is not a directory.
214 230
215 231
216 232 EOVERFLOW
217 233 A field in the stat structure cannot be represented
218 234 correctly in the current programming environment for
219 235 one or more files found in the file hierarchy.
220 236
221 237
222 238
223 239 The ftw() function will fail if:
224 240
225 241 EACCES
226 242 Search permission is denied for any component of path
227 243 or read permission is denied for path.
228 244
229 245
230 246 ENAMETOOLONG
231 247 The ftw() function has descended to a path that exceeds
232 248 {PATH_MAX} and the depth argument specified by the
233 249 application is less than 2 and FTW_CHDIR is not set.
234 250
235 251
236 252
237 253 The nftw() function will fail if:
238 254
239 255 EACCES
240 256 Search permission is denied for any component of path or read
241 257 permission is denied for path, or fn() returns 1 and does not
242 258 reset errno.
243 259
244 260
245 261
246 262 The nftw() and ftw() functions may fail if:
247 263
248 264 ELOOP
249 265 Too many symbolic links were encountered during
250 266 resolution of the path argument.
251 267
252 268
253 269 ENAMETOOLONG
254 270 Pathname resolution of a symbolic link in the path name
255 271 pointed to by the path argument produced an
256 272 intermediate result whose length exceeds {PATH_MAX}.
257 273
258 274
259 275
260 276 The ftw() function may fail if:
261 277
262 278 EINVAL
263 279 The value of the depth argument is invalid.
264 280
265 281
266 282
267 283 The nftw() function may fail if:
268 284
269 285 EMFILE
270 286 There are {OPEN_MAX} file descriptors currently open in the
271 287 calling process.
272 288
273 289
274 290 ENFILE
275 291 Too many files are currently open in the system.
276 292
277 293
278 294
279 295 If the function pointed to by fn encounters system errors, errno may be
280 296 set accordingly.
281 297
282 298 EXAMPLES
283 299 Example 1 Walk a directory structure using ftw().
284 300
285 301
286 302 The following example walks the current directory structure, calling
287 303 the fn() function for every directory entry, using at most 10 file
288 304 descriptors:
289 305
290 306
291 307 #include <ftw.h>
292 308 ...
293 309 if (ftw(".", fn, 10) != 0) {
294 310 perror("ftw"); exit(2);
295 311 }
296 312
297 313
298 314 Example 2 Walk a directory structure using nftw().
299 315
300 316
301 317 The following example walks the /tmp directory and its subdirectories,
302 318 calling the nftw() function for every directory entry, to a maximum of
303 319 5 levels deep.
304 320
305 321
306 322 #include <ftw.h>
307 323 ...
308 324 int nftwfunc(const char *, const struct stat *, int, struct FTW *);
309 325 int nftwfunc(const char *filename, const struct stat *statptr,
310 326 int fileflags, struct FTW *pfwt)
311 327 {
312 328 return 0;
313 329 }
314 330 ...
315 331 char *startpath = "/tmp";
316 332 int depth = 5;
317 333 int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
318 334 int ret;
319 335 ret = nftw(startpath, nftwfunc, depth, flags);
320 336
321 337
322 338 USAGE
323 339 Because ftw() and nftw() are recursive, they can terminate with a
324 340 memory fault when applied by a thread with a small stack to very deep
325 341 file structures.
326 342
327 343
328 344 The ftw() and nftw() functions allocate resources (memory, file
329 345 descriptors) during their operation. If ftw() they are forcibly
330 346 terminated, such as by longjmp(3C) being executed by fn or an interrupt
331 347 routine, they will not have a chance to free those resources, so they
332 348 remain permanently allocated. A safe way to handle interrupts is to
333 349 store the fact that an interrupt has occurred and arrange to have fn
334 350 return a non-zero value at its next invocation.
335 351
336 352
337 353 The ftw() and nftw() functions have transitional interfaces for 64-bit
338 354 file offsets. See lf64(5).
339 355
340 356
341 357 The ftw() function is safe in multithreaded applications. The nftw()
342 358 function is safe in multithreaded applications when the FTW_CHDIR flag
343 359 is not set.
344 360
345 361 ATTRIBUTES
346 362 See attributes(5) for descriptions of the following attributes:
347 363
348 364
349 365
350 366
351 367 +--------------------+-------------------------+
352 368 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
353 369 +--------------------+-------------------------+
354 370 |Interface Stability | Standard |
355 371 +--------------------+-------------------------+
356 372 |MT-Level | MT-Safe with exceptions |
357 373 +--------------------+-------------------------+
358 374
359 375 SEE ALSO
360 376 stat(2), longjmp(3C), attributes(5), lf64(5), standards(5)
361 377
362 378
363 379
364 380 January 30, 2007 FTW(3C)
|
↓ open down ↓ |
177 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX