1NFTW(3P)                   POSIX Programmer's Manual                  NFTW(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       nftw — walk a file tree
14

SYNOPSIS

16       #include <ftw.h>
17
18       int nftw(const char *path, int (*fn)(const char *,
19           const struct stat *, int, struct FTW *), int fd_limit, int flags);
20

DESCRIPTION

22       The nftw() function shall recursively descend the  directory  hierarchy
23       rooted  in  path.   The  nftw()  function has a similar effect to ftw()
24       except that it takes an additional argument flags, which is a  bitwise-
25       inclusive OR of zero or more of the following flags:
26
27       FTW_CHDIR   If  set,  nftw() shall change the current working directory
28                   to each directory as it reports files in that directory. If
29                   clear,  nftw()  shall not change the current working direc‐
30                   tory.
31
32       FTW_DEPTH   If set, nftw() shall report all files in a directory before
33                   reporting  the  directory  itself.  If  clear, nftw() shall
34                   report any directory before reporting  the  files  in  that
35                   directory.
36
37       FTW_MOUNT   If  set,  nftw()  shall  only report files in the same file
38                   system as path.  If clear, nftw() shall  report  all  files
39                   encountered during the walk.
40
41       FTW_PHYS    If  set, nftw() shall perform a physical walk and shall not
42                   follow symbolic links.
43
44       If FTW_PHYS is clear and FTW_DEPTH is set, nftw()  shall  follow  links
45       instead  of  reporting  them,  but  shall not report any directory that
46       would be a descendant of itself. If FTW_PHYS is clear and FTW_DEPTH  is
47       clear,  nftw()  shall follow links instead of reporting them, but shall
48       not report the contents of any directory that would be a descendant  of
49       itself.
50
51       At  each  file it encounters, nftw() shall call the user-supplied func‐
52       tion fn with four arguments:
53
54        *  The first argument is the pathname of the object.
55
56        *  The second argument is a pointer  to  the  stat  buffer  containing
57           information  on  the  object, filled in as if fstatat(), stat(), or
58           lstat() had been called to retrieve the information.
59
60        *  The third argument is an integer giving additional information. Its
61           value is one of the following:
62
63           FTW_D     The object is a directory.
64
65           FTW_DNR   The  object  is  a  directory that cannot be read. The fn
66                     function shall not be called for any of its descendants.
67
68           FTW_DP    The object is a directory and  subdirectories  have  been
69                     visited.   (This   condition  shall  only  occur  if  the
70                     FTW_DEPTH flag is included in flags.)
71
72           FTW_F     The object is a non-directory file.
73
74           FTW_NS    The stat() function failed on the object because of  lack
75                     of  appropriate  permission. The stat buffer passed to fn
76                     is undefined. Failure of stat() for any other  reason  is
77                     considered an error and nftw() shall return −1.
78
79           FTW_SL    The object is a symbolic link. (This condition shall only
80                     occur if the FTW_PHYS flag is included in flags.)
81
82           FTW_SLN   The object is a symbolic  link  that  does  not  name  an
83                     existing  file.   (This condition shall only occur if the
84                     FTW_PHYS flag is not included in flags.)
85
86        *  The fourth argument is a pointer to an FTW structure.  The value of
87           base  is the offset of the object's filename in the pathname passed
88           as the first argument to fn.  The value of  level  indicates  depth
89           relative to the root of the walk, where the root level is 0.
90
91       The  results  are  unspecified  if the application-supplied fn function
92       does not preserve the current working directory.
93
94       The argument fd_limit sets the maximum number of file descriptors  that
95       shall  be  used  by  nftw() while traversing the file tree. At most one
96       file descriptor shall be used for each directory level.
97
98       The nftw() function need not be thread-safe.
99

RETURN VALUE

101       The nftw() function shall continue until the  first  of  the  following
102       conditions occurs:
103
104        *  An  invocation  of  fn shall return a non-zero value, in which case
105           nftw() shall return that value.
106
107        *  The nftw() function detects  an  error  other  than  [EACCES]  (see
108           FTW_DNR and FTW_NS above), in which case nftw() shall return −1 and
109           set errno to indicate the error.
110
111        *  The tree is exhausted, in which case nftw() shall return 0.
112

ERRORS

