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
+++ new/usr/src/man/man3c/ftw.3c
1 1 '\" te
2 2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 3 .\" Copyright 1989 AT&T
4 4 .\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved.
5 5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
6 6 .\" http://www.opengroup.org/bookstore/.
7 7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
8 8 .\" This notice shall appear on any product containing this material.
9 9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
10 10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
11 11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
12 12 .TH FTW 3C "Jan 30, 2007"
13 13 .SH NAME
14 14 ftw, nftw \- walk a file tree
15 15 .SH SYNOPSIS
16 16 .LP
17 17 .nf
18 18 #include <ftw.h>
19 19
20 20 \fBint\fR \fBftw\fR(\fBconst char *\fR\fIpath\fR, \fBint\fR (*\fIfn\fR) (\fBconst char *\fR,
21 21 \fBconst struct stat *\fR, \fBint\fR), \fBint\fR \fIdepth\fR);
22 22 .fi
23 23
24 24 .LP
25 25 .nf
26 26 \fBint\fR \fBnftw\fR(\fBconst char *\fR\fIpath\fR, \fBint (*\fR\fIfn\fR) (\fBconst char *\fR,
27 27 \fBconst struct stat *\fR, \fBint\fR, \fBstruct FTW *\fR), \fBint\fR \fIdepth\fR,
28 28 \fBint\fR \fIflags\fR);
29 29 .fi
30 30
31 31 .SH DESCRIPTION
32 32 .sp
33 33 .LP
34 34 The \fBftw()\fR function recursively descends the directory hierarchy rooted in
35 35 \fIpath\fR. For each object in the hierarchy, \fBftw()\fR calls the
36 36 user-defined function \fIfn\fR, passing it a pointer to a null-terminated
37 37 character string containing the name of the object, a pointer to a \fBstat\fR
38 38 structure (see \fBstat\fR(2)) containing information about the object, and an
39 39 integer. Possible values of the integer, defined in the <\fBftw.h\fR> header,
40 40 are:
41 41 .sp
42 42 .ne 2
43 43 .na
44 44 \fB\fBFTW_F\fR\fR
45 45 .ad
46 46 .RS 11n
47 47 The object is a file.
48 48 .RE
49 49
50 50 .sp
51 51 .ne 2
52 52 .na
53 53 \fB\fBFTW_D\fR\fR
54 54 .ad
55 55 .RS 11n
56 56 The object is a directory.
57 57 .RE
58 58
59 59 .sp
60 60 .ne 2
61 61 .na
62 62 \fB\fBFTW_DNR\fR\fR
63 63 .ad
64 64 .RS 11n
65 65 The object is a directory that cannot be read. Descendants of the directory are
66 66 not processed.
67 67 .RE
68 68
69 69 .sp
70 70 .ne 2
71 71 .na
72 72 \fB\fBFTW_NS\fR\fR
73 73 .ad
74 74 .RS 11n
75 75 The \fBstat()\fR function failed on the object because of lack of appropriate
76 76 permission or the object is a symbolic link that points to a non-existent file.
77 77 The \fBstat\fR buffer passed to \fIfn\fR is undefined.
78 78 .RE
79 79
80 80 .sp
81 81 .LP
82 82 The \fBftw()\fR function visits a directory before visiting any of its
83 83 descendants.
84 84 .sp
85 85 .LP
86 86 The tree traversal continues until the tree is exhausted, an invocation of
87 87 \fIfn\fR returns a non-zero value, or some error is detected within \fBftw()\fR
88 88 (such as an I/O error). If the tree is exhausted, \fBftw()\fR returns \fB0\fR.
89 89 If \fIfn\fR returns a non-zero value, \fBftw()\fR stops its tree traversal and
90 90 returns whatever value was returned by \fIfn\fR.
91 91 .sp
92 92 .LP
93 93 The \fBnftw()\fR function is similar to \fBftw()\fR except that it takes the
94 94 additional argument \fIflags\fR, which is a bitwise-inclusive OR of zero or
95 95 more of the following flags:
96 96 .sp
97 97 .ne 2
98 98 .na
99 99 \fB\fBFTW_CHDIR\fR\fR
100 100 .ad
101 101 .RS 13n
102 102 If set, \fBnftw()\fR changes the current working directory to each directory as
103 103 it reports files in that directory. If clear, \fBnftw()\fR does not change the
104 104 current working directory.
105 105 .RE
106 106
107 107 .sp
108 108 .ne 2
109 109 .na
110 110 \fB\fBFTW_DEPTH\fR\fR
111 111 .ad
112 112 .RS 13n
113 113 If set, \fBnftw()\fR reports all files in a directory before reporting the
114 114 directory itself. If clear, \fBnftw()\fR reports any directory before reporting
115 115 the files in that directory.
116 116 .RE
117 117
118 118 .sp
119 119 .ne 2
120 120 .na
121 121 \fB\fBFTW_MOUNT\fR\fR
122 122 .ad
123 123 .RS 13n
124 124 If set, \fBnftw()\fR reports only files in the same file system as path. If
125 125 clear, \fBnftw()\fR reports all files encountered during the walk.
126 126 .RE
127 127
128 128 .sp
129 129 .ne 2
130 130 .na
131 131 \fB\fBFTW_PHYS\fR\fR
132 132 .ad
133 133 .RS 13n
134 134 If set, \fBnftw()\fR performs a physical walk and does not follow symbolic
135 135 links.
136 136 .RE
137 137
138 138 .sp
139 139 .LP
140 140 If \fBFTW_PHYS\fR is clear and \fBFTW_DEPTH\fR is set, \fBnftw()\fR follows
141 141 links instead of reporting them, but does not report any directory that would
142 142 be a descendant of itself. If \fBFTW_PHYS\fR is clear and \fBFTW_DEPTH\fR is
143 143 clear, \fBnftw()\fR follows links instead of reporting them, but does not
144 144 report the contents of any directory that would be a descendant of itself.
145 145 .sp
146 146 .LP
147 147 At each file it encounters, \fBnftw()\fR calls the user-supplied function
148 148 \fIfn\fR with four arguments:
149 149 .RS +4
150 150 .TP
151 151 .ie t \(bu
152 152 .el o
153 153 The first argument is the pathname of the object.
154 154 .RE
155 155 .RS +4
156 156 .TP
157 157 .ie t \(bu
158 158 .el o
159 159 The second argument is a pointer to the \fBstat\fR buffer containing
160 160 information on the object.
161 161 .RE
162 162 .RS +4
163 163 .TP
164 164 .ie t \(bu
165 165 .el o
166 166 The third argument is an integer giving additional information. Its value is
167 167 one of the following:
168 168 .RS
169 169
170 170 .sp
171 171 .ne 2
172 172 .na
173 173 \fB\fBFTW_F\fR\fR
174 174 .ad
175 175 .RS 11n
176 176 The object is a file.
177 177 .RE
178 178
179 179 .sp
180 180 .ne 2
181 181 .na
182 182 \fB\fBFTW_D\fR\fR
183 183 .ad
184 184 .RS 11n
185 185 The object is a directory.
186 186 .RE
187 187
188 188 .sp
189 189 .ne 2
190 190 .na
191 191 \fB\fBFTW_DP\fR\fR
192 192 .ad
193 193 .RS 11n
194 194 The object is a directory and subdirectories have been visited. (This condition
195 195 only occurs if the FTW_DEPTH flag is included in flags.)
196 196 .RE
197 197
198 198 .sp
199 199 .ne 2
200 200 .na
201 201 \fB\fBFTW_SL\fR\fR
202 202 .ad
203 203 .RS 11n
204 204 The object is a symbolic link. (This condition only occurs if the FTW_PHYS flag
205 205 is included in flags.)
206 206 .RE
207 207
208 208 .sp
209 209 .ne 2
210 210 .na
211 211 \fB\fBFTW_SLN\fR\fR
212 212 .ad
213 213 .RS 11n
214 214 The object is a symbolic link that points to a non-existent file. (This
215 215 condition only occurs if the FTW_PHYS flag is not included in flags.)
216 216 .RE
217 217
218 218 .sp
219 219 .ne 2
220 220 .na
221 221 \fB\fBFTW_DNR\fR\fR
222 222 .ad
223 223 .RS 11n
224 224 The object is a directory that cannot be read. The user-defined function
225 225 \fIfn\fR will not be called for any of its descendants.
226 226 .RE
227 227
228 228 .sp
229 229 .ne 2
230 230 .na
231 231 \fB\fBFTW_NS\fR\fR
232 232 .ad
233 233 .RS 11n
234 234 The \fBstat()\fR function failed on the object because of lack of appropriate
235 235 permission. The stat buffer passed to \fIfn\fR is undefined. Failure of
236 236 \fBstat()\fR for any other reason is considered an error and \fBnftw()\fR
237 237 returns \(mi1.
238 238 .RE
239 239
240 240 .RE
241 241
|
↓ open down ↓ |
241 lines elided |
↑ open up ↑ |
242 242 .RE
243 243 .RS +4
244 244 .TP
245 245 .ie t \(bu
246 246 .el o
247 247 The fourth argument is a pointer to an \fBFTW\fR structure that contains the
248 248 following members:
249 249 .sp
250 250 .in +2
251 251 .nf
252 +int quit;
252 253 int base;
253 254 int level;
254 255 .fi
255 256 .in -2
256 257
258 +The \fBquit\fR member has a default value of \fI0\fR, but can be set to the
259 +following values:
260 +.RS
261 +
262 +.sp
263 +.ne 2
264 +.na
265 +\fB\fBFTW_SKIP\fR\fR or \fB\fBFTW_PRUNE\fR\fR
266 +.ad
267 +.RS 11n
268 +This object and its descendants are pruned from the search.
269 +.RE
270 +
271 +.sp
272 +.ne 2
273 +.na
274 +\fB\fBFTW_FOLLOW\fR\fR
275 +.ad
276 +.RS 11n
277 +If this object is a symbolic link, follow the link to its physical counterpart.
278 +.RE
279 +
280 +.sp
257 281 The \fBbase\fR member is the offset of the object's filename in the pathname
258 282 passed as the first argument to \fIfn\fR(). The value of \fBlevel\fR indicates
259 283 the depth relative to the root of the walk, where the root level is 0.
260 284 .sp
261 285 The results are unspecified if the application-supplied \fIfn\fR() function
262 286 does not preserve the current working directory.
263 287 .RE
264 288 .sp
265 289 .LP
266 290 Both \fBftw()\fR and \fBnftw()\fR use one file descriptor for each level in the
267 291 tree. The \fIdepth\fR argument limits the number of file descriptors used. If
268 292 \fIdepth\fR is zero or negative, the effect is the same as if it were 1. It
269 293 must not be greater than the number of file descriptors currently available for
270 294 use. The \fBftw()\fR function runs faster if \fIdepth\fR is at least as large
271 295 as the number of levels in the tree. Both \fBftw()\fR and \fBnftw()\fR are able
272 296 to descend to arbitrary depths in a file hierarchy and do not fail due to path
273 297 length limitations unless either the length of the path name pointed to by the
274 298 \fIpath\fR argument exceeds {\fBPATH_MAX\fR} requirements, or for \fBftw()\fR,
275 299 the specified depth is less than 2, or for \fBnftw()\fR, the specified depth is
276 300 less than 2 and \fBFTW_CHDIR\fR is not set. When \fBftw()\fR and \fBnftw()\fR
277 301 return, they close any file descriptors they have opened; they do not close any
278 302 file descriptors that might have been opened by \fIfn\fR.
279 303 .SH RETURN VALUES
280 304 .sp
281 305 .LP
282 306 If the tree is exhausted, \fBftw()\fR and \fBnftw()\fR return \fB0\fR. If the
283 307 function pointed to by \fIfn\fR returns a non-zero value, \fBftw()\fR and
284 308 \fBnftw()\fR stop their tree traversal and return whatever value was returned
285 309 by the function pointed to by \fIfn\fR. If \fBftw()\fR and \fBnftw()\fR detect
286 310 an error, they return \fB\(mi1\fR and set \fBerrno\fR to indicate the error.
287 311 .sp
288 312 .LP
289 313 If \fBftw()\fR and \fBnftw()\fR encounter an error other than \fBEACCES\fR (see
290 314 \fBFTW_DNR\fR and \fBFTW_NS\fR above), they return \fB\(mi1\fR and set
291 315 \fBerrno\fR to indicate the error. The external variable \fBerrno\fR can
292 316 contain any error value that is possible when a directory is opened or when one
293 317 of the \fBstat\fR functions is executed on a directory or file.
294 318 .SH ERRORS
295 319 .sp
296 320 .LP
297 321 The \fBftw()\fR and \fBnftw()\fR functions will fail if:
298 322 .sp
299 323 .ne 2
300 324 .na
301 325 \fB\fBELOOP\fR\fR
302 326 .ad
303 327 .RS 16n
304 328 A loop exists in symbolic links encountered during resolution of the \fIpath\fR
305 329 argument
306 330 .RE
307 331
308 332 .sp
309 333 .ne 2
310 334 .na
311 335 \fB\fBENAMETOOLONG\fR\fR
312 336 .ad
313 337 .RS 16n
314 338 The length of the path name pointed to by the \fIpath\fR argument exceeds
315 339 {\fBPATH_MAX\fR}, or a path name component is longer than {\fBNAME_MAX\fR}.
316 340 .RE
317 341
318 342 .sp
319 343 .ne 2
320 344 .na
321 345 \fB\fBENOENT\fR\fR
322 346 .ad
323 347 .RS 16n
324 348 A component of \fIpath\fR does not name an existing file or \fIpath\fR is an
325 349 empty string.
326 350 .RE
327 351
328 352 .sp
329 353 .ne 2
330 354 .na
331 355 \fB\fBENOTDIR\fR\fR
332 356 .ad
333 357 .RS 16n
334 358 A component of \fIpath\fR is not a directory.
335 359 .RE
336 360
337 361 .sp
338 362 .ne 2
339 363 .na
340 364 \fB\fBEOVERFLOW\fR\fR
341 365 .ad
342 366 .RS 16n
343 367 A field in the \fBstat\fR structure cannot be represented correctly in the
344 368 current programming environment for one or more files found in the file
345 369 hierarchy.
346 370 .RE
347 371
348 372 .sp
349 373 .LP
350 374 The \fBftw()\fR function will fail if:
351 375 .sp
352 376 .ne 2
353 377 .na
354 378 \fB\fBEACCES\fR\fR
355 379 .ad
356 380 .RS 16n
357 381 Search permission is denied for any component of \fIpath\fR or read permission
358 382 is denied for \fIpath\fR.
359 383 .RE
360 384
361 385 .sp
362 386 .ne 2
363 387 .na
364 388 \fB\fBENAMETOOLONG\fR\fR
365 389 .ad
366 390 .RS 16n
367 391 The \fBftw()\fR function has descended to a path that exceeds {\fBPATH_MAX\fR}
368 392 and the depth argument specified by the application is less than 2 and
369 393 \fBFTW_CHDIR\fR is not set.
370 394 .RE
371 395
372 396 .sp
373 397 .LP
374 398 The \fBnftw()\fR function will fail if:
375 399 .sp
376 400 .ne 2
377 401 .na
378 402 \fB\fBEACCES\fR\fR
379 403 .ad
380 404 .RS 10n
381 405 Search permission is denied for any component of \fIpath\fR or read permission
382 406 is denied for \fIpath\fR, or \fIfn\fR() returns \(mi1 and does not reset
383 407 \fBerrno\fR.
384 408 .RE
385 409
386 410 .sp
387 411 .LP
388 412 The \fBnftw()\fR and \fBftw()\fR functions may fail if:
389 413 .sp
390 414 .ne 2
391 415 .na
392 416 \fB\fBELOOP\fR\fR
393 417 .ad
394 418 .RS 16n
395 419 Too many symbolic links were encountered during resolution of the \fIpath\fR
396 420 argument.
397 421 .RE
398 422
399 423 .sp
400 424 .ne 2
401 425 .na
402 426 \fB\fBENAMETOOLONG\fR\fR
403 427 .ad
404 428 .RS 16n
405 429 Pathname resolution of a symbolic link in the path name pointed to by the
406 430 \fIpath\fR argument produced an intermediate result whose length exceeds
407 431 {\fBPATH_MAX\fR}.
408 432 .RE
409 433
410 434 .sp
411 435 .LP
412 436 The \fBftw()\fR function may fail if:
413 437 .sp
414 438 .ne 2
415 439 .na
416 440 \fB\fBEINVAL\fR\fR
417 441 .ad
418 442 .RS 10n
419 443 The value of the \fIdepth\fR argument is invalid.
420 444 .RE
421 445
422 446 .sp
423 447 .LP
424 448 The \fBnftw()\fR function may fail if:
425 449 .sp
426 450 .ne 2
427 451 .na
428 452 \fB\fBEMFILE\fR\fR
429 453 .ad
430 454 .RS 10n
431 455 There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling
432 456 process.
433 457 .RE
434 458
435 459 .sp
436 460 .ne 2
437 461 .na
438 462 \fB\fBENFILE\fR\fR
439 463 .ad
440 464 .RS 10n
441 465 Too many files are currently open in the system.
442 466 .RE
443 467
444 468 .sp
445 469 .LP
446 470 If the function pointed to by \fIfn\fR encounters system errors, \fBerrno\fR
447 471 may be set accordingly.
448 472 .SH EXAMPLES
449 473 .LP
450 474 \fBExample 1 \fRWalk a directory structure using \fBftw()\fR.
451 475 .sp
452 476 .LP
453 477 The following example walks the current directory structure, calling the
454 478 \fIfn\fR() function for every directory entry, using at most 10 file
455 479 descriptors:
456 480
457 481 .sp
458 482 .in +2
459 483 .nf
460 484 #include <ftw.h>
461 485 \&...
462 486 if (ftw(".", fn, 10) != 0) {
463 487 perror("ftw"); exit(2);
464 488 }
465 489 .fi
466 490 .in -2
467 491
468 492 .LP
469 493 \fBExample 2 \fRWalk a directory structure using \fBnftw()\fR.
470 494 .sp
471 495 .LP
472 496 The following example walks the \fB/tmp\fR directory and its subdirectories,
473 497 calling the \fBnftw()\fR function for every directory entry, to a maximum of 5
474 498 levels deep.
475 499
476 500 .sp
477 501 .in +2
478 502 .nf
479 503 #include <ftw.h>
480 504 \&...
481 505 int nftwfunc(const char *, const struct stat *, int, struct FTW *);
482 506 int nftwfunc(const char *filename, const struct stat *statptr,
483 507 int fileflags, struct FTW *pfwt)
484 508 {
485 509 return 0;
486 510 }
487 511 \&...
488 512 char *startpath = "/tmp";
489 513 int depth = 5;
490 514 int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
491 515 int ret;
492 516 ret = nftw(startpath, nftwfunc, depth, flags);
493 517 .fi
494 518 .in -2
495 519
496 520 .SH USAGE
497 521 .sp
498 522 .LP
499 523 Because \fBftw()\fR and \fBnftw()\fR are recursive, they can terminate with a
500 524 memory fault when applied by a thread with a small stack to very deep file
501 525 structures.
502 526 .sp
503 527 .LP
504 528 The \fBftw()\fR and \fBnftw()\fR functions allocate resources (memory, file
505 529 descriptors) during their operation. If \fBftw()\fR they are forcibly
506 530 terminated, such as by \fBlongjmp\fR(3C) being executed by \fIfn\fR or an
507 531 interrupt routine, they will not have a chance to free those resources, so they
508 532 remain permanently allocated. A safe way to handle interrupts is to store the
509 533 fact that an interrupt has occurred and arrange to have \fIfn\fR return a
510 534 non-zero value at its next invocation.
511 535 .sp
512 536 .LP
513 537 The \fBftw()\fR and \fBnftw()\fR functions have transitional interfaces for
514 538 64-bit file offsets. See \fBlf64\fR(5).
515 539 .sp
516 540 .LP
517 541 The \fBftw()\fR function is safe in multithreaded applications. The
518 542 \fBnftw()\fR function is safe in multithreaded applications when the
519 543 \fBFTW_CHDIR\fR flag is not set.
520 544 .SH ATTRIBUTES
521 545 .sp
522 546 .LP
523 547 See \fBattributes\fR(5) for descriptions of the following attributes:
524 548 .sp
525 549
526 550 .sp
527 551 .TS
528 552 box;
529 553 c | c
530 554 l | l .
531 555 ATTRIBUTE TYPE ATTRIBUTE VALUE
532 556 _
533 557 Interface Stability Standard
534 558 _
535 559 MT-Level MT-Safe with exceptions
536 560 .TE
537 561
538 562 .SH SEE ALSO
539 563 .sp
540 564 .LP
541 565 \fBstat\fR(2), \fBlongjmp\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5),
542 566 \fBstandards\fR(5)
|
↓ open down ↓ |
276 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX