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 depth, int flags);
19
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
28              If  set,  nftw()  shall  change the current working directory to
29              each directory as it reports files in that directory. If  clear,
30              nftw() shall not change the current working directory.
31
32       FTW_DEPTH
33              If  set,  nftw()  shall  report  all files in a directory before
34              reporting the directory itself. If clear,  nftw()  shall  report
35              any directory before reporting the files in that directory.
36
37       FTW_MOUNT
38              If  set,  nftw() shall only report files in the same file system
39              as path. If clear, nftw() shall  report  all  files  encountered
40              during the walk.
41
42       FTW_PHYS
43              If  set, nftw() shall perform a physical walk and shall not fol‐
44              low symbolic links.
45
46
47       If FTW_PHYS is clear and FTW_DEPTH is set, nftw()  shall  follow  links
48       instead  of  reporting  them,  but  shall not report any directory that
49       would be a descendant of itself. If FTW_PHYS is clear and FTW_DEPTH  is
50       clear,  nftw()  shall follow links instead of reporting them, but shall
51       not report the contents of any directory that would be a descendant  of
52       itself.
53
54       At  each  file it encounters, nftw() shall call the user-supplied func‐
55       tion fn with four arguments:
56
57        * The first argument is the pathname of the object.
58
59        * The second argument is a  pointer  to  the  stat  buffer  containing
60          information on the object.
61
62        * The  third argument is an integer giving additional information. Its
63          value is one of the following:
64
65       FTW_F
66              The object is a file.
67
68       FTW_D
69              The object is a directory.
70
71       FTW_DP
72              The object is a directory and subdirectories have been  visited.
73              (This  condition  shall  only  occur  if  the  FTW_DEPTH flag is
74              included in flags.)
75
76       FTW_SL
77              The object is a symbolic link. (This condition shall only  occur
78              if the FTW_PHYS flag is included in flags.)
79
80       FTW_SLN
81              The  object  is  a  symbolic link that does not name an existing
82              file.  (This condition shall only occur if the FTW_PHYS flag  is
83              not included in flags.)
84
85       FTW_DNR
86              The  object  is a directory that cannot be read. The fn function
87              shall not be called for any of its descendants.
88
89       FTW_NS
90              The stat() function failed on the  object  because  of  lack  of
91              appropriate  permission.   The stat buffer passed to fn is unde‐
92              fined. Failure of stat() for any other reason is  considered  an
93              error and nftw() shall return -1.
94
95
96        * The  fourth  argument is a pointer to an FTW structure. The value of
97          base is the offset of the object's filename in the  pathname  passed
98          as the first argument to fn. The value of level indicates depth rel‐
99          ative to the root of the walk, where the root level is 0.
100
101       The results are unspecified if  the  application-supplied  fn  function
102       does not preserve the current working directory.
103
104       The  argument  depth  sets  the maximum number of file descriptors that
105       shall be used by nftw() while traversing the file  tree.  At  most  one
106       file descriptor shall be used for each directory level.
107
108       The  nftw()  function  need  not  be  reentrant. A function that is not
109       required to be reentrant is not required to be thread-safe.
110

RETURN VALUE

112       The nftw() function shall continue until the  first  of  the  following
113       conditions occurs:
114
115        * An  invocation  of  fn  shall return a non-zero value, in which case
116          nftw() shall return that value.
117
118        * The nftw() function  detects  an  error  other  than  [EACCES]  (see
119          FTW_DNR  and FTW_NS above), in which case nftw() shall return -1 and
120          set errno to indicate the error.
121
122        * The tree is exhausted, in which case nftw() shall return 0.
123

ERRORS

125       The nftw() function shall fail if:
126
127       EACCES Search permission is denied for any component of  path  or  read
128              permission  is  denied  for  path, or fn returns -1 and does not
129              reset errno.
130
131       ELOOP  A loop exists in symbolic links encountered during resolution of
132              the path argument.
133
134       ENAMETOOLONG
135              The length of the path argument exceeds {PATH_MAX} or a pathname
136              component is longer than {NAME_MAX}.
137
138       ENOENT A component of path does not name an existing file or path is an
139              empty string.
140
141       ENOTDIR
142              A component of path is not a directory.
143
144       EOVERFLOW
145              A field in the stat structure cannot be represented correctly in
146              the current programming environment for one or more files  found
147              in the file hierarchy.
148
149
150       The nftw() function may fail if:
151
152       ELOOP  More  than  {SYMLOOP_MAX} symbolic links were encountered during
153              resolution of the path argument.
154
155       EMFILE {OPEN_MAX} file descriptors are currently open  in  the  calling
156              process.
157
158       ENAMETOOLONG
159              Pathname  resolution of a symbolic link produced an intermediate
160              result whose length exceeds {PATH_MAX}.
161
162       ENFILE Too many files are currently open in the system.
163
164
165       In addition, errno may be set if the function pointed to by  fn  causes
166       errno to be set.
167
168       The following sections are informative.
169

EXAMPLES

171       The  following example walks the /tmp directory and its subdirectories,
172       calling the nftw() function for every directory entry, to a maximum  of
173       5 levels deep.
174
175
176              #include <ftw.h>
177              ...
178              int nftwfunc(const char *, const struct stat *, int, struct FTW *);
179
180
181              int nftwfunc(const char *filename, const struct stat *statptr,
182                  int fileflags, struct FTW *pfwt)
183              {
184                  return 0;
185              }
186              ...
187              char *startpath = "/tmp";
188              int depth = 5;
189              int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
190              int ret;
191
192
193              ret = nftw(startpath, nftwfunc, depth, flags);
194

APPLICATION USAGE

196       None.
197

RATIONALE

199       None.
200

FUTURE DIRECTIONS

202       None.
203

SEE ALSO

205       lstat(),  opendir(),  readdir(), stat(), the Base Definitions volume of
206       IEEE Std 1003.1-2001, <ftw.h>
207
209       Portions of this text are reprinted and reproduced in  electronic  form
210       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
211       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
212       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
213       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
214       event of any discrepancy between this version and the original IEEE and
215       The Open Group Standard, the original IEEE and The Open Group  Standard
216       is  the  referee document. The original Standard can be obtained online
217       at http://www.opengroup.org/unix/online.html .
218
219
220
221IEEE/The Open Group                  2003                             NFTW(3P)
Impressum