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 *, int)"
  33 .Fa "int maxfds"
  34 .Fc
  35 .Ft int
  36 .Fo nftw
  37 .Fa "const char *path"
  38 .Fa "int (*fn)(const\ char\ *, const\ struct\ stat\ *, int, struct\ FTW\ *)"
  39 .Fa "int maxfds"
  40 .Fa "int flags"
  41 .Fc
  42 .Sh DESCRIPTION
  43 .Bf -symbolic
  44 These functions are provided for compatibility with legacy code.
  45 New code should use the
  46 .Xr fts 3
  47 functions.
  48 .Ef
  49 .Pp
  50 The
  51 .Fn ftw
  52 and
  53 .Fn nftw
  54 functions traverse (walk) the directory hierarchy rooted in
  55 .Fa path .
  56 For each object in the hierarchy, these functions call the function
  57 pointed to by
  58 .Fa fn .
  59 The
  60 .Fn ftw
  61 function passes this function a pointer to a NUL-terminated string containing
  62 the name of the object, a pointer to a stat structure corresponding to the
  63 object, and an integer flag.
  64 The
  65 .Fn nftw
  66 function passes the aforementioned arguments plus a pointer to a
  67 .Dv FTW
  68 structure as defined by
  69 .Aq Pa ftw.h
  70 (shown below):
  71 .Bd -literal
  72 struct FTW {
  73     int base;   /* offset of basename into pathname */
  74     int level;  /* directory depth relative to starting point */
  75 };
  76 .Ed
  77 .Pp
  78 Possible values for the flag passed to
  79 .Fa fn
  80 are:
  81 .Bl -tag -width FTW_DNR
  82 .It Dv FTW_F
  83 A regular file.
  84 .It Dv FTW_D
  85 A directory being visited in pre-order.
  86 .It Dv FTW_DNR
  87 A directory which cannot be read.
  88 The directory will not be descended into.
  89 .It Dv FTW_DP
  90 A directory being visited in post-order
  91 .No ( Ns Fn nftw
  92 only).
  93 .It Dv FTW_NS
  94 A file for which no
  95 .Xr stat 2
  96 information was available.
  97 The contents of the stat 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 .No ( Ns Fn nftw
 103 only).
 104 .El
 105 .Pp
 106 The
 107 .Fn ftw
 108 function traverses the tree in pre-order.
 109 That is, it processes the directory before the directory's contents.
 110 .Pp
 111 The
 112 .Fa maxfds
 113 argument specifies the maximum number of file descriptors
 114 to keep open while traversing the tree.
 115 It has no effect in this implementation.
 116 .Pp
 117 The
 118 .Fn nftw
 119 function has an additional
 120 .Fa flags
 121 argument with the following possible values:
 122 .Bl -tag -width FTW_MOUNT
 123 .It Dv FTW_PHYS
 124 Physical walk, don't follow symbolic links.
 125 .It Dv FTW_MOUNT
 126 The walk will not cross a mount point.
 127 .It FTW_DEPTH
 128 Process directories in post-order.
 129 Contents of a directory are visited before the directory itself.
 130 By default,
 131 .Fn nftw
 132 traverses the tree in pre-order.
 133 .It FTW_CHDIR
 134 Change to a directory before reading it.
 135 By default,
 136 .Fn nftw
 137 will change its starting directory.
 138 The current working directory will be restored to its original value before
 139 .Fn nftw
 140 returns.
 141 .El
 142 .Sh RETURN VALUES
 143 If the tree was traversed successfully, the
 144 .Fn ftw
 145 and
 146 .Fn nftw
 147 functions return 0.
 148 If the function pointed to by
 149 .Fa fn
 150 returns a non-zero value,
 151 .Fn ftw
 152 and
 153 .Fn nftw
 154 will stop processing the tree and return the value from
 155 .Fa fn .
 156 Both functions return \-1 if an error is detected.
 157 .Sh ERRORS
 158 The
 159 .Fn ftw
 160 and
 161 .Fn nftw
 162 functions may fail and set
 163 .Va errno
 164 for any of the errors specified for the library functions
 165 .Xr close 2 ,
 166 .Xr open 2 ,
 167 .Xr stat 2 ,
 168 .Xr malloc 3 ,
 169 .Xr opendir 3
 170 and
 171 .Xr readdir 3 .
 172 If the
 173 .Dv FGTW_CHDIR
 174 flag is set, the
 175 .Fn nftw
 176 function may fail and set
 177 .Va errno
 178 for any of the errors specified for
 179 .Xr chdir 2 .
 180 In addition, either function may fail and set
 181 .Va errno
 182 as follows:
 183 .Bl -tag -width Er
 184 .It Bq Er EINVAL
 185 The
 186 .Fa maxfds
 187 argument is less than 1 or greater than
 188 .Dv OPEN_MAX .
 189 .El
 190 .Sh SEE ALSO
 191 .Xr chdir 2 ,
 192 .Xr close 2 ,
 193 .Xr open 2 ,
 194 .Xr stat 2 ,
 195 .Xr fts 3 ,
 196 .Xr malloc 3 ,
 197 .Xr opendir 3 ,
 198 .Xr readdir 3
 199 .Sh STANDARDS
 200 The
 201 .Fn ftw
 202 and
 203 .Fn nftw
 204 functions conform to
 205 .St -p1003.1-2001 .
 206 .Sh BUGS
 207 The
 208 .Fa maxfds
 209 argument is currently ignored.