| blob | f339ab71a0e402ad10b29a22876d7750850bb9d4 |
1 .fp 5 CW
2 .TH FTWALK 3
3 .SH NAME
4 \fBftwalk\fR \- file tree walker
5 .SH SYNOPSIS
6 .ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i
7 .PP
8 .nf
9 \f5
10 #include <ftwalk.h>
12 int ftwalk(char* path, int (*userf)(struct FTW* ftw), int options,
13 int (*comparf)(struct FTW* ftw1, struct FTW* ftw2));
16 int ftwflags(void);
17 \fR
18 .fi
19 .SH DESCRIPTION
20 .PP
21 \fIFtwalk\fR traverses a directory hierarchy using depth-first search.
22 Upon visiting each file or directory in the hierarchy, it calls
23 the user function \fIuserf\fP to process that file or directory.
24 On a directory object, \fIuserf\fR may be called twice, once in preorder
25 and once in postorder.
26 On a terminal object such as a file or an unreadable directory,
27 \fIuserf\fP is called only once.
28 Cycles due to hard links or symbolic links are detected
29 to avoid infinite loops.
30 .PP
31 \fIPath\fR is the starting point of the search.
32 It may be an absolute path name or a path name relative to
33 the current directory.
34 If \fIpath\fR is a null pointer or points to an empty string, it is treated
35 as if it points to the current (dot) directory.
36 .PP
37 \fIOptions\fR consists of zero or more of the following bits:
38 .IP
39 FTW_CHILDREN:
40 This implies preorder calls to \fIuserf\fR on directory objects.
41 On such a call to \fIuserf\fR,
42 the field \fIftw->link\fR (below) points to a link list of
43 the children of the respective directory.
44 Upon returning from \fIuserf\fP,
45 if the field \fIftw->status\fR of any child object
46 is set to FTW_SKIP (below), that child is pruned from the search.
47 .IP
48 FTW_DELAY: When \fBFTW_CHILDREN\fP is turned on,
49 the fields \fIftw->statb\fP (\fIstruct stat\fP) of children objects
50 remain undefined until these objects are visited.
51 .IP
52 FTW_DOT: Do not use \fIchdir\fR(2) during the traversal.
53 Normally \fIchdir\fR is used so that
54 the base name of the object about to be processed can be used
55 in accessing its data.
56 This can enhance \fIftwalk\fR efficiency but certain program effects
57 such as core dumps may be generated in unexpected places
58 or may not even be generated at all.
59 Whenever \fIchdir\fR generates an error, if possible,
60 the current directory is restored to the starting directory
61 (see FTW_NAME and FTW_PATH).
62 .IP
63 FTW_MULTIPLE: The \fIpath\fP argument is treated as a \fIchar**\fP
64 pointer to a null-terminated array of path names.
65 All hierarchies rooted at these paths will be searched
66 .IP
67 FTW_POST: Calls to the user function are issued only in postorder.
68 That is, \fIuserf\fP is called on a directory only after its descendants have
69 been processed.
70 The absence of this bit indicates that calls to the user functions
71 are issued in preorder. That is, \fIuserf\fP is
72 called on a directory before its descendants are processed.
73 .IP
74 FTW_PHYSICAL: Use \fIlstat\fR(2) instead of \fIstat\fR(2) to get
75 file status and allow detection of symbolic links.
76 In addition, if each component
77 of the absolute path to the starting object has search permission,
78 the absolute path is used for early detection of cycles.
79 .IP
80 FTW_META|FTW_PHYSICAL: Use \fIstat\fR(2) for top level file status and
81 \fIlstat\fR(2) for all other files.
82 Used to implement the POSIX
83 .B \-H
84 option for commands like
85 .IR ls .
86 .IP
87 FTW_TWICE: Calls to the user function are issued in both preorder and postorder
88 for directory objects.
89 .IP
90 FTW_USER: The first of 6 user defined option bits.
91 These bits are ignored by \fIftwalk\fP.
92 .PP
93 \fIUserf\fR is a user supplied function that is
94 called upon different visits of an object.
95 If the return value of \fIuserf\fR is non-zero,
96 \fIftwalk\fR returns immediately with the same value.
97 The \fIuserf\fP prototype is:
98 .PP
99 .nf
100 int userf(struct FTW* ftw)
101 .fi
102 .PP
103 \fBstruct FTW\fP contains at least the following elements:
104 .PP
105 .nf
106 struct FTW* link; /* link list of children */
107 struct FTW* parent; /* parent object on the search path */
108 union
109 {
110 long number; /* local number */
111 void* pointer; /* local pointer */
112 } local; /* user defined */
113 struct stat statb; /* stat buffer of this object */
114 char* path; /* full pathname */
115 short pathlen; /* strlen(path) */
116 unsigned short info; /* type of object */
117 unsigned short status; /* status of object */
118 short level; /* depth of object on the search path */
119 short namelen; /* strlen(name) */
120 char name[]; /* file name of object */
121 .fi
122 .PP
123 The \fIlink\fR field is normally NULL.
124 If the option FTW_CHILDREN was turned on,
125 it points to the start of the list of children
126 of the directory being visited in preorder.
127 Finally, if the directory being visited causes a cycle,
128 \fIlink\fR points to the object on the search path that is
129 identical to this directory. Note that if FTW_PHYSICAL was turned on,
130 this may point to a directory that is an ancestor of the starting
131 object.
132 .PP
133 The \fIparent\fR field points to the parent object
134 on the search path. For convenience, a parent object is also supplied for
135 the starting object.
136 In this case, except for the \fIlocal\fR field which is initialized
137 to 0 and the \fIlevel\fR field which contains a negative number,
138 the rest of the structure may be undefined.
139 .PP
140 The \fIinfo\fR field indicates the type of the object
141 being visited and the type of the visit. The types are:
142 .IP
143 FTW_D: A directory being visited in preorder, i.e.,
144 none of its children has been visited by the search.
145 .IP
146 FTW_DNX: A directory being visited in preorder that does not have
147 search permission.
148 .IP
149 FTW_DP: A directory being visited in postorder, i.e., all of its
150 descendants have been completely processed.
151 .IP
152 FTW_DC: A directory that causes cycles. This is a terminal object.
153 .IP
154 FTW_DNR: A directory that cannot be opened for reading. This is a terminal object.
155 .IP
156 FTW_F: An ordinary file.
157 .IP
158 FTW_SL: A symbolic link.
159 Unless FTW_FOLLOW (below) is issued by the user function,
160 this object is terminal.
161 .IP
162 FTW_NS: \fIStat\fR failed on this object.
163 The stat buffer \fIstatb\fR is undefined.
164 This object is terminal.
165 .PP
166 The \fIstatus\fR field of \fIstruct FTW\fR is used to communicate information
167 between \fIftwalk\fR and \fIuserf\fR. On calls to \fIuserf\fR, it has one of
168 two values:
169 .IP
170 FTW_NAME: The name of the object as defined in \fIftw->name\fR should be used for
171 accessing its file information. This is because \fIchdir\fR(2) has been used
172 to set the current directory to a suitable place (see FTW_CHDIR).
173 .IP
174 FTW_PATH: The argument \fIpath\fR of \fIuserf\fR should be used
175 for accessing the file information of the object.
176 .PP
177 Upon returning, \fIuserf\fR may set the \fIstatus\fR field
178 to one of the following values:
179 .IP
180 FTW_AGAIN: If this is a directory object being visited in postorder,
181 it will be processed \fIagain\fR as if it had not been visited.
182 .IP
183 FTW_NOPOST: If this is a directory object being visited in preorder,
184 the user function will not be called on its postorder visit.
185 .IP
186 FTW_SKIP: This object and its descendants are pruned from the search.
187 .IP
188 FTW_FOLLOW: If this object is a symbolic link,
189 follow the link to its physical counterpart.
190 .PP
191 \fIComparf\fR, if not NULL, is a pointer to a function
192 used to define a search ordering for children of a directory.
193 If FTW_CHILDREN is turned on, the ordering of the children of
194 a directory is done before the preorder call to \fIuserf\fR on that directory.
195 Therefore, in that case, \fIftw->link\fR will point to the smallest child.
196 .PP
197 The \fIcomparf\fP prototype is:
198 .PP
199 .nf
200 int comparf(struct FTW* ftw1, struct FTW* ftw2)
201 .fi
202 .PP
203 \fIComparf\fR should return a value <0, 0, or >0 to indicate whether
204 \fIftw1\fR is considered smaller, equal, or larger than \fIftw2\fR.
205 .PP
206 \fIFtwalk\fR normally returns 0.
207 On hard errors such as running out of memory, it returns -1.
208 \fIFtwalk\fR may also return other values as discussed with respect
209 to \fIuserf\fR.
210 .PP
211 \fIFtwflags\fR returns a combination of \fB0, FTW_META, FTW_PHYSICAL\fR
212 according to the
213 preferences specified by
214 \fBastconf("PATH_RESOLVE",0,0)\fR:
215 .TP
216 .B logical
217 0
218 .TP
219 .B metaphysical
220 .B "FTW_META|FTW_PHYSICAL"
221 .TP
222 .B physical
223 .B FTW_PHYSICAL
224 .SH HISTORY
225 \fIFtwalk\fR performs similar functions as that of
226 the routine \fIftw\fR provided in System V.
227 However, it is more general than \fIftw\fR
228 and suitable for use as a base in implementing
229 popular tools such as \fIls, find, tar, du,\fR and \fIrm\fR.
230 \fIFtwalk\fR also handles symbolic links and hard links gracefully.
231 .SH AUTHORS
232 Phong Vo, Glenn Fowler, Dave Korn
233 .SH SEE ALSO
234 find(1), rm(1), du(1), ls(1), tar(1), stat(2), symlink(2),
235 astfeature(3), ftw(3), pathcd(3)