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