Penguin
Recent Changes
Annotated edit history of ftw(3) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 FTW
2 !!!FTW
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 NOTES
7 CONFORMING TO
8 SEE ALSO
9 ----
10 !!NAME
11
12
13 ftw, nftw - file tree walk
14 !!SYNOPSIS
15
16
17 __#include __
18
19
20 __int ftw (const char *__''dir''__, int
21 (*__''fn''__)(const char *__''file''__, const
22 struct stat *__''sb''__, int__ ''flag''__),
23 int__ ''depth''__);__
24
25
26 __int nftw (const char *__''dir''__, int
27 (*__''fn''__)(const char *__''file''__, const
28 struct stat *__''sb''__, int__ ''flag''__,
29 struct FTW *__''s''__), int__ ''depth''__,
30 int__ ''flags''__);__
31 !!DESCRIPTION
32
33
34 __ftw__() walks through the directory tree starting from
35 the indicated directory ''dir''. For each found entry in
36 the tree, it calls ''fn''() with the full pathname of the
37 entry, a pointer to the stat(2) structure for the
38 entry and an int ''flag'', which value will be one of the
39 following:
40
41
42 __FTW_F__
43
44
45 Item is a normal file
46
47
48 __FTW_D__
49
50
51 Item is a directory
52
53
54 __FTW_DNR__
55
56
57 Item is a directory which can't be read
58
59
60 __FTW_SL__
61
62
63 Item is a symbolic link
64
65
66 __FTW_NS__
67
68
69 The stat failed on the item which is not a symbolic
70 link
71
72
73 If the item is a symbolic link and stat failed, XPG4v2
74 states that it is undefined whether FTW_NS or FTW_SL is
75 used.
76
77
78 __ftw__() recursively calls itself for traversing found
79 directories, handling a directory before its files or
80 subdirectories. To avoid using up all a program's file
81 descriptors, the ''depth'' specifies the number of
82 simultaneous open directories. When the depth is exceeded,
83 __ftw__() will become slower because directories have to
84 be closed and reopened. __ftw__() uses at most one file
85 descriptor for each level in the file
86 hierarchy.
87
88
89 To stop the tree walk, ''fn''() returns a non-zero value;
90 this value will become the return value of __ftw__().
91 Otherwise, __ftw__() will continue until it has traversed
92 the entire tree, in which case it will return zero, or until
93 it hits an error other than EACCES (such as a
94 malloc(3) failure), in which case it will return
95 -1.
96
97
98 Because __ftw()__ uses dynamic data structures, the only
99 safe way to exit out of a tree walk is to return a non-zero
100 value. To handle interrupts, for example, mark that the
101 interrupt occurred and return a non-zero value--don't use
102 longjmp(3) unless the program is going to
103 terminate.
104
105
106 The function __nftw__() does precisely the same as
107 __ftw__(), except that it has one additional argument
108 ''flags'' (and calls the supplied function with one more
109 argument). This ''flags'' argument is an OR of zero or
110 more of the following flags:
111
112
113 __FTW_CHDIR__
114
115
116 If set, do a ''chdir''() to each directory before
117 handling its contents.
118
119
120 __FTW_DEPTH__
121
122
123 If set, do a depth-first search, that is, call the function
124 for the directory itself only after handling the contents of
125 the directory and its subdirectories.
126
127
128 __FTW_MOUNT__
129
130
131 If set, stay within the same file system.
132
133
134 __FTW_PHYS__
135
136
137 If set, do not follow symbolic links. (This is what you
138 want.) If not set, symbolic links are followed, but no file
139 is reported twice.
140
141
142 If FTW_PHYS is not set, but FTW_DEPTH is set, then the
143 function ''fn''() is never called for a directory that
144 would be a descendant of itself.
145
146
147 The function ''fn''() is called with four arguments: the
148 pathname of the reported entry, a pointer to a struct stat
149 for this entry, an integer describing its type, and a
150 pointer to a struct FTW. The type will be one of the
151 following: FTW_F, FTW_D, FTW_DNR, FTW_SL, FTW_NS (with
152 meaning as above; FTW_SL occurs only with FTW_PHYS set)
153 or
154
155
156 __FTW_DP__
157
158
159 Item is a directory and all its descendants have been
160 handled already. (This occurs only with FTW_DEPTH
161 set.)
162
163
164 __FTW_SLN__
165
166
167 Item is a symbolic link pointing to a nonexisting file.
168 (This occurs only with FTW_PHYS unset.)
169
170
171 The struct FTW pointed at by the fourth argument to
172 ''fn''() has at least the fields ''base'', the offset
173 of the item's filename in the pathname given as first
174 argument of ''fn''(), and ''level'', the depth of the
175 item relative to the starting point (which has depth
176 0).
177 !!NOTES
178
179
180 The function ''nftw''() and the use of FTW_SL with
181 ''ftw''() were introduced in XPG4v2. Under Linux, libc4
182 and libc5 and glibc 2.0.6 will use FTW_F for all objects
183 (files, symbolic links, fifos, etc) that can be stat'ed but
184 are not a directory. First glibc 2.1 supports FTW_SL and
185 ''nftw''().
186 !!CONFORMING TO
187
188
189 AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2.
190 !!SEE ALSO
191
192
193 stat(2)
194 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.