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.Dd March 12, 2020 22.Dt FTW 3 23.Os 24.Sh NAME 25.Nm ftw , nftw 26.Nd traverse (walk) a file tree 27.Sh SYNOPSIS 28.In ftw.h 29.Ft int 30.Fo ftw 31.Fa "const char *path" 32.Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int\*[rp]" 33.Fa "int maxfds" 34.Fc 35.Ft int 36.Fo nftw 37.Fa "const char *path" 38.Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int, struct FTW *\*[rp]" 39.Fa "int maxfds" 40.Fa "int flags" 41.Fc 42.Sh DESCRIPTION 43The 44.Fn ftw 45and 46.Fn nftw 47functions traverse (walk) the directory hierarchy rooted in 48.Fa path . 49For each object in the hierarchy, these functions call the function 50pointed to by 51.Fa fn . 52The 53.Fn ftw 54function passes this function a pointer to a 55.Dv NUL Ns 56-terminated string containing 57the name of the object, a pointer to a 58.Vt stat 59structure corresponding to the 60object, and an integer flag. 61The 62.Fn nftw 63function passes the aforementioned arguments plus a pointer to a 64.Vt FTW 65structure as defined by 66.In ftw.h 67(shown below): 68.Bd -literal 69struct FTW { 70 int base; /* offset of basename into pathname */ 71 int level; /* directory depth relative to starting point */ 72}; 73.Ed 74.Pp 75Possible values for the flag passed to 76.Fa fn 77are: 78.Bl -tag -width ".Dv FTW_DNR" 79.It Dv FTW_F 80A regular file. 81.It Dv FTW_D 82A directory being visited in pre-order. 83.It Dv FTW_DNR 84A directory which cannot be read. 85The directory will not be descended into. 86.It Dv FTW_DP 87A directory being visited in post-order 88.Po Fn nftw 89only 90.Pc . 91.It Dv FTW_NS 92A file for which no 93.Xr stat 2 94information was available. 95The contents of the 96.Vt stat 97structure are undefined. 98.It Dv FTW_SL 99A symbolic link. 100.It Dv FTW_SLN 101A symbolic link with a non-existent target 102.Po Fn nftw 103only 104.Pc . 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 ".Dv FTW_MOUNT" 124.It Dv FTW_PHYS 125Physical walk, do not 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 EXAMPLES 159Following there is an example that shows how 160.Nm nftw 161can be used. 162It traverses the file tree starting at the directory pointed 163by the only program argument and shows the complete path and a brief 164indicator about the file type. 165.Bd -literal -offset 2n 166#include <ftw.h> 167#include <stdio.h> 168#include <sysexits.h> 169 170int 171nftw_callback(const char *path, const struct stat *sb, int typeflag, struct FTW *ftw) 172{ 173 char type; 174 175 switch(typeflag) { 176 case FTW_F: 177 type = 'F'; 178 break; 179 case FTW_D: 180 type = 'D'; 181 break; 182 case FTW_DNR: 183 type = '-'; 184 break; 185 case FTW_DP: 186 type = 'd'; 187 break; 188 case FTW_NS: 189 type = 'X'; 190 break; 191 case FTW_SL: 192 type = 'S'; 193 break; 194 case FTW_SLN: 195 type = 's'; 196 break; 197 default: 198 type = '?'; 199 break; 200 } 201 202 printf("[%c] %s\\n", type, path); 203 204 return (0); 205} 206 207int 208main(int argc, char **argv) 209{ 210 211 if (argc != 2) { 212 printf("Usage %s <directory>\\n", argv[0]); 213 return (EX_USAGE); 214 } else 215 return (nftw(argv[1], nftw_callback, /* UNUSED */ 1, 0)); 216} 217.Ed 218.Sh ERRORS 219The 220.Fn ftw 221and 222.Fn nftw 223functions may fail and set 224.Va errno 225for any of the errors specified for the library functions 226.Xr close 2 , 227.Xr open 2 , 228.Xr stat 2 , 229.Xr malloc 3 , 230.Xr opendir 3 231and 232.Xr readdir 3 . 233If the 234.Dv FTW_CHDIR 235flag is set, the 236.Fn nftw 237function may fail and set 238.Va errno 239for any of the errors specified for 240.Xr chdir 2 . 241In addition, either function may fail and set 242.Va errno 243as follows: 244.Bl -tag -width Er 245.It Bq Er EINVAL 246The 247.Fa maxfds 248argument is less than 1. 249.El 250.Sh SEE ALSO 251.Xr chdir 2 , 252.Xr close 2 , 253.Xr open 2 , 254.Xr stat 2 , 255.Xr fts 3 , 256.Xr malloc 3 , 257.Xr opendir 3 , 258.Xr readdir 3 259.Sh STANDARDS 260The 261.Fn ftw 262and 263.Fn nftw 264functions conform to 265.St -p1003.1-2001 . 266.Sh HISTORY 267These functions first appeared in 268.At V.3 . 269Their first 270.Fx 271appearance was in 272.Fx 5.3 . 273.Sh BUGS 274The 275.Fa maxfds 276argument is currently ignored. 277