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