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.
21 .\" $FreeBSD: src/lib/libc/gen/ftw.3,v 1.3 2005/11/23 15:41:36 ru Exp $
28 .Nd traverse (walk) a file tree
35 .Fa "const char *path"
36 .Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int\*[rp]"
41 .Fa "const char *path"
42 .Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int, struct FTW *\*[rp]"
51 functions traverse (walk) the directory hierarchy rooted in
53 For each object in the hierarchy, these functions call the function
58 function passes this function a pointer to a
60 -terminated string containing
61 the name of the object, a pointer to a
63 structure corresponding to the
64 object, and an integer flag.
67 function passes the aforementioned arguments plus a pointer to a
69 structure as defined by
74 int base; /* offset of basename into pathname */
75 int level; /* directory depth relative to starting point */
79 Possible values for the flag passed to
82 .Bl -tag -width ".Dv FTW_DNR"
86 A directory being visited in pre-order.
88 A directory which cannot be read.
89 The directory will not be descended into.
91 A directory being visited in post-order
97 information was available.
100 structure are undefined.
104 A symbolic link with a non-existent target
111 function traverses the tree in pre-order.
112 That is, it processes the directory before the directory's contents.
116 argument specifies the maximum number of file descriptors
117 to keep open while traversing the tree.
118 It has no effect in this implementation.
122 function has an additional
124 argument with the following possible values:
125 .Bl -tag -width ".Dv FTW_MOUNT"
127 Physical walk, do not follow symbolic links.
129 The walk will not cross a mount point.
131 Process directories in post-order.
132 Contents of a directory are visited before the directory itself.
135 traverses the tree in pre-order.
137 Change to a directory before reading it.
140 will change its starting directory.
141 The current working directory will be restored to its original value before
146 If the tree was traversed successfully, the
151 If the function pointed to by
153 returns a non-zero value,
157 will stop processing the tree and return the value from
159 Both functions return \-1 if an error is detected.
165 functions may fail and set
167 for any of the errors specified for the library functions
179 function may fail and set
181 for any of the errors specified for
183 In addition, either function may fail and set
190 argument is less than 1.
209 These functions first appeared in
215 They were imported into
220 argument is currently ignored.