1.\"	$OpenBSD: ftw.3,v 1.14 2019/09/02 21:18:41 deraadt Exp $
2.\"
3.\" Copyright (c) 2003 Todd C. Miller <millert@openbsd.org>
4.\"
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.
8.\"
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.
16.\"
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.
20.\"
21.Dd $Mdocdate: September 2 2019 $
22.Dt FTW 3
23.Os
24.Sh NAME
25.Nm ftw ,
26.Nm nftw
27.Nd traverse (walk) a file tree
28.Sh SYNOPSIS
29.In ftw.h
30.Ft int
31.Fo ftw
32.Fa "const char *path"
33.Fa "int (*fn)(const char *, const struct stat *, int)"
34.Fa "int maxfds"
35.Fc
36.Ft int
37.Fo nftw
38.Fa "const char *path"
39.Fa "int (*fn)(const\ char\ *, const\ struct\ stat\ *, int, struct\ FTW\ *)"
40.Fa "int maxfds"
41.Fa "int flags"
42.Fc
43.Sh DESCRIPTION
44.Bf -symbolic
45These functions are provided for compatibility with legacy code.
46New code should use the
47.Xr fts_open 3
48functions.
49.Ef
50.Pp
51The
52.Fn ftw
53and
54.Fn nftw
55functions traverse (walk) the directory hierarchy rooted in
56.Fa path .
57For each object in the hierarchy, these functions call the function
58pointed to by
59.Fa fn .
60The
61.Fn ftw
62function passes this function a pointer to a NUL-terminated string containing
63the name of the object, a pointer to a stat structure corresponding to the
64object, and an integer flag.
65The
66.Fn nftw
67function passes the aforementioned arguments plus a pointer to a
68.Dv FTW
69structure as defined by
70.In ftw.h
71(shown below):
72.Bd -literal -offset indent
73struct FTW {
74	int base;  /* offset of basename into pathname */
75	int level; /* directory depth relative to starting point */
76};
77.Ed
78.Pp
79Possible values for the flag passed to
80.Fa fn
81are:
82.Bl -tag -width FTW_DNR
83.It Dv FTW_F
84A regular file.
85.It Dv FTW_D
86A directory being visited in pre-order.
87.It Dv FTW_DNR
88A directory which cannot be read.
89The directory will not be descended into.
90.It Dv FTW_DP
91A directory being visited in post-order
92.Pf ( Fn nftw
93only).
94.It Dv FTW_NS
95A file for which no
96.Xr stat 2
97information was available.
98The contents of the stat structure are undefined.
99.It Dv FTW_SL
100A symbolic link.
101.It Dv FTW_SLN
102A symbolic link with a non-existent target
103.Pf ( Fn nftw
104only).
105.El
106.Pp
107The
108.Fn ftw
109function traverses the tree in pre-order.
110That is, it processes the directory before the directory's contents.
111.Pp
112The
113.Fa maxfds
114argument specifies the maximum number of file descriptors
115to keep open while traversing the tree.
116It has no effect in this implementation.
117.Pp
118The
119.Fn nftw
120function has an additional
121.Fa flags
122argument with the following possible values:
123.Bl -tag -width FTW_MOUNT
124.It Dv FTW_PHYS
125Physical walk: don't follow symbolic links.
126.It Dv FTW_MOUNT
127The walk will not cross a mount point.
128.It FTW_DEPTH
129Process directories in post-order.
130Contents of a directory are visited before the directory itself.
131By default,
132.Fn nftw
133traverses the tree in pre-order.
134.It FTW_CHDIR
135Change to a directory before reading it.
136By default,
137.Fn nftw
138will change its starting directory.
139The current working directory will be restored to its original value before
140.Fn nftw
141returns.
142.El
143.Sh RETURN VALUES
144If the tree was traversed successfully, the
145.Fn ftw
146and
147.Fn nftw
148functions return 0.
149If the function pointed to by
150.Fa fn
151returns a non-zero value,
152.Fn ftw
153and
154.Fn nftw
155will stop processing the tree and return the value from
156.Fa fn .
157Both functions return \-1 if an error is detected.
158.Sh ERRORS
159The
160.Fn ftw
161and
162.Fn nftw
163functions may fail and set
164.Va errno
165for any of the errors specified for the library functions
166.Xr close 2 ,
167.Xr open 2 ,
168.Xr stat 2 ,
169.Xr malloc 3 ,
170.Xr opendir 3
171and
172.Xr readdir 3 .
173If the
174.Dv FTW_CHDIR
175flag is set, the
176.Fn nftw
177function may fail and set
178.Va errno
179for any of the errors specified for
180.Xr chdir 2 .
181In addition, either function may fail and set
182.Va errno
183as follows:
184.Bl -tag -width Er
185.It Bq Er EINVAL
186The
187.Fa maxfds
188argument is less than 1 or, in the case of
189.Nm ftw
190only, greater than
191.Dv OPEN_MAX .
192.El
193.Sh SEE ALSO
194.Xr chdir 2 ,
195.Xr close 2 ,
196.Xr open 2 ,
197.Xr stat 2 ,
198.Xr fts_open 3 ,
199.Xr malloc 3 ,
200.Xr opendir 3 ,
201.Xr readdir 3
202.Sh STANDARDS
203The
204.Fn ftw
205and
206.Fn nftw
207functions conform to
208.St -p1003.1-2001 .
209.Sh BUGS
210The
211.Fa maxfds
212argument is currently ignored.
213