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

NAME

6       nftw - walk a file tree
7

SYNOPSIS

9       #include <ftw.h>
10
11       int nftw(const char *path, int (*fn)(const char *,
12              const struct stat *, int, struct FTW *), int depth, int flags);
13
14

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

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

APPLICATION USAGE

190       None.
191

RATIONALE

193       None.
194

FUTURE DIRECTIONS

196       None.
197

SEE ALSO

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