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 .Fn ( nftw
  91 only).
  92 .It Dv FTW_NS
  93 A file for which no
  94 .Xr stat 2
  95 information was available.
  96 The contents of the
  97 .Vt stat
  98 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 .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 maxfds
 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 ".Dv FTW_MOUNT"
 124 .It Dv FTW_PHYS
 125 Physical walk, do not 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 maxfds
 188 argument is less than 1.
 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 HISTORY
 207 These functions first appeared in
 208 .At V.3 .
 209 Their first
 210 .Fx
 211 appearance was in
 212 .Fx 5.3 .
 213 .Sh BUGS
 214 The
 215 .Fa maxfds
 216 argument is currently ignored.