1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
.TH FTW 3
.CT 2 dirs
.SH NAME
ftw \- file tree walk
.SH SYNOPSIS
.nf
.B #include <ftw.h>
.PP
.B int ftw(path, fn, depth)
.B char *path;
.B int (*fn)();
.B int depth;
.PP
.B #include <sys/types.h>
.B #include <sys/stat.h>
.PP
.IB fn "(name, statb, code, S)"
.B char *name;
.B struct stat *statb;
.B struct FTW *S;
.fi
.SH DESCRIPTION
.I Ftw
recursively descends the directory hierarchy
rooted in
.IR path .
For each entry in the hierarchy,
.I ftw
calls
.IR fn ,
passing it information about the entry:
a pointer to a null-terminated pathname
string, a pointer to a
.B stat
structure (see
.IR stat (2)),
and a pointer to the following structure.
.PP
.EX
.ta \w'struct 'u +\w'int level 'u
struct FTW {
int quit; \fRsee below\fP
int base; &name[base] \fRpoints to basename\fP
int level; \fRrecursion level (initially 0)\fP
};
.EE
.LP
Possible values of
.IR code ,
defined in
.FR <ftw.h> ,
are
.TF FTW_DNR
.PD 0
.TP
.B FTW_D
Entry is a directory (before visiting descendants).
.TP
.B FTW_DP
Entry is a directory (after visiting descendants).
.TP
.B FTW_SL
Entry is a symbolic link.
.TP
.B FTW_F
Entry is some other kind of file.
.TP
.B FTW_DNR
Entry is a directory that cannot be read;
no descendants will be visited.
.TP
.B FTW_NS
.I Lstat
(see
.IR stat (2))
failed on
.IR name ;
contents of
.I statb
are undefined
.TP
.B FTW_NSL
.I Lstat
succeeded, but
.I stat
failed; contents of
.I statb
are undefined.
.PD
.PP
The tree traversal continues until the tree is exhausted or
.I fn
returns a nonzero value.
When the tree is exhausted,
.I ftw
returns zero.
When
.I fn
returns a nonzero value,
.I ftw
stops and returns that value.
.PP
Normally symbolic links are not followed.
But if on a symbolic link
.RB ( FTW_SL )
.IR fn
sets
.B S->quit
to
.BR FTW_FOLLOW ,
.IR ftw
will next attempt to follow the link.
.PP
.I Ftw
normally visits a readable directory twice, before and
after visiting its descendants.
But if on a previsit
.RB ( FTW_D )
.I fn
sets
.B S->quit
to
.B FTW_SKD,
.I ftw
will skip the descendants and the postvisit
.RB ( FTW_DP ).
.PP
.I Ftw
uses one file descriptor for each level in the tree up to a
maximum of
.I depth
(or 1, if
.IR depth <1)
descriptors.
.I Depth
must not exceed the number of available file descriptors; small
values of
.I depth
may cause
.I ftw
to run slowly, but will not change its effect.
.SH "SEE ALSO"
.IR stat (2),
.IR directory (3)
.SH DIAGNOSTICS
.I Ftw
returns \-1
with
.I errno
set to
.B ENOMEM
when
.IR malloc (3)
fails.
.PP
.I Errno
is set appropriately when
.I ftw
calls
.I fn
with code
.BR FTW_DNR ,
.BR FTW_NS ,
or
.BR FTW_NSL .
|
