Debian Codegraph @

upstream/debian-unstable/man3/ftw.3

raw
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)