man3/ftw.3

   1 .\" Copyright (c) 1993 Michael Haardt (michael@moria.de)
   2 .\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
   3 .\" and copyright (c) 2006 Justin Pryzby <justinpryzby@users.sf.net>
   4 .\" and copyright (c) 2006 Michael Kerrisk <mtk-manpages@gmx.net>
   5 .\"
   6 .\" This is free documentation; you can redistribute it and/or
   7 .\" modify it under the terms of the GNU General Public License as
   8 .\" published by the Free Software Foundation; either version 2 of
   9 .\" the License, or (at your option) any later version.
  10 .\"
  11 .\" The GNU General Public License's references to "object code"
  12 .\" and "executables" are to be interpreted as the output of any
  13 .\" document formatting or typesetting system, including
  14 .\" intermediate and printed output.
  15 .\"
  16 .\" This manual is distributed in the hope that it will be useful,
  17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 .\" GNU General Public License for more details.
  20 .\"
  21 .\" You should have received a copy of the GNU General Public
  22 .\" License along with this manual; if not, write to the Free
  23 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  24 .\" USA.
  25 .\"
  26 .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu)
  27 .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net>
  28 .\"     document FTW_ACTIONRETVAL; include .SH "RETURN VALUE";
  29 .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> and
  30 .\"     Michael Kerrisk <mtk-manpages@gmx.net>
  31 .\"     reorganized and rewrote much of the page
  32 .\" 2006-05-24, Michael Kerrisk <mtk-manpages@gmx.net>
  33 .\"     Added an example program.
  34 .TH FTW 3 2006-05-24 "Linux" "Linux Programmer's Manual"
  35 .SH NAME
  36 ftw, nftw \- file tree walk
  37 .SH SYNOPSIS
  38 .nf
  39 .B #include <ftw.h>
  40 .sp
  41 .BI "int ftw(const char *" dirpath ,
  42 .BR "        int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
  43 .BI "                   int " typeflag ),
  44 .BI "        int " nopenfd );
  45 .sp
  46 .B #define _XOPEN_SOURCE 500
  47 .B #include <ftw.h>
  48 .sp
  49 .BI "int nftw(const char *" dirpath ,
  50 .BI "        int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
  51 .BI "                   int " typeflag ", struct FTW *" ftwbuf ),
  52 .BI "        int " nopenfd ", int " flags );
  53 .fi
  54 .SH DESCRIPTION
  55 \fBftw\fP() walks through the directory tree that is
  56 located under the directory \fIdirpath\fP,
  57 and calls \fIfn\fP() once for each entry in the tree.
  58 By default, directories are handled before the files and
  59 subdirectories they contain (pre-order traversal).
  60
  61 To avoid using up all of the calling process's file descriptors,
  62 \fInopenfd\fP specifies the maximum number of directories that
  63 \fBftw\fP() will hold open simultaneously.
  64 When
  65 the search depth exceeds this, \fBftw\fP() will become slower because
  66 directories have to be closed and reopened. \fBftw\fP() uses at most
  67 one file descriptor for each level in the directory tree.
  68
  69 For each entry found in the tree,
  70 .BR ftw ()
  71 calls
  72 \fIfn\fP() with three arguments:
  73 .IR fpath ,
  74 .IR sb ,
  75 and
  76 .IR typeflag .
  77 .IR fpath
  78 is the pathname of the entry relative to
  79 .IR dirpath .
  80 .IR sb
  81 is a pointer to the
  82 .IR stat
  83 structure returned by a call to
  84 .BR stat (2)
  85 for
  86 .IR fpath .
  87 .IR typeflag
  88 is an integer that has one of the following values:
  89 .TP
  90 .B FTW_F
  91 .I fpath
  92 is a normal file.
  93 .TP
  94 .B FTW_D
  95 .I fpath
  96 is a directory.
  97 .TP
  98 .B FTW_DNR
  99 .I fpath
 100 is a directory which can't be read.
 101 .TP
 102 .B FTW_NS
 103 The
 104 .BR stat (2)
 105 call failed on
 106 .IR fpath ,
 107 which is not a symbolic link.
 108 .sp
 109 If
 110 .I fpath
 111 is a symbolic link and
 112 .BR stat (2)
 113 failed, POSIX.1 states
 114 that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP (see below)
 115 is passed in
 116 .IR typeflag .
 117 .PP
 118 To stop the tree walk, \fIfn\fP() returns a non-zero value; this
 119 value will become the return value of \fBftw\fP().
 120 As long as \fIfn\fP() returns 0,
 121 \fBftw\fP() will continue either until it has traversed the entire tree,
 122 in which case it will return zero,
 123 or until it encounters an error (such as a
 124 .BR malloc (3)
 125 failure), in which case it will return \-1.
 126 .PP
 127 Because \fBftw\fP() uses dynamic data structures, the only safe way to
 128 exit out of a tree walk is to return a non-zero value from \fIfn\fP().
 129 To allow a signal to terminate the walk without causing a memory leak,
 130 have the handler set a global flag that is checked by \fIfn\fP().
 131 \fIDon't\fP use \fBlongjmp\fP(3) unless the program is going to terminate.
 132 .SS nftw()
 133 The function \fBnftw\fP() is the same as \fBftw\fP(),
 134 except that it has one additional argument, \fIflags\fP,
 135 and calls \fIfn\fP() with one more argument, \fIftwbuf\fP.
 136
 137 This \fIflags\fP argument is formed by ORing zero or more of the
 138 following flags:
 139 .TP
 140 .BR FTW_ACTIONRETVAL " (since glibc 2.3.3)"
 141 If this glibc-specific flag is set, then
 142 .BR nftw ()
 143 handles the return value from
 144 .IR fn ()
 145 differently.
 146 .IR fn ()
 147 should return one of the following values:
 148 .RS
 149 .TP
 150 .B FTW_CONTINUE
 151 Instructs \fBnftw\fP() to continue normally.
 152 .TP
 153 .B FTW_SKIP_SIBLINGS
 154 If \fIfn\fP() returns this value, then
 155 siblings of the current entry will be skipped,
 156 and processing continues in the parent.
 157 .\" If \fBFTW_DEPTH\fP
 158 .\" is set, the entry's parent directory is processed next (with
 159 .\" \fIflag\fP set to \fBFTW_DP\fP).
 160 .TP
 161 .B FTW_SKIP_SUBTREE
 162 If \fIfn\fP() is called with an entry that is a directory
 163 (\fItypeflag\fP is \fBFTW_D\fP), this return
 164 value will prevent objects within that directory from being passed as
 165 arguments to \fIfn\fP().
 166 .BR nftw ()
 167 continues processing with the next sibling of the directory.
 168 .TP
 169 .B FTW_STOP
 170 Causes \fBnftw\fP() to return immediately with the return value
 171 \fBFTW_STOP\fP.
 172 .PP
 173 Other return values could be associated with new actions in the future;
 174 \fIfn\fP() should not return values other than those listed above.
 175
 176 The feature test macro _GNU_SOURCE must be defined in order to
 177 obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP.
 178 .RE
 179 .TP
 180 .B FTW_CHDIR
 181 If set, do a
 182 .BR chdir (2)
 183 to each directory before handling its contents.
 184 This is useful if the program needs to perform some action
 185 in the directory in which \fIfpath\fP resides.
 186 .TP
 187 .B FTW_DEPTH
 188 If set, do a post-order traversal, that is, call \fIfn\fP() for
 189 the directory itself \fIafter\fP handling the contents of the directory
 190 and its subdirectories.
 191 (By default, each directory is handled \fIbefore\fP its contents.)
 192 .TP
 193 .B FTW_MOUNT
 194 If set, stay within the same file system
 195 (i.e., do not cross mount points).
 196 .TP
 197 .B FTW_PHYS
 198 If set, do not follow symbolic links.
 199 (This is what you want.)
 200 If not set, symbolic links are followed, but no file is reported twice.
 201 .sp
 202 If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set,
 203 then the function
 204 .IR fn ()
 205 is never called for a directory that would be a descendant of itself.
 206 .LP
 207 For each entry in the directory tree,
 208 .BR nftw ()
 209 calls
 210 .IR fn ()
 211 with four arguments.
 212 .I fpath
 213 and
 214 .I sb
 215 are as for
 216 .BR ftw ().
 217 .I typeflag
 218 may receive any of the same values as with
 219 .BR ftw (),
 220 or any of the following values:
 221 .TP
 222 .B FTW_DP
 223 .I fpath
 224 is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP.
 225 All of the files
 226 and subdirectories within \fIfpath\fP have been processed.
 227 .TP
 228 .B FTW_SL
 229 .I fpath
 230 is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP.
 231 .TP
 232 .B FTW_SLN
 233 .I fpath
 234 is a symbolic link pointing to a nonexistent file.
 235 (This occurs only if \fBFTW_PHYS\fP is not set.)
 236 .LP
 237 The fourth argument that
 238 .BR nftw ()
 239 supplies when calling
 240 \fIfn\fP()
 241 is a structure of type \fIFTW\fP:
 242 .in +0.25i
 243 .nf
 244
 245 struct FTW {
 246     int base;
 247     int level;
 248 };
 249
 250 .fi
 251 .in -0.25i
 252 .I base
 253 is the offset of the filename (i.e., basename component)
 254 in the pathname given in
 255 .IR fpath .
 256 .IR level
 257 is the depth of
 258 .I fpath
 259 in the directory tree, relative to the root of the tree
 260 .RI ( dirpath ,
 261 which has depth 0).
 262 .SH "RETURN VALUE"
 263 These functions return 0 on success, and \-1 if an error occurs.
 264
 265 .\" FIXME check the following
 266 If \fIfn\fP() returns non-zero,
 267 then the tree walk is terminated and the value returned by \fIfn\fP()
 268 is returned as the result of \fBftw\fP() or \fBnftw\fP().
 269
 270 If \fBnftw\fP() is called with the \fBFTW_ACTIONRETVAL\fP flag,
 271 then the only non-zero value that should be used by \fIfn\fP()
 272 to terminate the tree walk is \fBFTW_STOP\fP,
 273 and that value is returned as the result of \fBnftw\fP().
 274 .SH NOTES
 275 The function
 276 .BR nftw ()
 277 and the use of \fBFTW_SL\fP with
 278 .BR ftw ()
 279 were introduced in XPG4v2.
 280 .LP
 281 On some systems
 282 .BR ftw ()
 283 will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only
 284 for symbolic links that do not point to an existing file,
 285 and again on other systems
 286 .BR ftw ()
 287 will use \fBFTW_SL\fP for each symbolic link. For predictable control, use
 288 .BR nftw ().
 289 .LP
 290 Under Linux, libc4 and libc5 and glibc 2.0.6 will
 291 use \fBFTW_F\fP for all objects (files, symbolic links, fifos, etc)
 292 that can be stat'ed but are not a directory.
 293
 294 The function
 295 .BR nftw ()
 296 is available since glibc 2.1.
 297
 298 \fBFTW_ACTIONRETVAL\fP is glibc specific.
 299 .SH "CONFORMING TO"
 300 POSIX.1-2001, SVID3, XPG4v2.
 301 .SH EXAMPLE
 302 The following program traverses the directory tree under the path named
 303 in its first command-line argument, or under the current directory
 304 if no argument is supplied.
 305 It displays various information about each file.
 306 The second-command line argument can be used to specify characters that
 307 control the value assigned to the \fIflags\fP
 308 argument when calling \fBnftw\fP().
 309 .nf
 310
 311 #define _XOPEN_SOURCE 500
 312 #include <ftw.h>
 313 #include <stdio.h>
 314 #include <stdlib.h>
 315 #include <string.h>
 316
 317 static int
 318 display_info(const char *fpath, const struct stat *sb,
 319              int tflag, struct FTW *ftwbuf)
 320 {
 321     printf("%-3s %2d %7lld   %-40s %d %s\\n",
 322         (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
 323         (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
 324         (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_SL) ?  "sl" :
 325         (tflag == FTW_SLN) ? "sln" : "???",
 326         ftwbuf->level, (long long) sb->st_size,
 327         fpath, ftwbuf->base, fpath + ftwbuf->base);
 328     return 0;           /* To tell nftw() to continue */
 329 }
 330
 331 int
 332 main(int argc, char *argv[])
 333 {
 334     int flags = 0;
 335
 336     if (argc > 2 && strchr(argv[2], 'd') != NULL)
 337         flags |= FTW_DEPTH;
 338     if (argc > 2 && strchr(argv[2], 'p') != NULL)
 339         flags |= FTW_PHYS;
 340
 341     nftw((argc < 2) ? "." : argv[1], display_info, 20, flags);
 342     exit(EXIT_SUCCESS);
 343 }
 344 .fi
 345 .SH "SEE ALSO"
 346 .BR stat (2),
 347 .BR fts (3),
 348 .BR readdir (3)