Go to the first, previous, next, last section, table of contents.


Working on Directory Trees

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.

Data Type: __ftw_func_t

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
The current item is a normal file or files which do not fit into one of the following categories. This means especially special files, sockets etc.
FTW_D
The current item is a directory.
FTW_NS
The stat call to fill the object pointed to by the second parameter failed and so the information is invalid.
FTW_DNR
The item is a directory which cannot be read.
FTW_SL
The item is a symbolic link. Since symbolic links are normally followed seeing this value in a 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.

Data Type: __ftw64_func_t

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.

Data Type: __nftw_func_t

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
The current item is a directory and all subdirectories have already been visited and reported. This flag is returned instead of FTW_D if the FTW_DEPTH flag is given to nftw (see below).
FTW_SLN
The current item is a stale symbolic link. The file it points to does not exist.

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.

Data Type: __nftw64_func_t

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.

Data Type: struct FTW
The contained information helps to interpret the name parameter and gives some information about current state of the traversal of the directory hierarchy.

int base
The value specifies which part of the filename argument given in the first parameter to the callback function is the name of the file. The rest of the string is the path to locate the file. This information is especially important if the FTW_CHDIR flag for nftw was set since then the current directory is the one the current item is found in.
int level
While processing the directory the functions tracks how many directories have been examine to find the current item. This nesting level is @math{0} for the item given starting item (file or directory) and is incremented by one for each entered directory.

Function: int ftw (const char *filename, __ftw_func_t func, int descriptors)
The 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.

Function: int ftw64 (const char *filename, __ftw64_func_t func, int descriptors)
This function is similar to 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.

Function: int nftw (const char *filename, __nftw_func_t func, int descriptors, int flag)
The 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
While traversing the directory symbolic links are not followed. I.e., if this flag is given symbolic links are reported using the 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
The callback function is only called for items which are on the same mounted filesystem as the directory given as the filename parameter to nftw.
FTW_CHDIR
If this flag is given the current working directory is changed to the directory containing the reported object before the callback function is called.
FTW_DEPTH
If this option is given the function visits first all files and subdirectories before the callback function is called for the directory itself (depth-first processing). This also means the type flag given to the callback function is 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.

Function: int nftw64 (const char *filename, __nftw64_func_t func, int descriptors, int flag)
This function is similar to 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.