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       int ftw(const char *dirpath,
17               int (*fn)(const char *fpath, const struct stat *sb,
18                         int typeflag),
19               int nopenfd);
20
21   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
22
23       nftw():
24           _XOPEN_SOURCE >= 500
25

DESCRIPTION

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

RETURN VALUE

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

VERSIONS

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

ATTRIBUTES

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

CONFORMING TO

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

NOTES

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

BUGS

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

EXAMPLES

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

SEE ALSO

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

COLOPHON

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