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