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