Debian Codegraph @

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