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 nftw(const char *dirpath,
12               int (*fn) (const char *fpath, const struct stat *sb,
13                          int typeflag, struct FTW *ftwbuf),
14               int nopenfd, int flags);
15
16       #include <ftw.h>
17
18       int ftw(const char *dirpath,
19               int (*fn) (const char *fpath, const struct stat *sb,
20                          int typeflag),
21               int nopenfd);
22
23   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
24
25       nftw(): _XOPEN_SOURCE >= 500
26

DESCRIPTION

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

RETURN VALUE

177       These functions return 0 on success, and -1 if an error occurs.
178
179       If fn() returns nonzero, then the tree walk is terminated and the value
180       returned by fn() is returned as the result of ftw() or nftw().
181
182       If  nftw()  is  called  with  the  FTW_ACTIONRETVAL flag, then the only
183       nonzero value that should be used by fn() to terminate the tree walk is
184       FTW_STOP, and that value is returned as the result of nftw().
185

VERSIONS

187       nftw() is available under glibc since version 2.1.
188

ATTRIBUTES

190       For   an   explanation   of   the  terms  used  in  this  section,  see
191       attributes(7).
192
193       ┌──────────┬───────────────┬─────────────┐
194Interface Attribute     Value       
195       ├──────────┼───────────────┼─────────────┤
196nftw()    │ Thread safety │ MT-Safe cwd │
197       ├──────────┼───────────────┼─────────────┤
198ftw()     │ Thread safety │ MT-Safe     │
199       └──────────┴───────────────┴─────────────┘
200

CONFORMING TO

202       POSIX.1-2001, POSIX.1-2008, SVr4, SUSv1.  POSIX.1-2008 marks  ftw()  as
203       obsolete.
204

NOTES

206       POSIX.1-2008 notes that the results are unspecified if fn does not pre‐
207       serve the current working directory.
208
209       The function nftw() and the use of FTW_SL with ftw() were introduced in
210       SUSv1.
211
212       In  some implementations (e.g., glibc), ftw() will never use FTW_SL, on
213       other systems FTW_SL occurs only for symbolic links that do  not  point
214       to  an  existing file, and again on other systems ftw() will use FTW_SL
215       for each symbolic link.  If  fpath  is  a  symbolic  link  and  stat(2)
216       failed,  POSIX.1-2008  states  that  it  is undefined whether FTW_NS or
217       FTW_SL is passed in typeflag.  For predictable results, use nftw().
218

BUGS

220       According to POSIX.1-2008, when the typeflag argument  passed  to  fn()
221       contains  FTW_SLN,  the buffer pointed to by sb should contain informa‐
222       tion about the dangling symbolic link (obtained by calling lstat(2)  on
223       the  link).  Early glibc versions correctly followed the POSIX specifi‐
224       cation on this point.  However, as a result of a regression  introduced
225       in  glibc  2.4,  the contents of the buffer pointed to by sb were unde‐
226       fined when FTW_SLN is passed in typeflag.  (More  precisely,  the  con‐
227       tents of the buffer were left unchanged in this case.)  This regression
228       was eventually fixed in glibc 2.30, so that  the  glibc  implementation
229       (once more) follows the POSIX specification.
230

EXAMPLES

232       The following program traverses the directory tree under the path named
233       in its first command-line argument, or under the current  directory  if
234       no  argument  is  supplied.  It displays various information about each
235       file.  The second command-line argument can be used to specify  charac‐
236       ters that control the value assigned to the flags argument when calling
237       nftw().
238
239   Program source
240
241       #define _XOPEN_SOURCE 500
242       #include <ftw.h>
243       #include <stdio.h>
244       #include <stdlib.h>
245       #include <string.h>
246       #include <stdint.h>
247
248       static int
249       display_info(const char *fpath, const struct stat *sb,
250                    int tflag, struct FTW *ftwbuf)
251       {
252           printf("%-3s %2d ",
253                   (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
254                   (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
255                   (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
256                   (tflag == FTW_SLN) ? "sln" : "???",
257                   ftwbuf->level);
258
259           if (tflag == FTW_NS)
260               printf("-------");
261           else
262               printf("%7jd", (intmax_t) sb->st_size);
263
264           printf("   %-40s %d %s\n",
265                   fpath, ftwbuf->base, fpath + ftwbuf->base);
266
267           return 0;           /* To tell nftw() to continue */
268       }
269
270       int
271       main(int argc, char *argv[])
272       {
273           int flags = 0;
274
275           if (argc > 2 && strchr(argv[2], 'd') != NULL)
276               flags |= FTW_DEPTH;
277           if (argc > 2 && strchr(argv[2], 'p') != NULL)
278               flags |= FTW_PHYS;
279
280           if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
281                   == -1) {
282               perror("nftw");
283               exit(EXIT_FAILURE);
284           }
285
286           exit(EXIT_SUCCESS);
287       }
288

SEE ALSO

290       stat(2), fts(3), readdir(3)
291

COLOPHON

293       This page is part of release 5.07 of the Linux  man-pages  project.   A
294       description  of  the project, information about reporting bugs, and the
295       latest    version    of    this    page,    can     be     found     at
296       https://www.kernel.org/doc/man-pages/.
297
298
299
300Linux                             2020-06-09                            FTW(3)
Impressum