lib/libc/gen/ftw.3

   1 .\"     $NetBSD: ftw.3,v 1.5 2010/04/30 04:39:16 jruoho Exp $
   2 .\"
   3 .\"     From OpenBSD: ftw.3,v 1.4 2003/10/30 18:52:58 jmc Exp
   4 .\"
   5 .\" Copyright (c) 2003 Todd C. Miller <Todd.Miller@courtesan.com>
   6 .\"
   7 .\" Permission to use, copy, modify, and distribute this software for any
   8 .\" purpose with or without fee is hereby granted, provided that the above
   9 .\" copyright notice and this permission notice appear in all copies.
  10 .\"
  11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  12 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  13 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  14 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  15 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  16 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  17 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .\" Sponsored in part by the Defense Advanced Research Projects
  20 .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
  21 .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
  22 .\"
  23 .Dd April 30, 2010
  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 (*fn)(const char *, const struct stat *, int)"
  35 .Fa "int maxfds"
  36 .Fc
  37 .Ft int
  38 .Fo nftw
  39 .Fa "const char *path"
  40 .Fa "int (*fn)(const\ char\ *, const\ struct\ stat\ *, int, struct\ FTW\ *)"
  41 .Fa "int maxfds"
  42 .Fa "int flags"
  43 .Fc
  44 .Sh DESCRIPTION
  45 .Bf -symbolic
  46 These functions are provided for compatibility with legacy code.
  47 New code should use the
  48 .Xr fts 3
  49 functions.
  50 .Ef
  51 .Pp
  52 The
  53 .Fn ftw
  54 and
  55 .Fn nftw
  56 functions traverse (walk) the directory hierarchy rooted in
  57 .Fa path .
  58 For each object in the hierarchy, these functions call the function
  59 pointed to by
  60 .Fa fn .
  61 The
  62 .Fn ftw
  63 function passes this function a pointer to a NUL-terminated string containing
  64 the name of the object, a pointer to a stat structure corresponding to the
  65 object, and an integer flag.
  66 The
  67 .Fn nftw
  68 function passes the aforementioned arguments plus a pointer to a
  69 .Dv FTW
  70 structure as defined by
  71 .In ftw.h
  72 (shown below):
  73 .Bd -literal
  74 struct FTW {
  75     int base;   /* offset of basename into pathname */
  76     int level;  /* directory depth relative to starting point */
  77 };
  78 .Ed
  79 .Pp
  80 Possible values for the flag passed to
  81 .Fa fn
  82 are:
  83 .Bl -tag -width FTW_DNR
  84 .It Dv FTW_F
  85 A regular file.
  86 .It Dv FTW_D
  87 A directory being visited in pre-order.
  88 .It Dv FTW_DNR
  89 A directory which cannot be read.
  90 The directory will not be descended into.
  91 .It Dv FTW_DP
  92 A directory being visited in post-order
  93 .Pq Fn nftw No 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 .Pq Fn nftw No 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 The
 207 .St -p1003.1-2008
 208 revision marked the function
 209 .Fn ftw
 210 as obsolete.
 211 .Sh BUGS
 212 The
 213 .Fa maxfds
 214 argument is currently ignored.