1ftw(3C)                  Standard C Library Functions                  ftw(3C)
2
3
4

NAME

6       ftw, nftw - walk a file tree
7

SYNOPSIS

9       #include <ftw.h>
10
11       int ftw(const char *path, int (*fn) (const char *,
12            const struct stat *, int), int depth);
13
14
15       int nftw(const char *path, int (*fn) (const char *,
16            const struct stat *, int, struct FTW *), int depth,
17            int flags);
18
19

DESCRIPTION

21       The  ftw() function recursively descends the directory hierarchy rooted
22       in path. For each object in the hierarchy, ftw() calls the user-defined
23       function fn, passing it a pointer to a null-terminated character string
24       containing the name of the object, a pointer to a stat  structure  (see
25       stat(2))  containing information about the object, and an integer. Pos‐
26       sible values of the integer, defined in the <ftw.h> header, are:
27
28       FTW_F      The object is a file.
29
30
31       FTW_D      The object is a directory.
32
33
34       FTW_DNR    The object is a directory that cannot be  read.  Descendants
35                  of the directory are not processed.
36
37
38       FTW_NS     The  stat() function failed on the object because of lack of
39                  appropriate permission or the object is a symbolic link that
40                  points  to a non-existent file. The stat buffer passed to fn
41                  is undefined.
42
43
44
45       The ftw() function visits  a  directory  before  visiting  any  of  its
46       descendants.
47
48
49       The tree traversal continues until the tree is exhausted, an invocation
50       of fn returns a non-zero value, or some error is detected within  ftw()
51       (such  as  an I/O error). If the tree is exhausted, ftw() returns 0. If
52       fn returns a non-zero value, ftw() stops its tree traversal and returns
53       whatever value was returned by fn.
54
55
56       The  nftw() function is similar to ftw() except that it takes the addi‐
57       tional argument flags, which is a bitwise-inclusive OR of zero or  more
58       of the following flags:
59
60       FTW_CHDIR    If  set,  nftw()  changes the current working directory to
61                    each directory as it reports files in that  directory.  If
62                    clear,  nftw()  does not change the current working direc‐
63                    tory.
64
65
66       FTW_DEPTH    If set, nftw() reports all files  in  a  directory  before
67                    reporting  the  directory itself. If clear, nftw() reports
68                    any directory before reporting the files  in  that  direc‐
69                    tory.
70
71
72       FTW_MOUNT    If  set, nftw() reports only files in the same file system
73                    as path. If clear, nftw() reports  all  files  encountered
74                    during the walk.
75
76
77       FTW_PHYS     If  set, nftw() performs a physical walk and does not fol‐
78                    low symbolic links.
79
80
81
82       If FTW_PHYS is clear and FTW_DEPTH is set, nftw() follows links instead
83       of  reporting  them,  but does not report any directory that would be a
84       descendant of itself. If FTW_PHYS is  clear  and  FTW_DEPTH  is  clear,
85       nftw() follows links instead of reporting them, but does not report the
86       contents of any directory that would be a descendant of itself.
87
88
89       At each file it encounters, nftw() calls the user-supplied function  fn
90       with four arguments:
91
92           o      The first argument is the pathname of the object.
93
94           o      The second argument is a pointer to the stat buffer contain‐
95                  ing information on the object.
96
97           o      The third argument is an integer giving additional  informa‐
98                  tion. Its value is one of the following:
99
100
101                  FTW_F      The object is a file.
102
103
104                  FTW_D      The object is a directory.
105
106
107                  FTW_DP     The object is a directory and subdirectories have
108                             been visited. (This condition only occurs if  the
109                             FTW_DEPTH flag is included in flags.)
110
111
112                  FTW_SL     The  object  is  a symbolic link. (This condition
113                             only occurs if the FTW_PHYS flag is  included  in
114                             flags.)
115
116
117                  FTW_SLN    The  object  is  a symbolic link that points to a
118                             non-existent file. (This condition only occurs if
119                             the FTW_PHYS flag is not included in flags.)
120
121
122                  FTW_DNR    The  object  is  a directory that cannot be read.
123                             The user-defined function fn will not  be  called
124                             for any of its descendants.
125
126
127                  FTW_NS     The  stat() function failed on the object because
128                             of lack of appropriate permission. The stat  buf‐
129                             fer passed to fn is undefined.  Failure of stat()
130                             for any other reason is considered an  error  and
131                             nftw() returns −1.
132
133
134
135           o      The  fourth  argument  is a pointer to an FTW structure that
136                  contains the following members:
137
138                    int   base;
139                    int   level;
140
141                  The base member is the offset of the  object's  filename  in
142                  the pathname passed as the first argument to fn(). The value
143                  of level indicates the depth relative to  the  root  of  the
144                  walk, where the root level is 0.
145
146                  The results are unspecified if the application-supplied fn()
147                  function does not preserve the current working directory.
148
149
150       Both ftw() and nftw() use one file descriptor for  each  level  in  the
151       tree. The depth argument limits the number of file descriptors used. If
152       depth is zero or negative, the effect is the same as if it were  1.  It
153       must  not  be  greater  than  the  number of file descriptors currently
154       available for use.  The ftw() function runs faster if depth is at least
155       as large as the number of levels in the tree. Both ftw() and nftw() are
156       able to descend to arbitrary depths in a file hierarchy and do not fail
157       due  to  path  length  limitations unless either the length of the path
158       name pointed to by the path argument exceeds  {PATH_MAX}  requirements,
159       or  for  ftw(),  the specified depth is less than 2, or for nftw(), the
160       specified depth is less than 2 and FTW_CHDIR is not set. When ftw() and
161       nftw()  return,  they close any file descriptors they have opened; they
162       do not close any file descriptors that might have been opened by fn.
163

