]>
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 MK |
5 | .\" |
6 | .\" This is free documentation; you can redistribute it and/or | |
7 | .\" modify it under the terms of the GNU General Public License as | |
8 | .\" published by the Free Software Foundation; either version 2 of | |
9 | .\" the License, or (at your option) any later version. | |
10 | .\" | |
11 | .\" The GNU General Public License's references to "object code" | |
12 | .\" and "executables" are to be interpreted as the output of any | |
13 | .\" document formatting or typesetting system, including | |
14 | .\" intermediate and printed output. | |
15 | .\" | |
16 | .\" This manual is distributed in the hope that it will be useful, | |
17 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 | .\" GNU General Public License for more details. | |
20 | .\" | |
21 | .\" You should have received a copy of the GNU General Public | |
c715f741 MK |
22 | .\" License along with this manual; if not, see |
23 | .\" <http://www.gnu.org/licenses/>. | |
fea681da MK |
24 | .\" |
25 | .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu) | |
538b02cc | 26 | .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> |
c13182ef | 27 | .\" document FTW_ACTIONRETVAL; include .SH "RETURN VALUE"; |
538b02cc | 28 | .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> and |
c11b1abf | 29 | .\" Michael Kerrisk <mtk.manpages@gmail.com> |
538b02cc | 30 | .\" reorganized and rewrote much of the page |
c11b1abf | 31 | .\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com> |
538b02cc | 32 | .\" Added an example program. |
50831f9b | 33 | .TH FTW 3 2010-09-20 "Linux" "Linux Programmer's Manual" |
fea681da MK |
34 | .SH NAME |
35 | ftw, nftw \- file tree walk | |
36 | .SH SYNOPSIS | |
538b02cc | 37 | .nf |
fea681da MK |
38 | .B #include <ftw.h> |
39 | .sp | |
c13182ef | 40 | .BI "int ftw(const char *" dirpath , |
ca313a68 | 41 | .BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb , |
538b02cc | 42 | .BI " int " typeflag ), |
8d3a1e4b | 43 | .BI " int " nopenfd ); |
fea681da | 44 | .sp |
b80f966b | 45 | .BR "#define _XOPEN_SOURCE 500" " /* See feature_test_macros(7) */" |
538b02cc MK |
46 | .B #include <ftw.h> |
47 | .sp | |
c13182ef MK |
48 | .BI "int nftw(const char *" dirpath , |
49 | .BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb , | |
538b02cc | 50 | .BI " int " typeflag ", struct FTW *" ftwbuf ), |
8d3a1e4b | 51 | .BI " int " nopenfd ", int " flags ); |
538b02cc | 52 | .fi |
fea681da | 53 | .SH DESCRIPTION |
60a90ecd MK |
54 | .BR ftw () |
55 | walks through the directory tree that is | |
538b02cc MK |
56 | located under the directory \fIdirpath\fP, |
57 | and calls \fIfn\fP() once for each entry in the tree. | |
c13182ef | 58 | By default, directories are handled before the files and |
01d0a447 | 59 | subdirectories they contain (preorder traversal). |
538b02cc | 60 | |
c13182ef MK |
61 | To avoid using up all of the calling process's file descriptors, |
62 | \fInopenfd\fP specifies the maximum number of directories that | |
60a90ecd MK |
63 | .BR ftw () |
64 | will hold open simultaneously. | |
538b02cc | 65 | When |
60a90ecd MK |
66 | the search depth exceeds this, |
67 | .BR ftw () | |
68 | will become slower because | |
69 | directories have to be closed and reopened. | |
70 | .BR ftw () | |
71 | uses at most | |
538b02cc MK |
72 | one file descriptor for each level in the directory tree. |
73 | ||
c13182ef | 74 | For each entry found in the tree, |
538b02cc MK |
75 | .BR ftw () |
76 | calls | |
77 | \fIfn\fP() with three arguments: | |
78 | .IR fpath , | |
79 | .IR sb , | |
80 | and | |
81 | .IR typeflag . | |
0daa9e92 | 82 | .I fpath |
e409862f MK |
83 | is the pathname of the entry, |
84 | and is expressed either as a pathname relative to the calling process's | |
85 | current working directory at the time of the call to | |
86 | .BR ftw (), | |
87 | if | |
88 | .IR dirpath | |
89 | was expressed as a relative pathname, | |
90 | or as an absolute pathname, if | |
91 | .I dirpath | |
92 | was expressed as an absolute pathname. | |
0daa9e92 | 93 | .I sb |
538b02cc | 94 | is a pointer to the |
0daa9e92 | 95 | .I stat |
c13182ef MK |
96 | structure returned by a call to |
97 | .BR stat (2) | |
98 | for | |
538b02cc | 99 | .IR fpath . |
0daa9e92 | 100 | .I typeflag |
538b02cc | 101 | is an integer that has one of the following values: |
fea681da MK |
102 | .TP |
103 | .B FTW_F | |
538b02cc | 104 | .I fpath |
21035964 | 105 | is a regular file. |
fea681da MK |
106 | .TP |
107 | .B FTW_D | |
538b02cc MK |
108 | .I fpath |
109 | is a directory. | |
fea681da MK |
110 | .TP |
111 | .B FTW_DNR | |
538b02cc MK |
112 | .I fpath |
113 | is a directory which can't be read. | |
fea681da MK |
114 | .TP |
115 | .B FTW_NS | |
c13182ef MK |
116 | The |
117 | .BR stat (2) | |
118 | call failed on | |
538b02cc MK |
119 | .IR fpath , |
120 | which is not a symbolic link. | |
69515438 | 121 | .sp |
c13182ef | 122 | If |
538b02cc | 123 | .I fpath |
c13182ef | 124 | is a symbolic link and |
538b02cc | 125 | .BR stat (2) |
a7fadb55 | 126 | failed, POSIX.1-2001 states |
538b02cc MK |
127 | that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP (see below) |
128 | is passed in | |
129 | .IR typeflag . | |
fea681da | 130 | .PP |
c7094399 | 131 | To stop the tree walk, \fIfn\fP() returns a nonzero value; this |
60a90ecd MK |
132 | value will become the return value of |
133 | .BR ftw (). | |
538b02cc | 134 | As long as \fIfn\fP() returns 0, |
60a90ecd MK |
135 | .BR ftw () |
136 | will continue either until it has traversed the entire tree, | |
c13182ef | 137 | in which case it will return zero, |
69515438 | 138 | or until it encounters an error (such as a |
fea681da MK |
139 | .BR malloc (3) |
140 | failure), in which case it will return \-1. | |
141 | .PP | |
60a90ecd MK |
142 | Because |
143 | .BR ftw () | |
144 | uses dynamic data structures, the only safe way to | |
c7094399 | 145 | exit out of a tree walk is to return a nonzero value from \fIfn\fP(). |
538b02cc MK |
146 | To allow a signal to terminate the walk without causing a memory leak, |
147 | have the handler set a global flag that is checked by \fIfn\fP(). | |
60a90ecd MK |
148 | \fIDon't\fP use |
149 | .BR longjmp (3) | |
150 | unless the program is going to terminate. | |
538b02cc | 151 | .SS nftw() |
60a90ecd MK |
152 | The function |
153 | .BR nftw () | |
154 | is the same as | |
155 | .BR ftw (), | |
538b02cc MK |
156 | except that it has one additional argument, \fIflags\fP, |
157 | and calls \fIfn\fP() with one more argument, \fIftwbuf\fP. | |
fea681da | 158 | |
c13182ef | 159 | This \fIflags\fP argument is formed by ORing zero or more of the |
538b02cc | 160 | following flags: |
fea681da | 161 | .TP |
538b02cc MK |
162 | .BR FTW_ACTIONRETVAL " (since glibc 2.3.3)" |
163 | If this glibc-specific flag is set, then | |
164 | .BR nftw () | |
69515438 | 165 | handles the return value from |
538b02cc MK |
166 | .IR fn () |
167 | differently. | |
168 | .IR fn () | |
169 | should return one of the following values: | |
170 | .RS | |
171 | .TP | |
172 | .B FTW_CONTINUE | |
60a90ecd MK |
173 | Instructs |
174 | .BR nftw () | |
175 | to continue normally. | |
538b02cc | 176 | .TP |
5a967310 MK |
177 | .B FTW_SKIP_SIBLINGS |
178 | If \fIfn\fP() returns this value, then | |
179 | siblings of the current entry will be skipped, | |
180 | and processing continues in the parent. | |
181 | .\" If \fBFTW_DEPTH\fP | |
182 | .\" is set, the entry's parent directory is processed next (with | |
183 | .\" \fIflag\fP set to \fBFTW_DP\fP). | |
538b02cc MK |
184 | .TP |
185 | .B FTW_SKIP_SUBTREE | |
c13182ef | 186 | If \fIfn\fP() is called with an entry that is a directory |
538b02cc MK |
187 | (\fItypeflag\fP is \fBFTW_D\fP), this return |
188 | value will prevent objects within that directory from being passed as | |
189 | arguments to \fIfn\fP(). | |
190 | .BR nftw () | |
191 | continues processing with the next sibling of the directory. | |
192 | .TP | |
5a967310 | 193 | .B FTW_STOP |
60a90ecd MK |
194 | Causes |
195 | .BR nftw () | |
196 | to return immediately with the return value | |
5a967310 | 197 | \fBFTW_STOP\fP. |
538b02cc | 198 | .PP |
c13182ef | 199 | Other return values could be associated with new actions in the future; |
538b02cc MK |
200 | \fIfn\fP() should not return values other than those listed above. |
201 | ||
c3dfd2c8 MK |
202 | The feature test macro |
203 | .B _GNU_SOURCE | |
e417acb0 MK |
204 | must be defined |
205 | (before including | |
206 | .I any | |
207 | header files) | |
208 | in order to | |
538b02cc MK |
209 | obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP. |
210 | .RE | |
b7924f02 MK |
211 | .TP |
212 | .B FTW_CHDIR | |
213 | If set, do a | |
214 | .BR chdir (2) | |
215 | to each directory before handling its contents. | |
216 | This is useful if the program needs to perform some action | |
217 | in the directory in which \fIfpath\fP resides. | |
218 | .TP | |
219 | .B FTW_DEPTH | |
220 | If set, do a post-order traversal, that is, call \fIfn\fP() for | |
221 | the directory itself \fIafter\fP handling the contents of the directory | |
222 | and its subdirectories. | |
223 | (By default, each directory is handled \fIbefore\fP its contents.) | |
224 | .TP | |
225 | .B FTW_MOUNT | |
c13182ef | 226 | If set, stay within the same file system |
0be9413e | 227 | (i.e., do not cross mount points). |
b7924f02 MK |
228 | .TP |
229 | .B FTW_PHYS | |
230 | If set, do not follow symbolic links. | |
231 | (This is what you want.) | |
232 | If not set, symbolic links are followed, but no file is reported twice. | |
233 | .sp | |
c13182ef | 234 | If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set, |
b7924f02 MK |
235 | then the function |
236 | .IR fn () | |
237 | is never called for a directory that would be a descendant of itself. | |
fea681da | 238 | .LP |
538b02cc MK |
239 | For each entry in the directory tree, |
240 | .BR nftw () | |
c13182ef | 241 | calls |
fea681da | 242 | .IR fn () |
538b02cc MK |
243 | with four arguments. |
244 | .I fpath | |
c13182ef | 245 | and |
538b02cc | 246 | .I sb |
c13182ef | 247 | are as for |
538b02cc MK |
248 | .BR ftw (). |
249 | .I typeflag | |
250 | may receive any of the same values as with | |
251 | .BR ftw (), | |
252 | or any of the following values: | |
fea681da MK |
253 | .TP |
254 | .B FTW_DP | |
538b02cc | 255 | .I fpath |
c13182ef | 256 | is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP. |
538b02cc MK |
257 | All of the files |
258 | and subdirectories within \fIfpath\fP have been processed. | |
259 | .TP | |
260 | .B FTW_SL | |
261 | .I fpath | |
262 | is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP. | |
05b39220 MK |
263 | .\" To obtain the definition of this constant from |
264 | .\" .IR <ftw.h> , | |
265 | .\" either | |
266 | .\" .B _BSD_SOURCE | |
267 | .\" must be defined, or | |
268 | .\" .BR _XOPEN_SOURCE | |
269 | .\" must be defined with a value of 500 or more. | |
fea681da MK |
270 | .TP |
271 | .B FTW_SLN | |
538b02cc MK |
272 | .I fpath |
273 | is a symbolic link pointing to a nonexistent file. | |
69515438 | 274 | (This occurs only if \fBFTW_PHYS\fP is not set.) |
fea681da | 275 | .LP |
538b02cc MK |
276 | The fourth argument that |
277 | .BR nftw () | |
c13182ef | 278 | supplies when calling |
538b02cc | 279 | \fIfn\fP() |
69515438 | 280 | is a structure of type \fIFTW\fP: |
088a639b | 281 | .in +4n |
538b02cc MK |
282 | .nf |
283 | ||
284 | struct FTW { | |
285 | int base; | |
286 | int level; | |
287 | }; | |
288 | ||
289 | .fi | |
a08ea57c | 290 | .in |
538b02cc | 291 | .I base |
c13182ef MK |
292 | is the offset of the filename (i.e., basename component) |
293 | in the pathname given in | |
538b02cc | 294 | .IR fpath . |
0daa9e92 | 295 | .I level |
c13182ef | 296 | is the depth of |
538b02cc MK |
297 | .I fpath |
298 | in the directory tree, relative to the root of the tree | |
299 | .RI ( dirpath , | |
300 | which has depth 0). | |
47297adb | 301 | .SH RETURN VALUE |
538b02cc MK |
302 | These functions return 0 on success, and \-1 if an error occurs. |
303 | ||
c7094399 | 304 | If \fIfn\fP() returns nonzero, |
538b02cc | 305 | then the tree walk is terminated and the value returned by \fIfn\fP() |
60a90ecd MK |
306 | is returned as the result of |
307 | .BR ftw () | |
308 | or | |
309 | .BR nftw (). | |
538b02cc | 310 | |
60a90ecd MK |
311 | If |
312 | .BR nftw () | |
313 | is called with the \fBFTW_ACTIONRETVAL\fP flag, | |
c7094399 | 314 | then the only nonzero value that should be used by \fIfn\fP() |
c13182ef | 315 | to terminate the tree walk is \fBFTW_STOP\fP, |
60a90ecd MK |
316 | and that value is returned as the result of |
317 | .BR nftw (). | |
47297adb | 318 | .SH CONFORMING TO |
2b2581ee | 319 | POSIX.1-2001, SVr4, SUSv1. |
b7be83b7 MK |
320 | POSIX.1-2008 marks |
321 | .BR ftw () | |
322 | as obsolete. | |
fea681da | 323 | .SH NOTES |
743e7eb3 MK |
324 | POSIX.1-2001 note that the results are unspecified if |
325 | .I fn | |
326 | does not preserve the current working directory. | |
327 | .PP | |
fea681da | 328 | The function |
31e9a9ec | 329 | .BR nftw () |
8d3a1e4b | 330 | and the use of \fBFTW_SL\fP with |
31e9a9ec | 331 | .BR ftw () |
68e1685c | 332 | were introduced in SUSv1. |
fea681da MK |
333 | .LP |
334 | On some systems | |
31e9a9ec | 335 | .BR ftw () |
8d3a1e4b | 336 | will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only |
fea681da MK |
337 | for symbolic links that do not point to an existing file, |
338 | and again on other systems | |
31e9a9ec | 339 | .BR ftw () |
c13182ef MK |
340 | will use \fBFTW_SL\fP for each symbolic link. |
341 | For predictable control, use | |
31e9a9ec | 342 | .BR nftw (). |
fea681da MK |
343 | .LP |
344 | Under Linux, libc4 and libc5 and glibc 2.0.6 will | |
7de99918 | 345 | use \fBFTW_F\fP for all objects (files, symbolic links, FIFOs, etc.) |
fea681da | 346 | that can be stat'ed but are not a directory. |
538b02cc | 347 | |
fea681da | 348 | The function |
31e9a9ec | 349 | .BR nftw () |
fea681da | 350 | is available since glibc 2.1. |
538b02cc | 351 | |
8382f16d | 352 | \fBFTW_ACTIONRETVAL\fP is glibc-specific. |
538b02cc | 353 | .SH EXAMPLE |
69515438 MK |
354 | The following program traverses the directory tree under the path named |
355 | in its first command-line argument, or under the current directory | |
538b02cc MK |
356 | if no argument is supplied. |
357 | It displays various information about each file. | |
76c44d83 | 358 | The second command-line argument can be used to specify characters that |
c13182ef | 359 | control the value assigned to the \fIflags\fP |
60a90ecd MK |
360 | argument when calling |
361 | .BR nftw (). | |
538b02cc MK |
362 | .nf |
363 | ||
538b02cc MK |
364 | #define _XOPEN_SOURCE 500 |
365 | #include <ftw.h> | |
366 | #include <stdio.h> | |
367 | #include <stdlib.h> | |
368 | #include <string.h> | |
a15ae69a | 369 | #include <stdint.h> |
538b02cc MK |
370 | |
371 | static int | |
c13182ef | 372 | display_info(const char *fpath, const struct stat *sb, |
538b02cc MK |
373 | int tflag, struct FTW *ftwbuf) |
374 | { | |
a15ae69a | 375 | printf("%\-3s %2d %7jd %\-40s %d %s\\n", |
bb3b776e MK |
376 | (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" : |
377 | (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" : | |
e055032e | 378 | (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" : |
538b02cc | 379 | (tflag == FTW_SLN) ? "sln" : "???", |
a15ae69a | 380 | ftwbuf\->level, (intmax_t) sb\->st_size, |
29059a65 | 381 | fpath, ftwbuf\->base, fpath + ftwbuf\->base); |
538b02cc MK |
382 | return 0; /* To tell nftw() to continue */ |
383 | } | |
384 | ||
385 | int | |
386 | main(int argc, char *argv[]) | |
387 | { | |
388 | int flags = 0; | |
389 | ||
f81fb444 | 390 | if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL) |
538b02cc | 391 | flags |= FTW_DEPTH; |
f81fb444 | 392 | if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL) |
538b02cc MK |
393 | flags |= FTW_PHYS; |
394 | ||
e4b7f997 MK |
395 | if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) |
396 | == \-1) { | |
397 | perror("nftw"); | |
a15ae69a MK |
398 | exit(EXIT_FAILURE); |
399 | } | |
538b02cc MK |
400 | exit(EXIT_SUCCESS); |
401 | } | |
402 | .fi | |
47297adb | 403 | .SH SEE ALSO |
c2dd39b4 | 404 | .BR stat (2), |
b7924f02 | 405 | .BR fts (3), |
0a4f8b7b | 406 | .BR readdir (3) |