]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 1993 Michael Haardt (michael@moria.de) |
538b02cc MK |
2 | .\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) |
3 | .\" and copyright (c) 2006 Justin Pryzby <justinpryzby@users.sf.net> | |
c11b1abf | 4 | .\" and copyright (c) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 5 | .\" |
e4a74ca8 | 6 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
fea681da MK |
7 | .\" |
8 | .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu) | |
538b02cc | 9 | .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> |
d282bb24 | 10 | .\" document FTW_ACTIONRETVAL; include .SH RETURN VALUE; |
538b02cc | 11 | .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> and |
c11b1abf | 12 | .\" Michael Kerrisk <mtk.manpages@gmail.com> |
538b02cc | 13 | .\" reorganized and rewrote much of the page |
c11b1abf | 14 | .\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com> |
538b02cc | 15 | .\" Added an example program. |
3dd43f24 | 16 | .\" |
1d767b55 | 17 | .TH FTW 3 2021-03-22 "Linux" "Linux Programmer's Manual" |
fea681da MK |
18 | .SH NAME |
19 | ftw, nftw \- file tree walk | |
cfba38f4 AC |
20 | .SH LIBRARY |
21 | Standard C library | |
22 | .RI ( libc ", " \-lc ) | |
fea681da | 23 | .SH SYNOPSIS |
538b02cc | 24 | .nf |
fea681da | 25 | .B #include <ftw.h> |
f90f031e | 26 | .PP |
d954cea8 | 27 | .BI "int nftw(const char *" dirpath , |
511bb71b MK |
28 | .BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb , |
29 | .BI " int " typeflag ", struct FTW *" ftwbuf ), | |
d954cea8 | 30 | .BI " int " nopenfd ", int " flags ); |
dbfe9c70 | 31 | .PP |
c13182ef | 32 | .BI "int ftw(const char *" dirpath , |
511bb71b MK |
33 | .BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb , |
34 | .BI " int " typeflag ), | |
8d3a1e4b | 35 | .BI " int " nopenfd ); |
d954cea8 | 36 | .fi |
68e4db0a | 37 | .PP |
d39ad78f | 38 | .RS -4 |
d954cea8 MK |
39 | Feature Test Macro Requirements for glibc (see |
40 | .BR feature_test_macros (7)): | |
d39ad78f | 41 | .RE |
68e4db0a | 42 | .PP |
d954cea8 | 43 | .BR nftw (): |
1dd0d7b4 MK |
44 | .nf |
45 | _XOPEN_SOURCE >= 500 | |
46 | .fi | |
fea681da | 47 | .SH DESCRIPTION |
d954cea8 | 48 | .BR nftw () |
60a90ecd | 49 | walks through the directory tree that is |
538b02cc MK |
50 | located under the directory \fIdirpath\fP, |
51 | and calls \fIfn\fP() once for each entry in the tree. | |
c13182ef | 52 | By default, directories are handled before the files and |
01d0a447 | 53 | subdirectories they contain (preorder traversal). |
847e0d88 | 54 | .PP |
c13182ef MK |
55 | To avoid using up all of the calling process's file descriptors, |
56 | \fInopenfd\fP specifies the maximum number of directories that | |
d954cea8 | 57 | .BR nftw () |
60a90ecd | 58 | will hold open simultaneously. |
538b02cc | 59 | When |
60a90ecd | 60 | the search depth exceeds this, |
d954cea8 | 61 | .BR nftw () |
60a90ecd MK |
62 | will become slower because |
63 | directories have to be closed and reopened. | |
d954cea8 | 64 | .BR nftw () |
60a90ecd | 65 | uses at most |
538b02cc | 66 | one file descriptor for each level in the directory tree. |
847e0d88 | 67 | .PP |
c13182ef | 68 | For each entry found in the tree, |
d954cea8 | 69 | .BR nftw () |
538b02cc | 70 | calls |
d954cea8 | 71 | \fIfn\fP() with four arguments: |
538b02cc MK |
72 | .IR fpath , |
73 | .IR sb , | |
d954cea8 | 74 | .IR typeflag , |
538b02cc | 75 | and |
d954cea8 | 76 | .IR ftwbuf . |
0daa9e92 | 77 | .I fpath |
e409862f MK |
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 | |
d954cea8 | 81 | .BR nftw (), |
e409862f | 82 | if |
1ae6b2c7 | 83 | .I dirpath |
e409862f MK |
84 | was expressed as a relative pathname, |
85 | or as an absolute pathname, if | |
86 | .I dirpath | |
87 | was expressed as an absolute pathname. | |
0daa9e92 | 88 | .I sb |
538b02cc | 89 | is a pointer to the |
0daa9e92 | 90 | .I stat |
c13182ef MK |
91 | structure returned by a call to |
92 | .BR stat (2) | |
93 | for | |
538b02cc | 94 | .IR fpath . |
847e0d88 | 95 | .PP |
cbc091e8 | 96 | The |
0daa9e92 | 97 | .I typeflag |
cbc091e8 MK |
98 | argument passed to |
99 | .IR fn () | |
538b02cc | 100 | is an integer that has one of the following values: |
fea681da MK |
101 | .TP |
102 | .B FTW_F | |
538b02cc | 103 | .I fpath |
21035964 | 104 | is a regular file. |
fea681da MK |
105 | .TP |
106 | .B FTW_D | |
538b02cc MK |
107 | .I fpath |
108 | is a directory. | |
fea681da MK |
109 | .TP |
110 | .B FTW_DNR | |
538b02cc MK |
111 | .I fpath |
112 | is a directory which can't be read. | |
fea681da | 113 | .TP |
d954cea8 MK |
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 | |
fea681da | 128 | .B FTW_NS |
c13182ef MK |
129 | The |
130 | .BR stat (2) | |
131 | call failed on | |
538b02cc MK |
132 | .IR fpath , |
133 | which is not a symbolic link. | |
b466283a MK |
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). | |
d252ac9d MK |
141 | The contents of the buffer pointed to by |
142 | .I sb | |
143 | are undefined. | |
d954cea8 MK |
144 | .TP |
145 | .B FTW_SL | |
538b02cc | 146 | .I fpath |
d954cea8 MK |
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.) | |
51827105 | 160 | In this case the |
687d31a4 MK |
161 | .I sb |
162 | argument passed to | |
163 | .IR fn () | |
164 | contains information returned by performing | |
165 | .BR lstat (2) | |
51827105 MK |
166 | on the "dangling" symbolic link. |
167 | (But see BUGS.) | |
d954cea8 | 168 | .PP |
b8f9afd0 MK |
169 | The fourth argument |
170 | .RI ( ftwbuf ) | |
171 | that | |
d954cea8 MK |
172 | .BR nftw () |
173 | supplies when calling | |
174 | \fIfn\fP() | |
b8f9afd0 | 175 | is a pointer to a structure of type \fIFTW\fP: |
e646a1ba | 176 | .PP |
d954cea8 | 177 | .in +4n |
e646a1ba | 178 | .EX |
d954cea8 MK |
179 | struct FTW { |
180 | int base; | |
181 | int level; | |
182 | }; | |
e646a1ba | 183 | .EE |
d954cea8 | 184 | .in |
e646a1ba | 185 | .PP |
d954cea8 MK |
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). | |
fea681da | 196 | .PP |
c7094399 | 197 | To stop the tree walk, \fIfn\fP() returns a nonzero value; this |
60a90ecd | 198 | value will become the return value of |
d954cea8 | 199 | .BR nftw (). |
538b02cc | 200 | As long as \fIfn\fP() returns 0, |
d954cea8 | 201 | .BR nftw () |
60a90ecd | 202 | will continue either until it has traversed the entire tree, |
c13182ef | 203 | in which case it will return zero, |
69515438 | 204 | or until it encounters an error (such as a |
fea681da MK |
205 | .BR malloc (3) |
206 | failure), in which case it will return \-1. | |
207 | .PP | |
60a90ecd | 208 | Because |
d954cea8 | 209 | .BR nftw () |
60a90ecd | 210 | uses dynamic data structures, the only safe way to |
c7094399 | 211 | exit out of a tree walk is to return a nonzero value from \fIfn\fP(). |
538b02cc MK |
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(). | |
60a90ecd MK |
214 | \fIDon't\fP use |
215 | .BR longjmp (3) | |
216 | unless the program is going to terminate. | |
847e0d88 | 217 | .PP |
cd358be3 | 218 | The \fIflags\fP argument of |
d954cea8 MK |
219 | .BR nftw () |
220 | is formed by ORing zero or more of the | |
538b02cc | 221 | following flags: |
fea681da | 222 | .TP |
538b02cc MK |
223 | .BR FTW_ACTIONRETVAL " (since glibc 2.3.3)" |
224 | If this glibc-specific flag is set, then | |
225 | .BR nftw () | |
69515438 | 226 | handles the return value from |
538b02cc MK |
227 | .IR fn () |
228 | differently. | |
229 | .IR fn () | |
230 | should return one of the following values: | |
231 | .RS | |
232 | .TP | |
233 | .B FTW_CONTINUE | |
60a90ecd MK |
234 | Instructs |
235 | .BR nftw () | |
236 | to continue normally. | |
538b02cc | 237 | .TP |
5a967310 MK |
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). | |
538b02cc MK |
245 | .TP |
246 | .B FTW_SKIP_SUBTREE | |
c13182ef | 247 | If \fIfn\fP() is called with an entry that is a directory |
538b02cc MK |
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 | |
5a967310 | 254 | .B FTW_STOP |
60a90ecd MK |
255 | Causes |
256 | .BR nftw () | |
257 | to return immediately with the return value | |
5a967310 | 258 | \fBFTW_STOP\fP. |
538b02cc | 259 | .PP |
c13182ef | 260 | Other return values could be associated with new actions in the future; |
538b02cc | 261 | \fIfn\fP() should not return values other than those listed above. |
847e0d88 | 262 | .PP |
c3dfd2c8 MK |
263 | The feature test macro |
264 | .B _GNU_SOURCE | |
e417acb0 MK |
265 | must be defined |
266 | (before including | |
267 | .I any | |
268 | header files) | |
269 | in order to | |
538b02cc MK |
270 | obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP. |
271 | .RE | |
b7924f02 MK |
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. | |
a00ca3d5 MK |
279 | (Specifying this flag has no effect on the pathname that is passed in the |
280 | .I fpath | |
281 | argument of | |
282 | .IR fn .) | |
b7924f02 MK |
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 | |
9ee4a2b6 | 291 | If set, stay within the same filesystem |
0be9413e | 292 | (i.e., do not cross mount points). |
b7924f02 MK |
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. | |
bdd915e2 | 298 | .IP |
c13182ef | 299 | If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set, |
b7924f02 MK |
300 | then the function |
301 | .IR fn () | |
302 | is never called for a directory that would be a descendant of itself. | |
d954cea8 MK |
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 | |
1ae6b2c7 | 311 | .I flags |
d954cea8 MK |
312 | argument. |
313 | It behaves the same as when | |
538b02cc | 314 | .BR nftw () |
d954cea8 MK |
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 | |
538b02cc | 324 | .I typeflag |
d954cea8 MK |
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 . | |
47297adb | 334 | .SH RETURN VALUE |
538b02cc | 335 | These functions return 0 on success, and \-1 if an error occurs. |
847e0d88 | 336 | .PP |
c7094399 | 337 | If \fIfn\fP() returns nonzero, |
538b02cc | 338 | then the tree walk is terminated and the value returned by \fIfn\fP() |
60a90ecd MK |
339 | is returned as the result of |
340 | .BR ftw () | |
341 | or | |
342 | .BR nftw (). | |
847e0d88 | 343 | .PP |
60a90ecd MK |
344 | If |
345 | .BR nftw () | |
346 | is called with the \fBFTW_ACTIONRETVAL\fP flag, | |
c7094399 | 347 | then the only nonzero value that should be used by \fIfn\fP() |
c13182ef | 348 | to terminate the tree walk is \fBFTW_STOP\fP, |
60a90ecd MK |
349 | and that value is returned as the result of |
350 | .BR nftw (). | |
0b158300 MK |
351 | .SH VERSIONS |
352 | .BR nftw () | |
353 | is available under glibc since version 2.1. | |
a83934bf ZL |
354 | .SH ATTRIBUTES |
355 | For an explanation of the terms used in this section, see | |
356 | .BR attributes (7). | |
c466875e MK |
357 | .ad l |
358 | .nh | |
a83934bf ZL |
359 | .TS |
360 | allbox; | |
c466875e | 361 | lbx lb lb |
a83934bf ZL |
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 | |
c466875e MK |
371 | .hy |
372 | .ad | |
847e0d88 | 373 | .sp 1 |
47297adb | 374 | .SH CONFORMING TO |
c47fe813 | 375 | POSIX.1-2001, POSIX.1-2008, SVr4, SUSv1. |
b7be83b7 MK |
376 | POSIX.1-2008 marks |
377 | .BR ftw () | |
378 | as obsolete. | |
fea681da | 379 | .SH NOTES |
f6c19db0 | 380 | POSIX.1-2008 notes that the results are unspecified if |
743e7eb3 MK |
381 | .I fn |
382 | does not preserve the current working directory. | |
383 | .PP | |
fea681da | 384 | The function |
31e9a9ec | 385 | .BR nftw () |
8d3a1e4b | 386 | and the use of \fBFTW_SL\fP with |
31e9a9ec | 387 | .BR ftw () |
68e1685c | 388 | were introduced in SUSv1. |
dd3568a1 | 389 | .PP |
d954cea8 | 390 | In some implementations (e.g., glibc), |
31e9a9ec | 391 | .BR ftw () |
8d3a1e4b | 392 | will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only |
fea681da MK |
393 | for symbolic links that do not point to an existing file, |
394 | and again on other systems | |
31e9a9ec | 395 | .BR ftw () |
c13182ef | 396 | will use \fBFTW_SL\fP for each symbolic link. |
d954cea8 MK |
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 | |
31e9a9ec | 406 | .BR nftw (). |
34a2ee18 | 407 | .SH BUGS |
51827105 | 408 | According to POSIX.1-2008, when the |
1ae6b2c7 | 409 | .I typeflag |
51827105 MK |
410 | argument passed to |
411 | .IR fn () | |
412 | contains | |
413 | .BR FTW_SLN , | |
414 | the buffer pointed to by | |
34a2ee18 | 415 | .I sb |
51827105 MK |
416 | should contain information about the dangling symbolic link |
417 | (obtained by calling | |
34a2ee18 | 418 | .BR lstat (2) |
51827105 MK |
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 | |
34a2ee18 | 423 | .I sb |
51827105 | 424 | were undefined when |
34a2ee18 MK |
425 | .B FTW_SLN |
426 | is passed in | |
427 | .IR typeflag . | |
51827105 MK |
428 | (More precisely, the contents of the buffer were left unchanged in this case.) |
429 | This regression was eventually fixed in glibc 2.30, | |
34a2ee18 MK |
430 | .\" https://bugzilla.redhat.com/show_bug.cgi?id=1422736 |
431 | .\" http://austingroupbugs.net/view.php?id=1121 | |
99192e5f MK |
432 | .\" glibc commit 6ba205b2c35e3e024c8c12d2ee1b73363e84da87 |
433 | .\" https://sourceware.org/bugzilla/show_bug.cgi?id=23501 | |
51827105 | 434 | so that the glibc implementation (once more) follows the POSIX specification. |
a14af333 | 435 | .SH EXAMPLES |
69515438 MK |
436 | The following program traverses the directory tree under the path named |
437 | in its first command-line argument, or under the current directory | |
538b02cc MK |
438 | if no argument is supplied. |
439 | It displays various information about each file. | |
76c44d83 | 440 | The second command-line argument can be used to specify characters that |
c13182ef | 441 | control the value assigned to the \fIflags\fP |
60a90ecd MK |
442 | argument when calling |
443 | .BR nftw (). | |
f30b7415 | 444 | .SS Program source |
c7885256 | 445 | \& |
e7d0bb47 | 446 | .EX |
538b02cc MK |
447 | #define _XOPEN_SOURCE 500 |
448 | #include <ftw.h> | |
449 | #include <stdio.h> | |
450 | #include <stdlib.h> | |
451 | #include <string.h> | |
a15ae69a | 452 | #include <stdint.h> |
538b02cc MK |
453 | |
454 | static int | |
c13182ef | 455 | display_info(const char *fpath, const struct stat *sb, |
538b02cc MK |
456 | int tflag, struct FTW *ftwbuf) |
457 | { | |
88f78c4a MK |
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 | ||
d1a71985 | 470 | printf(" %\-40s %d %s\en", |
88f78c4a MK |
471 | fpath, ftwbuf\->base, fpath + ftwbuf\->base); |
472 | ||
538b02cc MK |
473 | return 0; /* To tell nftw() to continue */ |
474 | } | |
475 | ||
476 | int | |
477 | main(int argc, char *argv[]) | |
478 | { | |
479 | int flags = 0; | |
480 | ||
f81fb444 | 481 | if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL) |
538b02cc | 482 | flags |= FTW_DEPTH; |
f81fb444 | 483 | if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL) |
538b02cc MK |
484 | flags |= FTW_PHYS; |
485 | ||
e4b7f997 MK |
486 | if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) |
487 | == \-1) { | |
488 | perror("nftw"); | |
a15ae69a MK |
489 | exit(EXIT_FAILURE); |
490 | } | |
88f78c4a | 491 | |
538b02cc MK |
492 | exit(EXIT_SUCCESS); |
493 | } | |
e7d0bb47 | 494 | .EE |
47297adb | 495 | .SH SEE ALSO |
c2dd39b4 | 496 | .BR stat (2), |
b7924f02 | 497 | .BR fts (3), |
0a4f8b7b | 498 | .BR readdir (3) |