RETURN VALUES

165       If the tree is exhausted, ftw() and nftw() return 0.  If  the  function
166       pointed  to by fn returns a non-zero value, ftw() and nftw() stop their
167       tree traversal and return whatever value was returned by  the  function
168       pointed  to by fn. If ftw() and nftw() detect an error,  they return −1
169       and set errno to indicate the error.
170
171
172       If ftw() and nftw() encounter an error other than EACCES (see   FTW_DNR
173       and FTW_NS above),  they return −1 and set errno to indicate the error.
174       The external variable errno can contain any error value that is  possi‐
175       ble  when  a  directory  is opened or when one of the stat functions is
176       executed on a directory or file.
177

ERRORS

179       The ftw() and nftw() functions will fail if:
180
181       ELOOP           A loop exists in symbolic links encountered during res‐
182                       olution of the path argument
183
184
185       ENAMETOOLONG    The  length  of  the  path  name pointed to by the path
186                       argument exceeds {PATH_MAX}, or a path  name  component
187                       is longer than {NAME_MAX}.
188
189
190       ENOENT          A  component  of path does not name an existing file or
191                       path is an empty string.
192
193
194       ENOTDIR         A component of path is not a directory.
195
196
197       EOVERFLOW       A field in the stat  structure  cannot  be  represented
198                       correctly  in  the  current programming environment for
199                       one or more files found in the file hierarchy.
200
201
202
203       The ftw() function will fail if:
204
205       EACCES          Search permission is denied for any component  of  path
206                       or read permission is denied for path.
207
208
209       ENAMETOOLONG    The ftw() function has descended to a path that exceeds
210                       {PATH_MAX} and the  depth  argument  specified  by  the
211                       application is less than 2 and FTW_CHDIR is not set.
212
213
214
215       The nftw() function will fail if:
216
217       EACCES    Search permission is denied for any component of path or read
218                 permission is denied for path, or fn() returns  −1  and  does
219                 not reset errno.
220
221
222
223       The nftw() and ftw() functions may fail if:
224
225       ELOOP           Too many symbolic links were encountered during resolu‐
226                       tion of the path argument.
227
228
229       ENAMETOOLONG    Pathname resolution of a symbolic link in the path name
230                       pointed  to by the path argument produced an intermedi‐
231                       ate result whose length exceeds {PATH_MAX}.
232
233
234
235       The ftw() function may fail if:
236
237       EINVAL    The value of the depth argument is invalid.
238
239
240
241       The nftw() function may fail if:
242
243       EMFILE    There are {OPEN_MAX} file descriptors currently open  in  the
244                 calling process.
245
246
247       ENFILE    Too many files are currently open in the system.
248
249
250
251       If the function pointed to by fn encounters system errors, errno may be
252       set accordingly.
253

EXAMPLES

255       Example 1 Walk a directory structure using ftw().
256
257
258       The following example walks the current  directory  structure,  calling
259       the  fn()  function  for  every  directory entry, using at most 10 file
260       descriptors:
261
262
263         #include <ftw.h>
264         ...
265         if (ftw(".", fn, 10) != 0) {
266                perror("ftw"); exit(2);
267         }
268
269
270       Example 2 Walk a directory structure using nftw().
271
272
273       The following example walks the /tmp directory and its  subdirectories,
274       calling  the nftw() function for every directory entry, to a maximum of
275       5 levels deep.
276
277
278         #include <ftw.h>
279         ...
280         int nftwfunc(const char *, const struct stat *, int, struct FTW *);
281         int nftwfunc(const char *filename, const struct stat *statptr,
282               int fileflags, struct FTW *pfwt)
283         {
284               return 0;
285         }
286         ...
287         char *startpath = "/tmp";
288         int depth = 5;
289         int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
290         int ret;
291         ret = nftw(startpath, nftwfunc, depth, flags);
292
293

USAGE

295       Because ftw() and nftw() are recursive, they can terminate with a  mem‐
296       ory fault when applied by a thread with a small stack to very deep file
297       structures.
298
299
300       The  ftw()  and  nftw()  functions  allocate  resources  (memory,  file
301       descriptors)  during their operation. If ftw() they are forcibly termi‐
302       nated, such as by longjmp(3C) being executed by fn or an interrupt rou‐
303       tine,  they  will  not  have  a chance to free those resources, so they
304       remain permanently allocated. A safe way to  handle  interrupts  is  to
305       store  the  fact  that an interrupt has occurred and arrange to have fn
306       return a non-zero value at its next invocation.
307
308
309       The ftw() and nftw() functions have transitional interfaces for  64-bit
310       file offsets.  See lf64(5).
311
312
313       The  ftw()  function  is safe in multithreaded applications. The nftw()
314       function is safe in multithreaded applications when the FTW_CHDIR  flag
315       is not set.
316

ATTRIBUTES

318       See attributes(5) for descriptions of the following attributes:
319
320
321
322
323       ┌─────────────────────────────┬─────────────────────────────┐
324       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
325       ├─────────────────────────────┼─────────────────────────────┤
326       │Interface Stability          │Standard                     │
327       ├─────────────────────────────┼─────────────────────────────┤
328       │MT-Level                     │MT-Safe with exceptions      │
329       └─────────────────────────────┴─────────────────────────────┘
330

SEE ALSO

332       stat(2), longjmp(3C), attributes(5), lf64(5), standards(5)
333
334
335
336SunOS 5.11                        30 Jan 2007                          ftw(3C)
Impressum