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