1FTW(3)                     Linux Programmer's Manual                    FTW(3)
2
3
4

NAME

6       ftw, nftw - file tree walk
7

SYNOPSIS

9       #include <ftw.h>
10
11       int ftw(const char *dirpath,
12               int (*fn) (const char *fpath, const struct stat *sb,
13                          int typeflag),
14               int nopenfd);
15
16       #define _XOPEN_SOURCE 500
17       #include <ftw.h>
18
19       int nftw(const char *dirpath,
20               int (*fn) (const char *fpath, const struct stat *sb,
21                          int typeflag, struct FTW *ftwbuf),
22               int nopenfd, int flags);
23

DESCRIPTION

25       ftw() walks through the directory tree that is located under the direc‐
26       tory dirpath, and calls fn() once for  each  entry  in  the  tree.   By
27       default,  directories  are  handled before the files and subdirectories
28       they contain (pre-order traversal).
29
30       To avoid using up  all  of  the  calling  process's  file  descriptors,
31       nopenfd  specifies  the  maximum  number of directories that ftw() will
32       hold open simultaneously.  When the search depth  exceeds  this,  ftw()
33       will  become slower because directories have to be closed and reopened.
34       ftw() uses at most one file descriptor for each level in the  directory
35       tree.
36
37       For  each  entry  found  in the tree, ftw() calls fn() with three argu‐
38       ments: fpath, sb, and typeflag.  fpath is the  pathname  of  the  entry
39       relative to dirpath.  sb is a pointer to the stat structure returned by
40       a call to stat(2) for fpath.  typeflag is an integer that  has  one  of
41       the following values:
42
43       FTW_F  fpath is a regular file.
44
45       FTW_D  fpath is a directory.
46
47       FTW_DNR
48              fpath is a directory which can't be read.
49
50       FTW_NS The stat(2) call failed on fpath, which is not a symbolic link.
51
52              If  fpath  is  a  symbolic link and stat(2) failed, POSIX.1-2001
53              states that it is undefined whether FTW_NS or FTW_SL (see below)
54              is passed in typeflag.
55
56       To  stop  the tree walk, fn() returns a non-zero value; this value will
57       become the return value of ftw().  As long as  fn()  returns  0,  ftw()
58       will  continue  either until it has traversed the entire tree, in which
59       case it will return zero, or until it encounters an error  (such  as  a
60       malloc(3) failure), in which case it will return -1.
61
62       Because  ftw()  uses dynamic data structures, the only safe way to exit
63       out of a tree walk is to return a non-zero value from fn().  To allow a
64       signal  to  terminate  the walk without causing a memory leak, have the
65       handler set  a  global  flag  that  is  checked  by  fn().   Don't  use
66       longjmp(3) unless the program is going to terminate.
67
68   nftw()
69       The  function nftw() is the same as ftw(), except that it has one addi‐
70       tional argument, flags, and calls fn() with one more argument, ftwbuf.
71
72       This flags argument is formed by ORing zero or more  of  the  following
73       flags:
74
75       FTW_ACTIONRETVAL (since glibc 2.3.3)
76              If  this  glibc-specific  flag  is  set, then nftw() handles the
77              return value from fn() differently.  fn() should return  one  of
78              the following values:
79
80              FTW_CONTINUE
81                     Instructs nftw() to continue normally.
82
83              FTW_SKIP_SIBLINGS
84                     If  fn() returns this value, then siblings of the current
85                     entry will be skipped, and processing  continues  in  the
86                     parent.
87
88              FTW_SKIP_SUBTREE
89                     If  fn()  is  called  with  an  entry that is a directory
90                     (typeflag is  FTW_D),  this  return  value  will  prevent
91                     objects  within that directory from being passed as argu‐
92                     ments to fn().  nftw() continues processing with the next
93                     sibling of the directory.
94
95              FTW_STOP
96                     Causes nftw() to return immediately with the return value
97                     FTW_STOP.
98
99              Other return values could be associated with new actions in  the
100              future;  fn()  should  not return values other than those listed
101              above.
102
103              The feature test macro _GNU_SOURCE must be defined in  order  to
104              obtain the definition of FTW_ACTIONRETVAL from <ftw.h>.
105
106       FTW_CHDIR
107              If set, do a chdir(2) to each directory before handling its con‐
108              tents.  This is useful if the  program  needs  to  perform  some
109              action in the directory in which fpath resides.
110
111       FTW_DEPTH
112              If  set,  do  a post-order traversal, that is, call fn() for the
113              directory itself after handling the contents  of  the  directory
114              and  its subdirectories.  (By default, each directory is handled
115              before its contents.)
116
117       FTW_MOUNT
118              If set, stay within the same file system  (i.e.,  do  not  cross
119              mount points).
120
121       FTW_PHYS
122              If  set, do not follow symbolic links.  (This is what you want.)
123              If not set, symbolic links are followed, but no file is reported
124              twice.
125
126              If  FTW_PHYS is not set, but FTW_DEPTH is set, then the function
127              fn() is never called for a directory that would be a  descendant
128              of itself.
129
130       For each entry in the directory tree, nftw() calls fn() with four argu‐
131       ments.  fpath and sb are as for ftw().  typeflag may receive any of the
132       same values as with ftw(), or any of the following values:
133
134       FTW_DP fpath is a directory, and FTW_DEPTH was specified in flags.  All
135              of the files and subdirectories  within  fpath  have  been  pro‐
136              cessed.
137
138       FTW_SL fpath is a symbolic link, and FTW_PHYS was set in flags.
139
140       FTW_SLN
141              fpath  is a symbolic link pointing to a nonexistent file.  (This
142              occurs only if FTW_PHYS is not set.)
143
144       The fourth argument that nftw() supplies when calling fn() is a  struc‐
145       ture of type FTW:
146
147           struct FTW {
148               int base;
149               int level;
150           };
151
152       base  is  the  offset of the filename (i.e., basename component) in the
153       pathname given in fpath.  level is the depth of fpath in the  directory
154       tree, relative to the root of the tree (dirpath, which has depth 0).
155

