1 .\" $OpenBSD: ftw.3,v 1.5 2004/01/25 14:48:32 jmc Exp $
3 .\" Copyright (c) 2003 Todd C. Miller <Todd.Miller@courtesan.com>
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .\" Sponsored in part by the Defense Advanced Research Projects
18 .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
19 .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
28 .Nd traverse (walk) a file tree
33 .Fa "const char *path"
34 .Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int\*[rp]"
39 .Fa "const char *path"
40 .Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int, struct FTW *\*[rp]"
49 functions traverse (walk) the directory hierarchy rooted in
51 For each object in the hierarchy, these functions call the function
56 function passes this function a pointer to a
58 -terminated string containing
59 the name of the object, a pointer to a
61 structure corresponding to the
62 object, and an integer flag.
65 function passes the aforementioned arguments plus a pointer to a
67 structure as defined by
72 int base; /* offset of basename into pathname */
73 int level; /* directory depth relative to starting point */
77 Possible values for the flag passed to
80 .Bl -tag -width ".Dv FTW_DNR"
84 A directory being visited in pre-order.
86 A directory which cannot be read.
87 The directory will not be descended into.
89 A directory being visited in post-order
95 information was available.
98 structure are undefined.
102 A symbolic link with a non-existent target
109 function traverses the tree in pre-order.
110 That is, it processes the directory before the directory's contents.
114 argument specifies the maximum number of file descriptors
115 to keep open while traversing the tree.
116 It has no effect in this implementation.
120 function has an additional
122 argument with the following possible values:
123 .Bl -tag -width ".Dv FTW_MOUNT"
125 Physical walk, do not follow symbolic links.
127 The walk will not cross a mount point.
129 Process directories in post-order.
130 Contents of a directory are visited before the directory itself.
133 traverses the tree in pre-order.
135 Change to a directory before reading it.
138 will change its starting directory.
139 The current working directory will be restored to its original value before
144 If the tree was traversed successfully, the
149 If the function pointed to by
151 returns a non-zero value,
155 will stop processing the tree and return the value from
157 Both functions return \-1 if an error is detected.
163 functions may fail and set
165 for any of the errors specified for the library functions
177 function may fail and set
179 for any of the errors specified for
181 In addition, either function may fail and set
188 argument is less than 1.
207 These functions first appeared in
216 argument is currently ignored.