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