ftw

Walks a file tree.

Format 

#include  <ftw.h>

int ftw  (const char *path, int(*function)(const
         char *, const struct stat *,int), int depth);

Arguments

path
The directory hierarchy to be searched.
function
The function to be invoked for each file in the directory hierarchy.
depth
The maximum number of directory streams or file descriptors, or both, available for use by ftw. This argument should be in the range of 1 to OPEN_MAX.

Description

This function recursively searches the directory hierarchy that descends from the directory specified by the path argument.

For each file in the hierarchy, ftw calls the function specified by the function argument, passes it a pointer to a null- terminated character string containing the name of the file, a pointer to a stat structure containing information about the file, and an integer.

The integer identifies the file type. Possible values, defined in <ftw.h> are:
FTW_F  Regular file. 
FTW_D  Directory. 
FTW_ DNR  Directory that cannot be read. 
FTW_NS  A file on which stat could not successfully be executed. 

If the integer is FTW_DNR, then the files and subdirectories contained in that directory are not processed.

If the integer is FTW_NS, then the stat structure contents are meaningless. For example, a file in a directory for which you have read permission but not execute (search) permission can cause the function argument to pass FTW_NS.

The ftw function finishes processing a directory before processing any of its files or subdirectories.

The ftw function continues the search until:

Because the ftw function is recursive, it is possible for it to terminate with a memory fault because of stack overflow when applied to very deep file structures.

The ftw function uses the malloc function to allocate dynamic storage during its operation. If ftw is forcibly terminated, as with a call to longjmp from the function pointed to by the function argument, ftw has no chance to free that storage. It remains allocated.

A safe way to handle interrupts is to store the fact that an interrupt has occurred, and arrange to have the function specified by the function argument return a nonzero value the next time it is called.

Note
The ftw function is reentrant; make sure that the function supplied as argument function is also reentrant.

See malloc, longjump, lstat, and stat in this section.

Return Values
0  Indicates success. 
x  Indicates that the function specified by the function argument stops its search, and returns the value that was returned by the function. 
- 1  Indicates an error; errno is set to one of the following values:

  • EACCES - Search permission is denied for any component of the path argument or read permission is denied for the path argument.

  • ENAMETOOLONG - The length of the path string exceeds PATH_ MAX, or a pathname component is longer than NAME_MAX while [_ POSIX_NO_TRUNC] is in effect.

  • ENOENT - The path argument points to the name of a file that does not exist or points to an empty string.

  • ENOMEM - There is insufficient memory for this operation.

Also, if the function pointed to by the function argument encounters an error, errno can be set accordingly.  

Previous Page | Next Page | Table of Contents | Index