Walks a file tree.
Standard C Library (libc.a)
The ftw and ftw64 subroutines recursively searches the directory hierarchy that descends from the directory specified by the Path parameter.
For each file in the hierarchy, the ftw and ftw64 subroutines call the function specified by the Function parameter. ftw 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. ftw64 passes it a pointer to a null-terminated character string containing the name of the file, a pointer to a stat64 structure containing information about the file, and an integer.
The integer passed to the Function parameter identifies the file type with one of the following values:
| Item | Description |
|---|---|
| FTW_F | Regular file |
| FTW_D | Directory |
| FTW_DNR | Directory that cannot be read |
| FTW_SL | Symbolic Link |
| FTW_NS | File for which the stat structure could not be executed successfully |
If the integer is FTW-DNR, the files and subdirectories contained in that directory are not processed.
If the integer is FTW-NS, the stat structure contents are meaningless. An example of a file that causes FTW-NS to be passed to the Function parameter is a file in a directory for which you have read permission but not execute (search) permission.
The ftw and ftw64 subroutines finish processing a directory before processing any of its files or subdirectories.
The ftw and ftw64 subroutines continue the search until the directory hierarchy specified by the Path parameter is completed, an invocation of the function specified by the Function parameter returns a nonzero value, or an error is detected within the ftw and ftw64 subroutines, such as an I/O error.
The ftw and ftw64 subroutines traverse symbolic links encountered in the resolution of the Path parameter, including the final component. Symbolic links encountered while walking the directory tree rooted at the Path parameter are not traversed.
The ftw and ftw64 subroutines use one file descriptor for each level in the tree. The Depth parameter specifies the maximum number of file descriptors to be used. In general, the ftw and ftw64 subroutines runs faster if the value of the Depth parameter is at least as large as the number of levels in the tree. However, the value of the Depth parameter must not be greater than the number of file descriptors currently available for use. If the value of the Depth parameter is 0 or a negative number, the effect is the same as if it were 1.
Because the ftw and ftw64 subroutines are recursive, it is possible for it to terminate with a memory fault due to stack overflow when applied to very deep file structures.
The ftw and ftw64 subroutines use the malloc subroutine to allocate dynamic storage during its operation. If the ftw and ftw64 subroutined is terminated prior to its completion, such as by the longjmp subroutine being executed by the function specified by the Function parameter or by an interrupt routine, the ftw and ftw64 subroutines cannot free that storage. The storage 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 parameter return a nonzero value the next time it is called.
| Item | Description |
|---|---|
| Path | Specifies the directory hierarchy to be searched. |
| Function | Specifies the file type. |
| Depth | Specifies the maximum number of file descriptors to be used. Depth cannot be greater than OPEN_MAX which is described in the sys/limits.h header file. |
If the tree is exhausted, the ftw and ftw64 subroutines returns a value of 0. If the subroutine pointed to by fn returns a nonzero value, ftw and ftw64 subroutines stops its tree traversal and returns whatever value was returned by the subroutine pointed to by fn. If the ftw and ftw64 subroutines detects an error, it returns a -1 and sets the errno global variable to indicate the error.
If the ftw or ftw64 subroutines detect an error, a value of -1 is returned and the errno global variable is set to indicate the error.
The ftw and ftw64 subroutine are unsuccessful if:
| Item | Description |
|---|---|
| EACCES | Search permission is denied for any component of the Path parameter or read permission is denied for Path. |
| ENAMETOOLONG | The length of the path exceeds PATH_MAX while _POSIX_NO_TRUNC is in effect. |
| ENOENT | The Path parameter points to the name of a file that does not exist or points to an empty string. |
| ENOTDIR | A component of the Path parameter is not a directory. |
The ftw subroutine is unsuccessful if:
| Item | Description |
|---|---|
| EOVERFLOW | A file in Path is of a size larger than 2 Gigabytes. |