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 July 5, 2004
  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 ERRORS
 161 The
 162 .Fn ftw
 163 and
 164 .Fn nftw
 165 functions may fail and set
 166 .Va errno
 167 for any of the errors specified for the library functions
 168 .Xr close 2 ,
 169 .Xr open 2 ,
 170 .Xr stat 2 ,
 171 .Xr malloc 3 ,
 172 .Xr opendir 3
 173 and
 174 .Xr readdir 3 .
 175 If the
 176 .Dv FTW_CHDIR
 177 flag is set, the
 178 .Fn nftw
 179 function may fail and set
 180 .Va errno
 181 for any of the errors specified for
 182 .Xr chdir 2 .
 183 In addition, either function may fail and set
 184 .Va errno
 185 as follows:
 186 .Bl -tag -width Er
 187 .It Bq Er EINVAL
 188 The
 189 .Fa maxfds
 190 argument is less than 1.
 191 .El
 192 .Sh SEE ALSO
 193 .Xr chdir 2 ,
 194 .Xr close 2 ,
 195 .Xr open 2 ,
 196 .Xr stat 2 ,
 197 .Xr fts 3 ,
 198 .Xr malloc 3 ,
 199 .Xr opendir 3 ,
 200 .Xr readdir 3
 201 .Sh STANDARDS
 202 The
 203 .Fn ftw
 204 and
 205 .Fn nftw
 206 functions conform to
 207 .St -p1003.1-2001 .
 208 .Sh HISTORY
 209 These functions first appeared in
 210 .At V.3 .
 211 Their first
 212 .Fx
 213 appearance was in
 214 .Fx 5.3 .
 215 .Sh BUGS
 216 The
 217 .Fa maxfds
 218 argument is currently ignored.