The functions to handle files in directories described so far allowed to
retrieve all the information in small pieces or process all files in a
directory (see scandir
). Sometimes it is useful to process whole
hierarchies of directories and the contained files. The X/Open
specification define two functions to do this. The simpler form is
derived from an early definition in System V systems and therefore
this function is available on SVID derived systems. The prototypes and
required definitions can be found in the `ftw.h' header.
Both functions of this ftw
family take as one of the arguments a
reference to a callback function. The functions must be of these types.
int (*) (const char *, const struct stat *, int)
Type for callback functions given to the ftw
function. The first
parameter will contain a pointer to the filename, the second parameter
will point to an object of type struct stat
which will be filled
for the file named by the first parameter.
The last parameter is a flag given more information about the current file. It can have the following values:
FTW_F
FTW_D
FTW_NS
stat
call to fill the object pointed to by the second
parameter failed and so the information is invalid.
FTW_DNR
FTW_SL
ftw
callback function means the referenced
file does not exist. The situation for nftw
is different.
This value is only available if the program is compiled with
_BSD_SOURCE
or _XOPEN_EXTENDED
defined before including
the first header. The original SVID systems do not have symbolic links.
If the sources are compiled with _FILE_OFFSET_BITS == 64
this
type is in fact __ftw64_func_t
since this mode also changes
struct stat
to be struct stat64
.
For the LFS interface and the use in the function ftw64
the
header `ftw.h' defines another function type.
int (*) (const char *, const struct stat64 *, int)
This type is used just like __ftw_func_t
for the callback
function, but this time called from ftw64
. The second parameter
to the function is this time a pointer to a variable of type
struct stat64
which is able to represent the larger values.
int (*) (const char *, const struct stat *, int, struct FTW *)
The first three arguments have the same as for the __ftw_func_t
type. A difference is that for the third argument some additional
values are defined to allow finer differentiation:
FTW_DP
FTW_D
if
the FTW_DEPTH
flag is given to nftw
(see below).
FTW_SLN
The last parameter of the callback function is a pointer to a structure with some extra information as described below.
If the sources are compiled with _FILE_OFFSET_BITS == 64
this
type is in fact __nftw64_func_t
since this mode also changes
struct stat
to be struct stat64
.
For the LFS interface there is also a variant of this data type
available which has to be used with the nftw64
function.
int (*) (const char *, const struct stat64 *, int, struct FTW *)
This type is used just like __nftw_func_t
for the callback
function, but this time called from nftw64
. The second parameter
to the function is this time a pointer to a variable of type
struct stat64
which is able to represent the larger values.
int base
FTW_CHDIR
flag for nftw
was
set since then the current directory is the one the current item is
found in.
int level
ftw
function calls the callback function given in the
parameter func for every item which is found in the directory
specified by filename and all directories below. The function
follows symbolic links if necessary but does not process an item twice.
If filename names no directory this item is the only object
reported by calling the callback function.
The filename given to the callback function is constructed by taking the
filename parameter and appending the names of all passed
directories and then the local file name. So the callback function can
use this parameter to access the file. Before the callback function is
called ftw
calls stat
for this file and passes the
information up to the callback function. If this stat
call was
not successful the failure is indicated by setting the falg argument of
the callback function to FTW_NS
. Otherwise the flag is set
according to the description given in the description of
__ftw_func_t
above.
The callback function is expected to return @math{0} to indicate that no
error occurred and the processing should be continued. If an error
occurred in the callback function or the call to ftw
shall return
immediately the callback function can return a value other than
@math{0}. This is the only correct way to stop the function. The
program must not use setjmp
or similar techniques to continue the
program in another place. This would leave the resources allocated in
the ftw
function allocated.
The descriptors parameter to the ftw
function specifies how
many file descriptors the ftw
function is allowed to consume.
The more descriptors can be used the faster the function can run. For
each level of directories at most one descriptor is used so that for
very deep directory hierarchies the limit on open file descriptors for
the process or the system can be exceeded. Beside this the limit on
file descriptors is counted together for all threads in a multi-threaded
program and therefore it is always good too limit the maximal number of
open descriptors to a reasonable number.
The return value of the ftw
function is @math{0} if all callback
function calls returned @math{0} and all actions performed by the
ftw
succeeded. If some function call failed (other than calling
stat
on an item) the function return @math{-1}. If a callback
function returns a value other than @math{0} this value is returned as
the return value of ftw
.
When the sources are compiled with _FILE_OFFSET_BITS == 64
on a
32 bits system this function is in fact ftw64
. I.e., the LFS
interface transparently replaces the old interface.
ftw
but it can work on filesystems
with large files since the information about the files is reported using
a variable of type struct stat64
which is passed by reference to
the callback function.
When the sources are compiled with _FILE_OFFSET_BITS == 64
on a
32 bits system this function is available under the name ftw
and
transparently replaces the old implementation.
nftw
functions works like the ftw
functions. It calls
the callback function func for all items it finds in the directory
filename and below. At most descriptors file descriptors
are consumed during the nftw
call.
The differences are that for one the callback function is of a different
type. It is of type struct FTW *
and provides the callback
functions the information described above.
The second difference is that nftw
takes an additional fourth
argument which is @math{0} or a combination of any of the following
values, combined using bitwise OR.
FTW_PHYS
FTW_SL
value for the type parameter to the callback function.
Please note that if this flag is used the appearance of FTW_SL
in
a callback function does not mean the referenced file does not exist.
To indicate this the extra value FTW_SLN
exists.
FTW_MOUNT
nftw
.
FTW_CHDIR
FTW_DEPTH
FTW_DP
and not FTW_D
.
The return value is computed in the same way as for ftw
.
nftw
return @math{0} if no failure occurred in nftw
and
all callback function call return values are also @math{0}. For
internal errors such as memory problems @math{-1} is returned and
errno is set accordingly. If the return value of a callback
invocation is nonzero this very same value is returned.
When the sources are compiled with _FILE_OFFSET_BITS == 64
on a
32 bits system this function is in fact nftw64
. I.e., the LFS
interface transparently replaces the old interface.
nftw
but it can work on filesystems
with large files since the information about the files is reported using
a variable of type struct stat64
which is passed by reference to
the callback function.
When the sources are compiled with _FILE_OFFSET_BITS == 64
on a
32 bits system this function is available under the name nftw
and
transparently replaces the old implementation.
Go to the first, previous, next, last section, table of contents.