1 .\" Copyright (c) 1993 Michael Haardt (michael@moria.de)
2 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
3 .\" Fri Jun 25 00:34:07 CEST 1999
5 .\" This is free documentation; you can redistribute it and/or
6 .\" modify it under the terms of the GNU General Public License as
7 .\" published by the Free Software Foundation; either version 2 of
8 .\" the License, or (at your option) any later version.
10 .\" The GNU General Public License's references to "object code"
11 .\" and "executables" are to be interpreted as the output of any
12 .\" document formatting or typesetting system, including
13 .\" intermediate and printed output.
15 .\" This manual is distributed in the hope that it will be useful,
16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 .\" GNU General Public License for more details.
20 .\" You should have received a copy of the GNU General Public
21 .\" License along with this manual; if not, write to the Free
22 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
25 .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu)
26 .TH FTW 3 1999-06-25 "Linux" "Linux Programmer's Manual"
28 ftw, nftw \- file tree walk
32 .BI "int ftw(const char *" dir ", int (*" fn ")(const"
33 .BI "char *" file ", const struct stat *" sb ", int " flag ),
36 .BI "int nftw(const char *" dir ", int (*" fn ")(const"
37 .BI "char *" file ", const struct stat *" sb ", int " flag ,
38 .BI "struct FTW *" s ),
39 .BI "int " nopenfd ", int " flags );
41 \fBftw\fP() walks through the directory tree starting from the indicated
42 directory \fIdir\fP. For each found entry in the tree, it calls
43 \fIfn\fP() with the full pathname of the entry, a pointer to the
45 structure for the entry and an int \fIflag\fP, which value will be one of
55 Item is a directory which can't be read
58 Item is a symbolic link
61 The stat failed on the item which is not a symbolic link
63 If the item is a symbolic link and stat failed, XPG4v2 states
64 that it is undefined whether FTW_NS or FTW_SL is used.
66 \fBftw\fP() recursively calls itself for traversing found directories,
67 handling a directory before its files or subdirectories.
68 To avoid using up all a program's file descriptors, \fInopenfd\fP
69 specifies the maximum number of simultaneous open directories. When
70 the search depth exceeds this, \fBftw\fP() will become slower because
71 directories have to be closed and reopened. \fBftw\fP() uses at most
72 one file descriptor for each level in the file hierarchy.
74 To stop the tree walk, \fIfn\fP() returns a non-zero value; this
75 value will become the return value of \fBftw\fP(). Otherwise,
76 \fBftw\fP() will continue until it has traversed the entire tree, in
77 which case it will return zero, or until it hits an error other than EACCES
80 failure), in which case it will return \-1.
82 Because \fBftw\fP() uses dynamic data structures, the only safe way to
83 exit out of a tree walk is to return a non-zero value. To handle
84 interrupts, for example, mark that the interrupt occurred and return a
85 non-zero value\(emdon't use
87 unless the program is going to terminate.
89 The function \fBnftw\fP() does precisely the same as \fBftw\fP(),
90 except that it has one additional argument \fIflags\fP
91 (and calls the supplied function with one more argument).
92 This \fIflags\fP argument is an OR of zero or more of the following flags:
97 to each directory before handling its contents.
100 If set, do a depth-first search, that is, call the function for
101 the directory itself only after handling the contents of the directory
102 and its subdirectories.
105 If set, stay within the same file system.
108 If set, do not follow symbolic links.
109 (This is what you want.)
110 If not set, symbolic links are followed, but no file is reported twice.
112 If FTW_PHYS is not set, but FTW_DEPTH is set, then the function
114 is never called for a directory that would be a descendant of itself.
118 is called with four arguments: the pathname of the reported entry,
119 a pointer to a struct stat for this entry, an integer describing
120 its type, and a pointer to a struct FTW. The type will be one
121 of the following: FTW_F, FTW_D, FTW_DNR, FTW_SL, FTW_NS
122 (with meaning as above; FTW_SL occurs only with FTW_PHYS set) or
125 Item is a directory and all its descendants have been handled
126 already. (This occurs only with FTW_DEPTH set.)
129 Item is a symbolic link pointing to a nonexisting file.
130 (This occurs only with FTW_PHYS unset.)
132 The struct FTW pointed to by the fourth argument to
134 has at least the fields
136 the offset of the item's filename in the pathname
137 given as first argument of
141 the depth of the item relative to the starting point
146 and the use of FTW_SL with
148 were introduced in XPG4v2.
152 will never use FTW_SL, on other systems FTW_SL occurs only
153 for symbolic links that do not point to an existing file,
154 and again on other systems
156 will use FTW_SL for each symbolic link. For predictable control, use
159 Under Linux, libc4 and libc5 and glibc 2.0.6 will
160 use FTW_F for all objects (files, symbolic links, fifos, etc)
161 that can be stat'ed but are not a directory.
164 is available since glibc 2.1.
166 AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2.