lib/libc/gen/ftw.3

   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
  43 The
  44 .Fn ftw
  45 and
  46 .Fn nftw
  47 functions traverse (walk) the directory hierarchy rooted in
  48 .Fa path .
  49 For each object in the hierarchy, these functions call the function
  50 pointed to by
  51 .Fa fn .
  52 The
  53 .Fn ftw
  54 function passes this function a pointer to a
  55 .Dv NUL Ns
  56 -terminated string containing
  57 the name of the object, a pointer to a
  58 .Vt stat
  59 structure corresponding to the
  60 object, and an integer flag.
  61 The
  62 .Fn nftw
  63 function passes the aforementioned arguments plus a pointer to a
  64 .Vt FTW
  65 structure as defined by
  66 .In ftw.h
  67 (shown below):
  68 .Bd -literal
  69 struct FTW {
  70     int base;   /* offset of basename into pathname */
  71     int level;  /* directory depth relative to starting point */
  72 };
  73 .Ed
  74 .Pp
  75 Possible values for the flag passed to
  76 .Fa fn
  77 are:
  78 .Bl -tag -width ".Dv FTW_DNR"
  79 .It Dv FTW_F
  80 A regular file.
  81 .It Dv FTW_D
  82 A directory being visited in pre-order.
  83 .It Dv FTW_DNR
  84 A directory which cannot be read.
  85 The directory will not be descended into.
  86 .It Dv FTW_DP
  87 A directory being visited in post-order
  88 .Po Fn nftw
  89 only
  90 .Pc .
  91 .It Dv FTW_NS
  92 A file for which no
  93 .Xr stat 2
  94 information was available.
  95 The contents of the
  96 .Vt stat
  97 structure are undefined.
  98 .It Dv FTW_SL
  99 A symbolic link.
 100 .It Dv FTW_SLN
 101 A symbolic link with a non-existent target
 102 .Po Fn nftw
 103 only
 104 .Pc .
 105 .El
 106 .Pp
 107 The
 108 .Fn ftw
 109 function traverses the tree in pre-order.
 110 That is, it processes the directory before the directory's contents.
 111 .Pp
 112 The
 113 .Fa maxfds
 114 argument specifies the maximum number of file descriptors
 115 to keep open while traversing the tree.
 116 It has no effect in this implementation.
 117 .Pp
 118 The
 119 .Fn nftw
 120 function has an additional
 121 .Fa flags
 122 argument with the following possible values:
 123 .Bl -tag -width ".Dv FTW_MOUNT"
 124 .It Dv FTW_PHYS
 125 Physical walk, do not follow symbolic links.
 126 .It Dv FTW_MOUNT
 127 The walk will not cross a mount point.
 128 .It FTW_DEPTH
 129 Process directories in post-order.
 130 Contents of a directory are visited before the directory itself.
 131 By default,
 132 .Fn nftw
 133 traverses the tree in pre-order.
 134 .It FTW_CHDIR
 135 Change to a directory before reading it.
 136 By default,
 137 .Fn nftw
 138 will change its starting directory.
 139 The current working directory will be restored to its original value before
 140 .Fn nftw
 141 returns.
 142 .El
 143 .Sh RETURN VALUES
 144 If the tree was traversed successfully, the
 145 .Fn ftw
 146 and
 147 .Fn nftw
 148 functions return 0.
 149 If the function pointed to by
 150 .Fa fn
 151 returns a non-zero value,
 152 .Fn ftw
 153 and
 154 .Fn nftw
 155 will stop processing the tree and return the value from
 156 .Fa fn .
 157 Both functions return \-1 if an error is detected.
 158 .Sh EXAMPLES
 159 Following there is an example that shows how
 160 .Nm nftw
 161 can be used.
 162 It traverses the file tree starting at the directory pointed
 163 by the only program argument and shows the complete path and a brief
 164 indicator about the file type.
 165 .Bd -literal -offset 2n
 166 #include <ftw.h>
 167 #include <stdio.h>
 168 #include <sysexits.h>
 169
 170 int
 171 nftw_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
 207 int
 208 main(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
 219 The
 220 .Fn ftw
 221 and
 222 .Fn nftw
 223 functions may fail and set
 224 .Va errno
 225 for 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
 231 and
 232 .Xr readdir 3 .
 233 If the
 234 .Dv FTW_CHDIR
 235 flag is set, the
 236 .Fn nftw
 237 function may fail and set
 238 .Va errno
 239 for any of the errors specified for
 240 .Xr chdir 2 .
 241 In addition, either function may fail and set
 242 .Va errno
 243 as follows:
 244 .Bl -tag -width Er
 245 .It Bq Er EINVAL
 246 The
 247 .Fa maxfds
 248 argument 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
 260 The
 261 .Fn ftw
 262 and
 263 .Fn nftw
 264 functions conform to
 265 .St -p1003.1-2001 .
 266 .Sh HISTORY
 267 These functions first appeared in
 268 .At V.3 .
 269 Their first
 270 .Fx
 271 appearance was in
 272 .Fx 5.3 .
 273 .Sh BUGS
 274 The
 275 .Fa maxfds
 276 argument is currently ignored.