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