1.\" $NetBSD: ftw.3,v 1.5 2010/04/30 04:39:16 jruoho Exp $ 2.\" 3.\" From OpenBSD: ftw.3,v 1.4 2003/10/30 18:52:58 jmc Exp 4.\" 5.\" Copyright (c) 2003 Todd C. Miller <Todd.Miller@courtesan.com> 6.\" 7.\" Permission to use, copy, modify, and distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.\" Sponsored in part by the Defense Advanced Research Projects 20.\" Agency (DARPA) and Air Force Research Laboratory, Air Force 21.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. 22.\" 23.Dd April 30, 2010 24.Dt FTW 3 25.Os 26.Sh NAME 27.Nm ftw, nftw 28.Nd traverse (walk) a file tree 29.Sh SYNOPSIS 30.In ftw.h 31.Ft int 32.Fo ftw 33.Fa "const char *path" 34.Fa "int (*fn)(const char *, const struct stat *, int)" 35.Fa "int maxfds" 36.Fc 37.Ft int 38.Fo nftw 39.Fa "const char *path" 40.Fa "int (*fn)(const\ char\ *, const\ struct\ stat\ *, int, struct\ FTW\ *)" 41.Fa "int maxfds" 42.Fa "int flags" 43.Fc 44.Sh DESCRIPTION 45.Bf -symbolic 46These functions are provided for compatibility with legacy code. 47New code should use the 48.Xr fts 3 49functions. 50.Ef 51.Pp 52The 53.Fn ftw 54and 55.Fn nftw 56functions traverse (walk) the directory hierarchy rooted in 57.Fa path . 58For each object in the hierarchy, these functions call the function 59pointed to by 60.Fa fn . 61The 62.Fn ftw 63function passes this function a pointer to a NUL-terminated string containing 64the name of the object, a pointer to a stat structure corresponding to the 65object, and an integer flag. 66The 67.Fn nftw 68function passes the aforementioned arguments plus a pointer to a 69.Dv FTW 70structure as defined by 71.In ftw.h 72(shown below): 73.Bd -literal 74struct FTW { 75 int base; /* offset of basename into pathname */ 76 int level; /* directory depth relative to starting point */ 77}; 78.Ed 79.Pp 80Possible values for the flag passed to 81.Fa fn 82are: 83.Bl -tag -width FTW_DNR 84.It Dv FTW_F 85A regular file. 86.It Dv FTW_D 87A directory being visited in pre-order. 88.It Dv FTW_DNR 89A directory which cannot be read. 90The directory will not be descended into. 91.It Dv FTW_DP 92A directory being visited in post-order 93.Pq Fn nftw No only . 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.Pq Fn nftw No only . 104.El 105.Pp 106The 107.Fn ftw 108function traverses the tree in pre-order. 109That is, it processes the directory before the directory's contents. 110.Pp 111The 112.Fa maxfds 113argument specifies the maximum number of file descriptors 114to keep open while traversing the tree. 115It has no effect in this implementation. 116.Pp 117The 118.Fn nftw 119function has an additional 120.Fa flags 121argument with the following possible values: 122.Bl -tag -width FTW_MOUNT 123.It Dv FTW_PHYS 124Physical walk, don't follow symbolic links. 125.It Dv FTW_MOUNT 126The walk will not cross a mount point. 127.It FTW_DEPTH 128Process directories in post-order. 129Contents of a directory are visited before the directory itself. 130By default, 131.Fn nftw 132traverses the tree in pre-order. 133.It FTW_CHDIR 134Change to a directory before reading it. 135By default, 136.Fn nftw 137will change its starting directory. 138The current working directory will be restored to its original value before 139.Fn nftw 140returns. 141.El 142.Sh RETURN VALUES 143If the tree was traversed successfully, the 144.Fn ftw 145and 146.Fn nftw 147functions return 0. 148If the function pointed to by 149.Fa fn 150returns a non-zero value, 151.Fn ftw 152and 153.Fn nftw 154will stop processing the tree and return the value from 155.Fa fn . 156Both functions return \-1 if an error is detected. 157.Sh ERRORS 158The 159.Fn ftw 160and 161.Fn nftw 162functions may fail and set 163.Va errno 164for any of the errors specified for the library functions 165.Xr close 2 , 166.Xr open 2 , 167.Xr stat 2 , 168.Xr malloc 3 , 169.Xr opendir 3 , 170and 171.Xr readdir 3 . 172If the 173.Dv FGTW_CHDIR 174flag is set, the 175.Fn nftw 176function may fail and set 177.Va errno 178for any of the errors specified for 179.Xr chdir 2 . 180In addition, either function may fail and set 181.Va errno 182as follows: 183.Bl -tag -width Er 184.It Bq Er EINVAL 185The 186.Fa maxfds 187argument is less than 1 or greater than 188.Dv OPEN_MAX . 189.El 190.Sh SEE ALSO 191.Xr chdir 2 , 192.Xr close 2 , 193.Xr open 2 , 194.Xr stat 2 , 195.Xr fts 3 , 196.Xr malloc 3 , 197.Xr opendir 3 , 198.Xr readdir 3 199.Sh STANDARDS 200The 201.Fn ftw 202and 203.Fn nftw 204functions conform to 205.St -p1003.1-2001 . 206The 207.St -p1003.1-2008 208revision marked the function 209.Fn ftw 210as obsolete. 211.Sh BUGS 212The 213.Fa maxfds 214argument is currently ignored. 215