1.\" $OpenBSD: ftw.3,v 1.8 2007/05/31 19:19:28 jmc Exp $ 2.\" 3.\" Copyright (c) 2003 Todd C. Miller <Todd.Miller@courtesan.com> 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: May 31 2007 $ 22.Dt FTW 3 23.Os 24.Sh NAME 25.Nm ftw, nftw 26.Nd traverse (walk) a file tree 27.Sh SYNOPSIS 28.Fd #include <ftw.h> 29.Ft int 30.Fo ftw 31.Fa "const char *path" 32.Fa "int (*fn)(const char *, const struct stat *, int)" 33.Fa "int maxfds" 34.Fc 35.Ft int 36.Fo nftw 37.Fa "const char *path" 38.Fa "int (*fn)(const\ char\ *, const\ struct\ stat\ *, int, struct\ FTW\ *)" 39.Fa "int maxfds" 40.Fa "int flags" 41.Fc 42.Sh DESCRIPTION 43.Bf -symbolic 44These functions are provided for compatibility with legacy code. 45New code should use the 46.Xr fts 3 47functions. 48.Ef 49.Pp 50The 51.Fn ftw 52and 53.Fn nftw 54functions traverse (walk) the directory hierarchy rooted in 55.Fa path . 56For each object in the hierarchy, these functions call the function 57pointed to by 58.Fa fn . 59The 60.Fn ftw 61function passes this function a pointer to a NUL-terminated string containing 62the name of the object, a pointer to a stat structure corresponding to the 63object, and an integer flag. 64The 65.Fn nftw 66function passes the aforementioned arguments plus a pointer to a 67.Dv FTW 68structure as defined by 69.Aq Pa ftw.h 70(shown below): 71.Bd -literal -offset indent 72struct FTW { 73 int base; /* offset of basename into pathname */ 74 int level; /* directory depth relative to starting point */ 75}; 76.Ed 77.Pp 78Possible values for the flag passed to 79.Fa fn 80are: 81.Bl -tag -width FTW_DNR 82.It Dv FTW_F 83A regular file. 84.It Dv FTW_D 85A directory being visited in pre-order. 86.It Dv FTW_DNR 87A directory which cannot be read. 88The directory will not be descended into. 89.It Dv FTW_DP 90A directory being visited in post-order 91.No ( Ns Fn nftw 92only). 93.It Dv FTW_NS 94A file for which no 95.Xr stat 2 96information was available. 97The contents of the stat structure are undefined. 98.It Dv FTW_SL 99A symbolic link. 100.It Dv FTW_SLN 101A symbolic link with a non-existent target 102.No ( Ns Fn nftw 103only). 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 FTW_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, in the case of 188.Nm ftw 189only, greater than 190.Dv OPEN_MAX . 191.El 192.Sh SEE ALSO 193.Xr chdir 2 , 194.Xr close 2 , 195.Xr open 2 , 196.Xr stat 2 , 197.Xr fts 3 , 198.Xr malloc 3 , 199.Xr opendir 3 , 200.Xr readdir 3 201.Sh STANDARDS 202The 203.Fn ftw 204and 205.Fn nftw 206functions conform to 207.St -p1003.1-2001 . 208.Sh BUGS 209The 210.Fa maxfds 211argument is currently ignored. 212