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

NAME

12       nftw — walk a file tree
13

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

159       The following program traverses the directory tree under the path named
160       in its first command-line argument, or under the current  directory  if
161       no  argument  is  supplied.  It displays various information about each
162       file. The second command-line argument can be used to  specify  charac‐
163       ters that control the value assigned to the flags argument when calling
164       nftw().
165
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‐2017, <ftw.h>
230
232       Portions of this text are reprinted and reproduced in  electronic  form
233       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
234       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
235       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
236       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
237       event of any discrepancy between this version and the original IEEE and
238       The Open Group Standard, the original IEEE and The Open Group  Standard
239       is  the  referee document. The original Standard can be obtained online
240       at http://www.opengroup.org/unix/online.html .
241
242       Any typographical or formatting errors that appear  in  this  page  are
243       most likely to have been introduced during the conversion of the source
244       files to man page format. To report such errors,  see  https://www.ker
245       nel.org/doc/man-pages/reporting_bugs.html .
246
247
248
249IEEE/The Open Group                  2017                             NFTW(3P)
Impressum