The functions described so far for handling the files in a directory
have allowed you to either retrieve the information bit by bit, or to
process all the files as a group (see scandir
). Sometimes it is
useful to process whole hierarchies of directories and their contained
files. The X/Open specification defines 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.
There are four functions in this family: ftw
, nftw
and
their 64-bit counterparts ftw64
and nftw64
. These
functions take as one of their arguments a pointer to a callback
function of the appropriate type.
int (*) (const char *, const struct stat *, int)
The type of callback functions given to the ftw
function. The
first parameter points to the file name, the second parameter to an
object of type struct stat
which is filled in for the file named
in the first parameter.
The last parameter is a flag giving more information about the current file. It can have the following values:
FTW_F
FTW_D
FTW_NS
stat
call failed and so the information pointed to by the
second paramater 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 changes
struct stat
to be struct stat64
.
For the LFS interface and for 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 is called from ftw64
. The second
parameter to the function is 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 are the same as for the __ftw_func_t
type. However for the third argument some additional values are defined
to allow finer differentiation:
FTW_DP
FTW_D
if
the FTW_DEPTH
flag is passed 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 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 is 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 was set in calling nftw
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 is not a directory then it itself is the only object
returned to the callback function.
The file name passed 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. ftw
also calls
stat
for the file and passes that information on to the callback
function. If this stat
call was not successful the failure is
indicated by setting the third argument of the callback function to
FTW_NS
. Otherwise it is set according to the description given
in the account of __ftw_func_t
above.
The callback function is expected to return @math{0} to indicate that no
error occurred and that processing should continue. If an error
occurred in the callback function or it wants ftw
to 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
from another place. This would leave resources allocated by the
ftw
function unfreed.
The descriptors parameter to ftw
specifies how many file
descriptors it is allowed to consume. The function runs faster the more
descriptors it can use. For each level in the directory hierarchy at
most one descriptor is used, but for very deep ones any limit on open
file descriptors for the process or the system may be exceeded.
Moreover, file descriptor limits in a multi-threaded program apply to
all the threads as a group, and therefore it is a good idea to supply a
reasonable limit to the number of open descriptors.
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 a function call failed (other than calling
stat
on an item) the function returns @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-bit 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. File information 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-bit system this function is available under the name ftw
and
transparently replaces the old implementation.
nftw
function works like the ftw
functions. They call
the callback function func for all items found in the directory
filename and below. At most descriptors file descriptors
are consumed during the nftw
call.
One difference is that the callback function is of a different type. It
is of type struct FTW *
and provides the callback function
with the extra information described above.
A second difference is that nftw
takes a fourth argument, which
is @math{0} or a bitwise-OR combination of any of the following values.
FTW_PHYS
FTW_SL
value for the type
parameter to the callback function. If the file referenced by a
symbolic link does not exist FTW_SLN
is returned instead.
FTW_MOUNT
nftw
.
FTW_CHDIR
ntfw
finally returns the current directory is restored to
its original value.
FTW_DEPTH
FTW_DP
and not FTW_D
.
The return value is computed in the same way as for ftw
.
nftw
returns @math{0} if no failures occurred and all callback
functions returned @math{0}. In case of internal errors, such as memory
problems, the return value is @math{-1} and errno is set
accordingly. If the return value of a callback invocation was non-zero
then that value is returned.
When the sources are compiled with _FILE_OFFSET_BITS == 64
on a
32-bit 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. File information 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-bit 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.