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: src/lib/libc/gen/ftw.3,v 1.3 2005/11/23 15:41:36 ru Exp $
  22 .\"
  23 .Dd December 13, 2008
  24 .Dt FTW 3
  25 .Os
  26 .Sh NAME
  27 .Nm ftw , nftw
  28 .Nd traverse (walk) a file tree
  29 .Sh LIBRARY
  30 .Lb libc
  31 .Sh SYNOPSIS
  32 .In ftw.h
  33 .Ft int
  34 .Fo ftw
  35 .Fa "const char *path"
  36 .Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int\*[rp]"
  37 .Fa "int maxfds"
  38 .Fc
  39 .Ft int
  40 .Fo nftw
  41 .Fa "const char *path"
  42 .Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int, struct FTW *\*[rp]"
  43 .Fa "int maxfds"
  44 .Fa "int flags"
  45 .Fc
  46 .Sh DESCRIPTION
  47 The
  48 .Fn ftw
  49 and
  50 .Fn nftw
  51 functions traverse (walk) the directory hierarchy rooted in
  52 .Fa path .
  53 For each object in the hierarchy, these functions call the function
  54 pointed to by
  55 .Fa fn .
  56 The
  57 .Fn ftw
  58 function passes this function a pointer to a
  59 .Dv NUL Ns
  60 -terminated string containing
  61 the name of the object, a pointer to a
  62 .Vt stat
  63 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 .Vt FTW
  69 structure as defined by
  70 .In 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 ".Dv 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 .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
  99 .Vt stat
 100 structure are undefined.
 101 .It Dv FTW_SL
 102 A symbolic link.
 103 .It Dv FTW_SLN
 104 A symbolic link with a non-existent target
 105 .Fn ( nftw
 106 only).
 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 They were imported into
 216 .Dx 2.1 .
 217 .Sh BUGS
 218 The
 219 .Fa maxfds
 220 argument is currently ignored.