gen/ftw.3

   1 .\"     $OpenBSD: ftw.3,v 1.4 2003/10/30 18:52:58 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 May 20, 2003
  22 .Dt FTW 3
  23 .Os
  24 .Sh NAME
  25 .Nm ftw, nftw
  26 .Nd traverse (walk) a file tree
  27 .Sh SYNOPSIS
  28 .Fd #include <ftw.h>
  29 .Ft int
  30 .Fo ftw
  31 .Fa "const char *path"
  32 .Fa "int (*fn)(const\ char\ *, const\ struct\ stat\ *ptr, int\ flag)"
  33 .Fa "int depth"
  34 .Fc
  35 .Ft int
  36 .Fo nftw
  37 .Fa "const char *path"
  38 .Fa "int (*fn)(const\ char\ *, const\ struct\ stat\ *ptr, \
  39      int\ flag, struct\ FTW\ *)"
  40 .Fa "int depth"
  41 .Fa "int flags"
  42 .Fc
  43 .Sh DESCRIPTION
  44 .Bf -symbolic
  45 These functions are provided for compatibility with legacy code.
  46 New code should use the
  47 .Xr fts 3
  48 functions.
  49 .Ef
  50 .Pp
  51 The
  52 .Fn ftw
  53 and
  54 .Fn nftw
  55 functions traverse (walk) the directory hierarchy rooted in
  56 .Fa path .
  57 For each object in the hierarchy, these functions call the function
  58 pointed to by
  59 .Fa fn .
  60 The
  61 .Fn ftw
  62 function passes this function a pointer to a NUL-terminated string containing
  63 the name of the object, a pointer to a stat structure corresponding to the
  64 object, and an integer flag.
  65 The
  66 .Fn nftw
  67 function passes the aforementioned arguments plus a pointer to a
  68 .Dv FTW
  69 structure as defined by
  70 .Aq Pa ftw.h
  71 (shown below):
  72 .Bd -literal
  73 struct FTW {
  74     int base;   /* offset of basename into pathname */
  75     int level;  /* directory depth relative to starting point */
  76 };
  77 .Ed
  78 .Pp
  79 Possible values for the flag passed to
  80 .Fa fn
  81 are:
  82 .Bl -tag -width FTW_DNR
  83 .It Dv FTW_F
  84 A regular file.
  85 .It Dv FTW_D
  86 A directory being visited in pre-order.
  87 .It Dv FTW_DNR
  88 A directory which cannot be read.
  89 The directory will not be descended into.
  90 .It Dv FTW_DP
  91 A directory being visited in post-order
  92 .No ( Ns Fn nftw
  93 only).
  94 .It Dv FTW_NS
  95 A file for which no
  96 .Xr stat 2
  97 information was available.
  98 The contents of the stat structure are undefined.
  99 .It Dv FTW_SL
 100 A symbolic link.
 101 .It Dv FTW_SLN
 102 A symbolic link with a non-existent target
 103 .No ( Ns Fn nftw
 104 only).
 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 depth
 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 FTW_MOUNT
 124 .It Dv FTW_PHYS
 125 Physical walk, don't 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 ERRORS
 159 The
 160 .Fn ftw
 161 and
 162 .Fn nftw
 163 functions may fail and set
 164 .Va errno
 165 for any of the errors specified for the library functions
 166 .Xr close 2 ,
 167 .Xr open 2 ,
 168 .Xr stat 2 ,
 169 .Xr malloc 3 ,
 170 .Xr opendir 3
 171 and
 172 .Xr readdir 3 .
 173 If the
 174 .Dv FTW_CHDIR
 175 flag is set, the
 176 .Fn nftw
 177 function may fail and set
 178 .Va errno
 179 for any of the errors specified for
 180 .Xr chdir 2 .
 181 In addition, either function may fail and set
 182 .Va errno
 183 as follows:
 184 .Bl -tag -width Er
 185 .It Bq Er EINVAL
 186 The
 187 .Fa depth
 188 argument is less than 1 or greater than
 189 .Dv OPEN_MAX .
 190 .El
 191 .Sh LEGACY ERRORS
 192 The
 193 .Fn ftw
 194 and
 195 .Fn nftw
 196 functions are far more tolerant of symlink cycles and are lax in reporting
 197 errors while accessing the initial path.  When
 198 .Fn nftw
 199 is passed
 200 .Dv FTW_MOUNT ,
 201 it will pass the mount point to the callback function.
 202 .Sh SEE ALSO
 203 .Xr chdir 2 ,
 204 .Xr close 2 ,
 205 .Xr open 2 ,
 206 .Xr stat 2 ,
 207 .Xr fts 3 ,
 208 .Xr malloc 3 ,
 209 .Xr opendir 3 ,
 210 .Xr readdir 3 ,
 211 .Xr compat 5
 212 .Sh STANDARDS
 213 The
 214 .Fn ftw
 215 and
 216 .Fn nftw
 217 functions conform to
 218 .St -p1003.1-2001 and
 219 .St -susv3 .
 220 .Sh HISTORY
 221 Prior to MacOS X 10.4
 222 .Nm ftw
 223 did not follow symlinks.
 224 .Sh BUGS
 225 The
 226 .Fa depth
 227 argument is currently ignored.