original/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@gmail.com>
   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@gmail.com>
  31 .\"     reorganized and rewrote much of the page
  32 .\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com>
  33 .\"     Added an example program.
  34 .TH FTW 3 2010-09-20 "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 .BI "        int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
  43 .BI "                   int " typeflag ),
  44 .BI "        int " nopenfd );
  45 .sp
  46 .BR "#define _XOPEN_SOURCE 500" "   /* See feature_test_macros(7) */"
  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 .BR ftw ()
  56 walks through the directory tree that is
  57 located under the directory \fIdirpath\fP,
  58 and calls \fIfn\fP() once for each entry in the tree.
  59 By default, directories are handled before the files and
  60 subdirectories they contain (preorder traversal).
  61
  62 To avoid using up all of the calling process's file descriptors,
  63 \fInopenfd\fP specifies the maximum number of directories that
  64 .BR ftw ()
  65 will hold open simultaneously.
  66 When
  67 the search depth exceeds this,
  68 .BR ftw ()
  69 will become slower because
  70 directories have to be closed and reopened.
  71 .BR ftw ()
  72 uses at most
  73 one file descriptor for each level in the directory tree.
  74
  75 For each entry found in the tree,
  76 .BR ftw ()
  77 calls
  78 \fIfn\fP() with three arguments:
  79 .IR fpath ,
  80 .IR sb ,
  81 and
  82 .IR typeflag .
  83 .I fpath
  84 is the pathname of the entry,
  85 and is expressed either as a pathname relative to the calling process's
  86 current working directory at the time of the call to
  87 .BR ftw (),
  88 if
  89 .IR dirpath
  90 was expressed as a relative pathname,
  91 or as an absolute pathname, if
  92 .I dirpath
  93 was expressed as an absolute pathname.
  94 .I sb
  95 is a pointer to the
  96 .I stat
  97 structure returned by a call to
  98 .BR stat (2)
  99 for
 100 .IR fpath .
 101 .I typeflag
 102 is an integer that has one of the following values:
 103 .TP
 104 .B FTW_F
 105 .I fpath
 106 is a regular file.
 107 .TP
 108 .B FTW_D
 109 .I fpath
 110 is a directory.
 111 .TP
 112 .B FTW_DNR
 113 .I fpath
 114 is a directory which can't be read.
 115 .TP
 116 .B FTW_NS
 117 The
 118 .BR stat (2)
 119 call failed on
 120 .IR fpath ,
 121 which is not a symbolic link.
 122 .sp
 123 If
 124 .I fpath
 125 is a symbolic link and
 126 .BR stat (2)
 127 failed, POSIX.1-2001 states
 128 that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP (see below)
 129 is passed in
 130 .IR typeflag .
 131 .PP
 132 To stop the tree walk, \fIfn\fP() returns a nonzero value; this
 133 value will become the return value of
 134 .BR ftw ().
 135 As long as \fIfn\fP() returns 0,
 136 .BR ftw ()
 137 will continue either until it has traversed the entire tree,
 138 in which case it will return zero,
 139 or until it encounters an error (such as a
 140 .BR malloc (3)
 141 failure), in which case it will return \-1.
 142 .PP
 143 Because
 144 .BR ftw ()
 145 uses dynamic data structures, the only safe way to
 146 exit out of a tree walk is to return a nonzero value from \fIfn\fP().
 147 To allow a signal to terminate the walk without causing a memory leak,
 148 have the handler set a global flag that is checked by \fIfn\fP().
 149 \fIDon't\fP use
 150 .BR longjmp (3)
 151 unless the program is going to terminate.
 152 .SS nftw()
 153 The function
 154 .BR nftw ()
 155 is the same as
 156 .BR ftw (),
 157 except that it has one additional argument, \fIflags\fP,
 158 and calls \fIfn\fP() with one more argument, \fIftwbuf\fP.
 159
 160 This \fIflags\fP argument is formed by ORing zero or more of the
 161 following flags:
 162 .TP
 163 .BR FTW_ACTIONRETVAL " (since glibc 2.3.3)"
 164 If this glibc-specific flag is set, then
 165 .BR nftw ()
 166 handles the return value from
 167 .IR fn ()
 168 differently.
 169 .IR fn ()
 170 should return one of the following values:
 171 .RS
 172 .TP
 173 .B FTW_CONTINUE
 174 Instructs
 175 .BR nftw ()
 176 to continue normally.
 177 .TP
 178 .B FTW_SKIP_SIBLINGS
 179 If \fIfn\fP() returns this value, then
 180 siblings of the current entry will be skipped,
 181 and processing continues in the parent.
 182 .\" If \fBFTW_DEPTH\fP
 183 .\" is set, the entry's parent directory is processed next (with
 184 .\" \fIflag\fP set to \fBFTW_DP\fP).
 185 .TP
 186 .B FTW_SKIP_SUBTREE
 187 If \fIfn\fP() is called with an entry that is a directory
 188 (\fItypeflag\fP is \fBFTW_D\fP), this return
 189 value will prevent objects within that directory from being passed as
 190 arguments to \fIfn\fP().
 191 .BR nftw ()
 192 continues processing with the next sibling of the directory.
 193 .TP
 194 .B FTW_STOP
 195 Causes
 196 .BR nftw ()
 197 to return immediately with the return value
 198 \fBFTW_STOP\fP.
 199 .PP
 200 Other return values could be associated with new actions in the future;
 201 \fIfn\fP() should not return values other than those listed above.
 202
 203 The feature test macro
 204 .B _GNU_SOURCE
 205 must be defined
 206 (before including
 207 .I any
 208 header files)
 209 in order to
 210 obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP.
 211 .RE
 212 .TP
 213 .B FTW_CHDIR
 214 If set, do a
 215 .BR chdir (2)
 216 to each directory before handling its contents.
 217 This is useful if the program needs to perform some action
 218 in the directory in which \fIfpath\fP resides.
 219 .TP
 220 .B FTW_DEPTH
 221 If set, do a post-order traversal, that is, call \fIfn\fP() for
 222 the directory itself \fIafter\fP handling the contents of the directory
 223 and its subdirectories.
 224 (By default, each directory is handled \fIbefore\fP its contents.)
 225 .TP
 226 .B FTW_MOUNT
 227 If set, stay within the same file system
 228 (i.e., do not cross mount points).
 229 .TP
 230 .B FTW_PHYS
 231 If set, do not follow symbolic links.
 232 (This is what you want.)
 233 If not set, symbolic links are followed, but no file is reported twice.
 234 .sp
 235 If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set,
 236 then the function
 237 .IR fn ()
 238 is never called for a directory that would be a descendant of itself.
 239 .LP
 240 For each entry in the directory tree,
 241 .BR nftw ()
 242 calls
 243 .IR fn ()
 244 with four arguments.
 245 .I fpath
 246 and
 247 .I sb
 248 are as for
 249 .BR ftw ().
 250 .I typeflag
 251 may receive any of the same values as with
 252 .BR ftw (),
 253 or any of the following values:
 254 .TP
 255 .B FTW_DP
 256 .I fpath
 257 is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP.
 258 All of the files
 259 and subdirectories within \fIfpath\fP have been processed.
 260 .TP
 261 .B FTW_SL
 262 .I fpath
 263 is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP.
 264 .\" To obtain the definition of this constant from
 265 .\" .IR <ftw.h> ,
 266 .\" either
 267 .\" .B _BSD_SOURCE
 268 .\" must be defined, or
 269 .\" .BR _XOPEN_SOURCE
 270 .\" must be defined with a value of 500 or more.
 271 .TP
 272 .B FTW_SLN
 273 .I fpath
 274 is a symbolic link pointing to a nonexistent file.
 275 (This occurs only if \fBFTW_PHYS\fP is not set.)
 276 .LP
 277 The fourth argument that
 278 .BR nftw ()
 279 supplies when calling
 280 \fIfn\fP()
 281 is a structure of type \fIFTW\fP:
 282 .in +4n
 283 .nf
 284
 285 struct FTW {
 286     int base;
 287     int level;
 288 };
 289
 290 .fi
 291 .in
 292 .I base
 293 is the offset of the filename (i.e., basename component)
 294 in the pathname given in
 295 .IR fpath .
 296 .I level
 297 is the depth of
 298 .I fpath
 299 in the directory tree, relative to the root of the tree
 300 .RI ( dirpath ,
 301 which has depth 0).
 302 .SH "RETURN VALUE"
 303 These functions return 0 on success, and \-1 if an error occurs.
 304
 305 If \fIfn\fP() returns nonzero,
 306 then the tree walk is terminated and the value returned by \fIfn\fP()
 307 is returned as the result of
 308 .BR ftw ()
 309 or
 310 .BR nftw ().
 311
 312 If
 313 .BR nftw ()
 314 is called with the \fBFTW_ACTIONRETVAL\fP flag,
 315 then the only nonzero value that should be used by \fIfn\fP()
 316 to terminate the tree walk is \fBFTW_STOP\fP,
 317 and that value is returned as the result of
 318 .BR nftw ().
 319 .SH "CONFORMING TO"
 320 POSIX.1-2001, SVr4, SUSv1.
 321 POSIX.1-2008 marks
 322 .BR ftw ()
 323 as obsolete.
 324 .SH NOTES
 325 POSIX.1-2001 note that the results are unspecified if
 326 .I fn
 327 does not preserve the current working directory.
 328 .PP
 329 The function
 330 .BR nftw ()
 331 and the use of \fBFTW_SL\fP with
 332 .BR ftw ()
 333 were introduced in SUSv1.
 334 .LP
 335 On some systems
 336 .BR ftw ()
 337 will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only
 338 for symbolic links that do not point to an existing file,
 339 and again on other systems
 340 .BR ftw ()
 341 will use \fBFTW_SL\fP for each symbolic link.
 342 For predictable control, use
 343 .BR nftw ().
 344 .LP
 345 Under Linux, libc4 and libc5 and glibc 2.0.6 will
 346 use \fBFTW_F\fP for all objects (files, symbolic links, FIFOs, etc.)
 347 that can be stat'ed but are not a directory.
 348
 349 The function
 350 .BR nftw ()
 351 is available since glibc 2.1.
 352
 353 \fBFTW_ACTIONRETVAL\fP is glibc-specific.
 354 .SH EXAMPLE
 355 The following program traverses the directory tree under the path named
 356 in its first command-line argument, or under the current directory
 357 if no argument is supplied.
 358 It displays various information about each file.
 359 The second command-line argument can be used to specify characters that
 360 control the value assigned to the \fIflags\fP
 361 argument when calling
 362 .BR nftw ().
 363 .nf
 364
 365 #define _XOPEN_SOURCE 500
 366 #include <ftw.h>
 367 #include <stdio.h>
 368 #include <stdlib.h>
 369 #include <string.h>
 370 #include <stdint.h>
 371
 372 static int
 373 display_info(const char *fpath, const struct stat *sb,
 374              int tflag, struct FTW *ftwbuf)
 375 {
 376     printf("%\-3s %2d %7jd   %\-40s %d %s\\n",
 377         (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
 378         (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
 379         (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
 380         (tflag == FTW_SLN) ? "sln" : "???",
 381         ftwbuf\->level, (intmax_t) sb\->st_size,
 382         fpath, ftwbuf\->base, fpath + ftwbuf\->base);
 383     return 0;           /* To tell nftw() to continue */
 384 }
 385
 386 int
 387 main(int argc, char *argv[])
 388 {
 389     int flags = 0;
 390
 391     if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL)
 392         flags |= FTW_DEPTH;
 393     if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL)
 394         flags |= FTW_PHYS;
 395
 396     if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
 397             == \-1) {
 398         perror("nftw");
 399         exit(EXIT_FAILURE);
 400     }
 401     exit(EXIT_SUCCESS);
 402 }
 403 .fi
 404 .SH "SEE ALSO"
 405 .BR stat (2),
 406 .BR fts (3),
 407 .BR readdir (3)