1.\" $OpenBSD: ftw.3,v 1.5 2004/01/25 14:48:32 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.\" $FreeBSD: src/lib/libc/gen/ftw.3,v 1.3 2005/11/23 15:41:36 ru Exp $ 22.\" 23.Dd December 13, 2008 24.Dt FTW 3 25.Os 26.Sh NAME 27.Nm ftw , nftw 28.Nd traverse (walk) a file tree 29.Sh LIBRARY 30.Lb libc 31.Sh SYNOPSIS 32.In ftw.h 33.Ft int 34.Fo ftw 35.Fa "const char *path" 36.Fa "int (*fn)(const char *, const struct stat *, int)" 37.Fa "int maxfds" 38.Fc 39.Ft int 40.Fo nftw 41.Fa "const char *path" 42.Fa "int (*fn)(const char *, const struct stat *, int, struct FTW *)" 43.Fa "int maxfds" 44.Fa "int flags" 45.Fc 46.Sh DESCRIPTION 47The 48.Fn ftw 49and 50.Fn nftw 51functions traverse (walk) the directory hierarchy rooted in 52.Fa path . 53For each object in the hierarchy, these functions call the function 54pointed to by 55.Fa fn . 56The 57.Fn ftw 58function passes this function a pointer to a 59.Dv NUL Ns 60-terminated string containing 61the name of the object, a pointer to a 62.Vt stat 63structure corresponding to the 64object, and an integer flag. 65The 66.Fn nftw 67function passes the aforementioned arguments plus a pointer to a 68.Vt FTW 69structure as defined by 70.In ftw.h 71(shown below): 72.Bd -literal 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 ".Dv 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.Fn ( nftw 93only). 94.It Dv FTW_NS 95A file for which no 96.Xr stat 2 97information was available. 98The contents of the 99.Vt stat 100structure are undefined. 101.It Dv FTW_SL 102A symbolic link. 103.It Dv FTW_SLN 104A symbolic link with a non-existent target 105.Fn ( nftw 106only). 107.El 108.Pp 109The 110.Fn ftw 111function traverses the tree in pre-order. 112That is, it processes the directory before the directory's contents. 113.Pp 114The 115.Fa maxfds 116argument specifies the maximum number of file descriptors 117to keep open while traversing the tree. 118It has no effect in this implementation. 119.Pp 120The 121.Fn nftw 122function has an additional 123.Fa flags 124argument with the following possible values: 125.Bl -tag -width ".Dv FTW_MOUNT" 126.It Dv FTW_PHYS 127Physical walk, do not follow symbolic links. 128.It Dv FTW_MOUNT 129The walk will not cross a mount point. 130.It FTW_DEPTH 131Process directories in post-order. 132Contents of a directory are visited before the directory itself. 133By default, 134.Fn nftw 135traverses the tree in pre-order. 136.It FTW_CHDIR 137Change to a directory before reading it. 138By default, 139.Fn nftw 140will change its starting directory. 141The current working directory will be restored to its original value before 142.Fn nftw 143returns. 144.El 145.Sh RETURN VALUES 146If the tree was traversed successfully, the 147.Fn ftw 148and 149.Fn nftw 150functions return 0. 151If the function pointed to by 152.Fa fn 153returns a non-zero value, 154.Fn ftw 155and 156.Fn nftw 157will stop processing the tree and return the value from 158.Fa fn . 159Both functions return \-1 if an error is detected. 160.Sh ERRORS 161The 162.Fn ftw 163and 164.Fn nftw 165functions may fail and set 166.Va errno 167for any of the errors specified for the library functions 168.Xr close 2 , 169.Xr open 2 , 170.Xr stat 2 , 171.Xr malloc 3 , 172.Xr opendir 3 173and 174.Xr readdir 3 . 175If the 176.Dv FTW_CHDIR 177flag is set, the 178.Fn nftw 179function may fail and set 180.Va errno 181for any of the errors specified for 182.Xr chdir 2 . 183In addition, either function may fail and set 184.Va errno 185as follows: 186.Bl -tag -width Er 187.It Bq Er EINVAL 188The 189.Fa maxfds 190argument is less than 1. 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 HISTORY 209These functions first appeared in 210.At V.3 . 211Their first 212.Fx 213appearance was in 214.Fx 5.3 . 215They were imported into 216.Dx 2.1 . 217.Sh BUGS 218The 219.Fa maxfds 220argument is currently ignored. 221