Debian Codegraph @

upstream/fedora-44/man3/ftw.3

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