114       The nftw() function shall fail if:
115
116       EACCES Search permission is denied for any component of  path  or  read
117              permission  is  denied  for  path, or fn returns −1 and does not
118              reset errno.
119
120       ELOOP  A loop exists in symbolic links encountered during resolution of
121              the path argument.
122
123       ENAMETOOLONG
124              The  length  of  a  component  of  a  pathname  is  longer  than
125              {NAME_MAX}.
126
127       ENOENT A component of path does not name an existing file or path is an
128              empty string.
129
130       ENOTDIR
131              A  component  of  path  names an existing file that is neither a
132              directory nor a symbolic link to a directory.
133
134       EOVERFLOW
135              A field in the stat structure cannot be represented correctly in
136              the  current programming environment for one or more files found
137              in the file hierarchy.
138
139       The nftw() function may fail if:
140
141       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
142              resolution of the path argument.
143
144       EMFILE All  file  descriptors  available  to  the process are currently
145              open.
146
147       ENAMETOOLONG
148              The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
149              tion  of  a symbolic link produced an intermediate result with a
150              length that exceeds {PATH_MAX}.
151
152       ENFILE Too many files are currently open in the system.
153
154       In addition, errno may be set if the function pointed to by  fn  causes
155       errno to be set.
156
157       The following sections are informative.
158

EXAMPLES

160       The following program traverses the directory tree under the path named
161       in its first command-line argument, or under the current  directory  if
162       no  argument  is  supplied.  It displays various information about each
163       file. The second command-line argument can be used to  specify  charac‐
164       ters that control the value assigned to the flags argument when calling
165       nftw().
166
167           #include <ftw.h>
168           #include <stdio.h>
169           #include <stdlib.h>
170           #include <string.h>
171           #include <stdint.h>
172
173           static int
174           display_info(const char *fpath, const struct stat *sb,
175               int tflag, struct FTW *ftwbuf)
176           {
177               printf("%-3s %2d %7jd   %-40s %d %s\n",
178                   (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
179                   (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?
180                       (S_ISBLK(sb->st_mode) ? "f b" :
181                        S_ISCHR(sb->st_mode) ? "f c" :
182                        S_ISFIFO(sb->st_mode) ? "f p" :
183                        S_ISREG(sb->st_mode) ? "f r" :
184                        S_ISSOCK(sb->st_mode) ? "f s" : "f ?") :
185                   (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
186                   (tflag == FTW_SLN) ? "sln" : "?",
187                   ftwbuf->level, (intmax_t) sb->st_size,
188                   fpath, ftwbuf->base, fpath + ftwbuf->base);
189               return 0;           /* To tell nftw() to continue */
190           }
191
192           int
193           main(int argc, char *argv[])
194           {
195               int flags = 0;
196
197               if (argc > 2 && strchr(argv[2], 'd') != NULL)
198                   flags |= FTW_DEPTH;
199               if (argc > 2 && strchr(argv[2], 'p') != NULL)
200                   flags |= FTW_PHYS;
201
202               if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) == -1)
203               {
204                   perror("nftw");
205                   exit(EXIT_FAILURE);
206               }
207
208               exit(EXIT_SUCCESS);
209           }
210

APPLICATION USAGE

212       The nftw() function may allocate dynamic storage during its  operation.
213       If  nftw() is forcibly terminated, such as by longjmp() or siglongjmp()
214       being executed by the function pointed to by fn or  an  interrupt  rou‐
215       tine, nftw() does not have a chance to free that storage, so it remains
216       permanently allocated. A safe way to handle interrupts is to store  the
217       fact  that  an interrupt has occurred, and arrange to have the function
218       pointed to by fn return a non-zero value at its next invocation.
219

RATIONALE

221       None.
222

FUTURE DIRECTIONS

224       None.
225

SEE ALSO

227       fdopendir(), fstatat(), readdir()
228
229       The Base Definitions volume of POSIX.1‐2008, <ftw.h>
230
232       Portions of this text are reprinted and reproduced in  electronic  form
233       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
234       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
235       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
236       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
237       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
238       event of any discrepancy between this version and the original IEEE and
239       The  Open Group Standard, the original IEEE and The Open Group Standard
240       is the referee document. The original Standard can be  obtained  online
241       at http://www.unix.org/online.html .
242
243       Any  typographical  or  formatting  errors that appear in this page are
244       most likely to have been introduced during the conversion of the source
245       files  to  man page format. To report such errors, see https://www.ker
246       nel.org/doc/man-pages/reporting_bugs.html .
247
248
249
250IEEE/The Open Group                  2013                             NFTW(3P)
Impressum