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