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 .\"
  36 .TH FTW 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  37 .SH NAME
  38 ftw, nftw \- file tree walk
  39 .SH SYNOPSIS
  40 .nf
  41 .B #include <ftw.h>
  42 .PP
  43 .BI "int nftw(const char *" dirpath ,
  44 .BI "        int (*" fn ")(const char *" fpath ", const struct stat *" sb ,
  45 .BI "                  int " typeflag ", struct FTW *" ftwbuf ),
  46 .BI "        int " nopenfd ", int " flags );
  47 .PP
  48 .BI "int ftw(const char *" dirpath ,
  49 .BI "        int (*" fn ")(const char *" fpath ", const struct stat *" sb ,
  50 .BI "                  int " typeflag ),
  51 .BI "        int " nopenfd );
  52 .fi
  53 .PP
  54 .RS -4
  55 Feature Test Macro Requirements for glibc (see
  56 .BR feature_test_macros (7)):
  57 .RE
  58 .PP
  59 .BR nftw ():
  60 .nf
  61     _XOPEN_SOURCE >= 500
  62 .fi
  63 .SH DESCRIPTION
  64 .BR nftw ()
  65 walks through the directory tree that is
  66 located under the directory \fIdirpath\fP,
  67 and calls \fIfn\fP() once for each entry in the tree.
  68 By default, directories are handled before the files and
  69 subdirectories they contain (preorder traversal).
  70 .PP
  71 To avoid using up all of the calling process's file descriptors,
  72 \fInopenfd\fP specifies the maximum number of directories that
  73 .BR nftw ()
  74 will hold open simultaneously.
  75 When
  76 the search depth exceeds this,
  77 .BR nftw ()
  78 will become slower because
  79 directories have to be closed and reopened.
  80 .BR nftw ()
  81 uses at most
  82 one file descriptor for each level in the directory tree.
  83 .PP
  84 For each entry found in the tree,
  85 .BR nftw ()
  86 calls
  87 \fIfn\fP() with four arguments:
  88 .IR fpath ,
  89 .IR sb ,
  90 .IR typeflag ,
  91 and
  92 .IR ftwbuf .
  93 .I fpath
  94 is the pathname of the entry,
  95 and is expressed either as a pathname relative to the calling process's
  96 current working directory at the time of the call to
  97 .BR nftw (),
  98 if
  99 .IR dirpath
 100 was expressed as a relative pathname,
 101 or as an absolute pathname, if
 102 .I dirpath
 103 was expressed as an absolute pathname.
 104 .I sb
 105 is a pointer to the
 106 .I stat
 107 structure returned by a call to
 108 .BR stat (2)
 109 for
 110 .IR fpath .
 111 .PP
 112 The
 113 .I typeflag
 114 argument passed to
 115 .IR fn ()
 116 is an integer that has one of the following values:
 117 .TP
 118 .B FTW_F
 119 .I fpath
 120 is a regular file.
 121 .TP
 122 .B FTW_D
 123 .I fpath
 124 is a directory.
 125 .TP
 126 .B FTW_DNR
 127 .I fpath
 128 is a directory which can't be read.
 129 .TP
 130 .B FTW_DP
 131 .I fpath
 132 is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP.
 133 (If
 134 .B FTW_DEPTH
 135 was not specified in
 136 .IR flags ,
 137 then directories will always be visited with
 138 .I typeflag
 139 set to
 140 .BR FTW_D .)
 141 All of the files
 142 and subdirectories within \fIfpath\fP have been processed.
 143 .TP
 144 .B FTW_NS
 145 The
 146 .BR stat (2)
 147 call failed on
 148 .IR fpath ,
 149 which is not a symbolic link.
 150 The probable cause for this is that the caller had read permission
 151 on the parent directory, so that the filename
 152 .I fpath
 153 could be seen,
 154 but did not have execute permission,
 155 so that the file could not be reached for
 156 .BR stat (2).
 157 The contents of the buffer pointed to by
 158 .I sb
 159 are undefined.
 160 .TP
 161 .B FTW_SL
 162 .I fpath
 163 is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP.
 164 .\" To obtain the definition of this constant from
 165 .\" .IR <ftw.h> ,
 166 .\" either
 167 .\" .B _BSD_SOURCE
 168 .\" must be defined, or
 169 .\" .BR _XOPEN_SOURCE
 170 .\" must be defined with a value of 500 or more.
 171 .TP
 172 .B FTW_SLN
 173 .I fpath
 174 is a symbolic link pointing to a nonexistent file.
 175 (This occurs only if \fBFTW_PHYS\fP is not set.)
 176 In this case the
 177 .I sb
 178 argument passed to
 179 .IR fn ()
 180 contains information returned by performing
 181 .BR lstat (2)
 182 on the "dangling" symbolic link.
 183 (But see BUGS.)
 184 .PP
 185 The fourth argument
 186 .RI ( ftwbuf )
 187 that
 188 .BR nftw ()
 189 supplies when calling
 190 \fIfn\fP()
 191 is a pointer to a structure of type \fIFTW\fP:
 192 .PP
 193 .in +4n
 194 .EX
 195 struct FTW {
 196     int base;
 197     int level;
 198 };
 199 .EE
 200 .in
 201 .PP
 202 .I base
 203 is the offset of the filename (i.e., basename component)
 204 in the pathname given in
 205 .IR fpath .
 206 .I level
 207 is the depth of
 208 .I fpath
 209 in the directory tree, relative to the root of the tree
 210 .RI ( dirpath ,
 211 which has depth 0).
 212 .PP
 213 To stop the tree walk, \fIfn\fP() returns a nonzero value; this
 214 value will become the return value of
 215 .BR nftw ().
 216 As long as \fIfn\fP() returns 0,
 217 .BR nftw ()
 218 will continue either until it has traversed the entire tree,
 219 in which case it will return zero,
 220 or until it encounters an error (such as a
 221 .BR malloc (3)
 222 failure), in which case it will return \-1.
 223 .PP
 224 Because
 225 .BR nftw ()
 226 uses dynamic data structures, the only safe way to
 227 exit out of a tree walk is to return a nonzero value from \fIfn\fP().
 228 To allow a signal to terminate the walk without causing a memory leak,
 229 have the handler set a global flag that is checked by \fIfn\fP().
 230 \fIDon't\fP use
 231 .BR longjmp (3)
 232 unless the program is going to terminate.
 233 .PP
 234 The \fIflags\fP argument of
 235 .BR nftw ()
 236 is formed by ORing zero or more of the
 237 following flags:
 238 .TP
 239 .BR FTW_ACTIONRETVAL " (since glibc 2.3.3)"
 240 If this glibc-specific flag is set, then
 241 .BR nftw ()
 242 handles the return value from
 243 .IR fn ()
 244 differently.
 245 .IR fn ()
 246 should return one of the following values:
 247 .RS
 248 .TP
 249 .B FTW_CONTINUE
 250 Instructs
 251 .BR nftw ()
 252 to continue normally.
 253 .TP
 254 .B FTW_SKIP_SIBLINGS
 255 If \fIfn\fP() returns this value, then
 256 siblings of the current entry will be skipped,
 257 and processing continues in the parent.
 258 .\" If \fBFTW_DEPTH\fP
 259 .\" is set, the entry's parent directory is processed next (with
 260 .\" \fIflag\fP set to \fBFTW_DP\fP).
 261 .TP
 262 .B FTW_SKIP_SUBTREE
 263 If \fIfn\fP() is called with an entry that is a directory
 264 (\fItypeflag\fP is \fBFTW_D\fP), this return
 265 value will prevent objects within that directory from being passed as
 266 arguments to \fIfn\fP().
 267 .BR nftw ()
 268 continues processing with the next sibling of the directory.
 269 .TP
 270 .B FTW_STOP
 271 Causes
 272 .BR nftw ()
 273 to return immediately with the return value
 274 \fBFTW_STOP\fP.
 275 .PP
 276 Other return values could be associated with new actions in the future;
 277 \fIfn\fP() should not return values other than those listed above.
 278 .PP
 279 The feature test macro
 280 .B _GNU_SOURCE
 281 must be defined
 282 (before including
 283 .I any
 284 header files)
 285 in order to
 286 obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP.
 287 .RE
 288 .TP
 289 .B FTW_CHDIR
 290 If set, do a
 291 .BR chdir (2)
 292 to each directory before handling its contents.
 293 This is useful if the program needs to perform some action
 294 in the directory in which \fIfpath\fP resides.
 295 (Specifying this flag has no effect on the pathname that is passed in the
 296 .I fpath
 297 argument of
 298 .IR fn .)
 299 .TP
 300 .B FTW_DEPTH
 301 If set, do a post-order traversal, that is, call \fIfn\fP() for
 302 the directory itself \fIafter\fP handling the contents of the directory
 303 and its subdirectories.
 304 (By default, each directory is handled \fIbefore\fP its contents.)
 305 .TP
 306 .B FTW_MOUNT
 307 If set, stay within the same filesystem
 308 (i.e., do not cross mount points).
 309 .TP
 310 .B FTW_PHYS
 311 If set, do not follow symbolic links.
 312 (This is what you want.)
 313 If not set, symbolic links are followed, but no file is reported twice.
 314 .IP
 315 If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set,
 316 then the function
 317 .IR fn ()
 318 is never called for a directory that would be a descendant of itself.
 319 .SS ftw()
 320 .BR ftw ()
 321 is an older function that offers a subset of the functionality of
 322 .BR nftw ().
 323 The notable differences are as follows:
 324 .IP * 3
 325 .BR ftw ()
 326 has no
 327 .IR flags
 328 argument.
 329 It behaves the same as when
 330 .BR nftw ()
 331 is called with
 332 .I flags
 333 specified as zero.
 334 .IP *
 335 The callback function,
 336 .IR fn (),
 337 is not supplied with a fourth argument.
 338 .IP *
 339 The range of values that is passed via the
 340 .I typeflag
 341 argument supplied to
 342 .IR fn ()
 343 is smaller: just
 344 .BR FTW_F ,
 345 .BR FTW_D ,
 346 .BR FTW_DNR ,
 347 .BR FTW_NS ,
 348 and (possibly)
 349 .BR FTW_SL .
 350 .SH RETURN VALUE
 351 These functions return 0 on success, and \-1 if an error occurs.
 352 .PP
 353 If \fIfn\fP() returns nonzero,
 354 then the tree walk is terminated and the value returned by \fIfn\fP()
 355 is returned as the result of
 356 .BR ftw ()
 357 or
 358 .BR nftw ().
 359 .PP
 360 If
 361 .BR nftw ()
 362 is called with the \fBFTW_ACTIONRETVAL\fP flag,
 363 then the only nonzero value that should be used by \fIfn\fP()
 364 to terminate the tree walk is \fBFTW_STOP\fP,
 365 and that value is returned as the result of
 366 .BR nftw ().
 367 .SH VERSIONS
 368 .BR nftw ()
 369 is available under glibc since version 2.1.
 370 .SH ATTRIBUTES
 371 For an explanation of the terms used in this section, see
 372 .BR attributes (7).
 373 .ad l
 374 .nh
 375 .TS
 376 allbox;
 377 lbx lb lb
 378 l l l.
 379 Interface       Attribute       Value
 380 T{
 381 .BR nftw ()
 382 T}      Thread safety   MT-Safe cwd
 383 T{
 384 .BR ftw ()
 385 T}      Thread safety   MT-Safe
 386 .TE
 387 .hy
 388 .ad
 389 .sp 1
 390 .SH CONFORMING TO
 391 POSIX.1-2001, POSIX.1-2008, SVr4, SUSv1.
 392 POSIX.1-2008 marks
 393 .BR ftw ()
 394 as obsolete.
 395 .SH NOTES
 396 POSIX.1-2008 notes that the results are unspecified if
 397 .I fn
 398 does not preserve the current working directory.
 399 .PP
 400 The function
 401 .BR nftw ()
 402 and the use of \fBFTW_SL\fP with
 403 .BR ftw ()
 404 were introduced in SUSv1.
 405 .PP
 406 In some implementations (e.g., glibc),
 407 .BR ftw ()
 408 will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only
 409 for symbolic links that do not point to an existing file,
 410 and again on other systems
 411 .BR ftw ()
 412 will use \fBFTW_SL\fP for each symbolic link.
 413 If
 414 .I fpath
 415 is a symbolic link and
 416 .BR stat (2)
 417 failed, POSIX.1-2008 states
 418 that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP
 419 is passed in
 420 .IR typeflag .
 421 For predictable results, use
 422 .BR nftw ().
 423 .SH BUGS
 424 According to POSIX.1-2008, when the
 425 .IR typeflag
 426 argument passed to
 427 .IR fn ()
 428 contains
 429 .BR FTW_SLN ,
 430 the buffer pointed to by
 431 .I sb
 432 should contain information about the dangling symbolic link
 433 (obtained by calling
 434 .BR lstat (2)
 435 on the link).
 436 Early glibc versions correctly followed the POSIX specification on this point.
 437 However, as a result of a regression introduced in glibc 2.4,
 438 the contents of the buffer pointed to by
 439 .I sb
 440 were undefined when
 441 .B FTW_SLN
 442 is passed in
 443 .IR typeflag .
 444 (More precisely, the contents of the buffer were left unchanged in this case.)
 445 This regression was eventually fixed in glibc 2.30,
 446 .\" https://bugzilla.redhat.com/show_bug.cgi?id=1422736
 447 .\" http://austingroupbugs.net/view.php?id=1121
 448 .\" glibc commit 6ba205b2c35e3e024c8c12d2ee1b73363e84da87
 449 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=23501
 450 so that the glibc implementation (once more) follows the POSIX specification.
 451 .SH EXAMPLES
 452 The following program traverses the directory tree under the path named
 453 in its first command-line argument, or under the current directory
 454 if no argument is supplied.
 455 It displays various information about each file.
 456 The second command-line argument can be used to specify characters that
 457 control the value assigned to the \fIflags\fP
 458 argument when calling
 459 .BR nftw ().
 460 .SS Program source
 461 \&
 462 .EX
 463 #define _XOPEN_SOURCE 500
 464 #include <ftw.h>
 465 #include <stdio.h>
 466 #include <stdlib.h>
 467 #include <string.h>
 468 #include <stdint.h>
 469
 470 static int
 471 display_info(const char *fpath, const struct stat *sb,
 472              int tflag, struct FTW *ftwbuf)
 473 {
 474     printf("%\-3s %2d ",
 475             (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
 476             (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
 477             (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
 478             (tflag == FTW_SLN) ? "sln" : "???",
 479             ftwbuf\->level);
 480
 481     if (tflag == FTW_NS)
 482         printf("\-\-\-\-\-\-\-");
 483     else
 484         printf("%7jd", (intmax_t) sb\->st_size);
 485
 486     printf("   %\-40s %d %s\en",
 487             fpath, ftwbuf\->base, fpath + ftwbuf\->base);
 488
 489     return 0;           /* To tell nftw() to continue */
 490 }
 491
 492 int
 493 main(int argc, char *argv[])
 494 {
 495     int flags = 0;
 496
 497     if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL)
 498         flags |= FTW_DEPTH;
 499     if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL)
 500         flags |= FTW_PHYS;
 501
 502     if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
 503             == \-1) {
 504         perror("nftw");
 505         exit(EXIT_FAILURE);
 506     }
 507
 508     exit(EXIT_SUCCESS);
 509 }
 510 .EE
 511 .SH SEE ALSO
 512 .BR stat (2),
 513 .BR fts (3),
 514 .BR readdir (3)