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