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