RETURN VALUE

157       These functions return 0 on success, and -1 if an error occurs.
158
159       If  fn()  returns  non-zero,  then  the tree walk is terminated and the
160       value returned by fn() is returned as the result of ftw() or nftw().
161
162       If nftw() is called with the FTW_ACTIONRETVAL flag, then the only  non-
163       zero  value  that  should be used by fn() to terminate the tree walk is
164       FTW_STOP, and that value is returned as the result of nftw().
165

CONFORMING TO

167       POSIX.1-2001, SVr4, SUSv1.  POSIX.1-2008 marks ftw() as obsolete.
168

NOTES

170       The function nftw() and the use of FTW_SL with ftw() were introduced in
171       SUSv1.
172
173       On  some  systems  ftw() will never use FTW_SL, on other systems FTW_SL
174       occurs only for symbolic links that do not point to an  existing  file,
175       and  again  on  other  systems  ftw() will use FTW_SL for each symbolic
176       link.  For predictable control, use nftw().
177
178       Under Linux, libc4 and libc5 and glibc 2.0.6 will  use  FTW_F  for  all
179       objects  (files,  symbolic links, FIFOs, etc.)  that can be stat'ed but
180       are not a directory.
181
182       The function nftw() is available since glibc 2.1.
183
184       FTW_ACTIONRETVAL is glibc-specific.
185

EXAMPLE

187       The following program traverses the directory tree under the path named
188       in  its  first command-line argument, or under the current directory if
189       no argument is supplied.  It displays various  information  about  each
190       file.   The second command-line argument can be used to specify charac‐
191       ters that control the value assigned to the flags argument when calling
192       nftw().
193
194       #define _XOPEN_SOURCE 500
195       #include <ftw.h>
196       #include <stdio.h>
197       #include <stdlib.h>
198       #include <string.h>
199       #include <stdint.h>
200
201       static int
202       display_info(const char *fpath, const struct stat *sb,
203                    int tflag, struct FTW *ftwbuf)
204       {
205           printf("%-3s %2d %7jd   %-40s %d %s\n",
206               (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
207               (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
208               (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
209               (tflag == FTW_SLN) ? "sln" : "???",
210               ftwbuf->level, (intmax_t) sb->st_size,
211               fpath, ftwbuf->base, fpath + ftwbuf->base);
212           return 0;           /* To tell nftw() to continue */
213       }
214
215       int
216       main(int argc, char *argv[])
217       {
218           int flags = 0;
219
220           if (argc > 2 && strchr(argv[2], 'd') != NULL)
221               flags |= FTW_DEPTH;
222           if (argc > 2 && strchr(argv[2], 'p') != NULL)
223               flags |= FTW_PHYS;
224
225           if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
226                   == -1) {
227               perror("nftw");
228               exit(EXIT_FAILURE);
229           }
230           exit(EXIT_SUCCESS);
231       }
232

SEE ALSO

234       stat(2), fts(3), readdir(3), feature_test_macros(7)
235

COLOPHON

237       This  page  is  part of release 3.22 of the Linux man-pages project.  A
238       description of the project, and information about reporting  bugs,  can
239       be found at http://www.kernel.org/doc/man-pages/.
240
241
242
243Linux                             2008-08-06                            FTW(3)
Impressum