ftw(), ftw64()

Walk a file tree

Synopsis:

#include <ftw.h>

int ftw( const char *path, 
         int (*fn)( const char *fname,
                    const struct stat *sbuf,
                    int flags),
         int depth );

int ftw64 ( const char *path, 
            int (*fn)( const char *fname,
                      const struct stat64 *sbuf,
                      int flags),
            int depth );

Arguments:

path: The path of the directory whose file tree you want to walk.
fn: A pointer to a function that you want to call for each file; see below.
depth: The maximum number of file descriptors that ftw() can use. The ftw() function uses one file descriptor for each level in the tree.
If depth is zero or negative, the effect is the same as if it were 1. The depth must not be greater than the number of file descriptors currently available for use. The ftw() function is faster if depth is at least as large as the number of levels in the tree.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Note: These functions are in libc.a, but not in libc.so (in order to save space).

Description:

The ftw() and ftw64() functions recursively descend the directory hierarchy identified by path. The ftw64() function is a large-file support version of ftw().

Note: In QNX Neutrino 6.6 or later, the large-file support functions and data types appear in the name space only if you define _LARGEFILE64_SOURCE when you compile your code. For more information, see “Classification” in What's in a Function Description?

For each object in the hierarchy, ftw() calls the user-defined function fn(), passing to it:

a pointer to a NULL-terminated character string containing the name of the object
a pointer to a stat structure (see stat()) containing information about the object
an integer. Possible values of the integer, defined in the <ftw.h> header, are:

FTW_F

The object is a file.

FTW_D

The object is a directory.

FTW_DNR

The object is a directory that can't be read. Descendants of the directory aren't processed.

FTW_NS

The stat() failed on the object because the permissions weren't appropriate, or the object is a symbolic link that points to a nonexistent file. Don't assume that the stat buffer contains valid data.

The ftw() function visits a directory before visiting any of its descendants.

The tree traversal continues until the tree is exhausted, an invocation of fn() returns a nonzero value, or some error is detected within ftw() (such as an I/O error). If the tree is exhausted, ftw() returns zero. If fn() returns a nonzero value, ftw() stops its tree traversal and returns whatever value was returned by fn().

When ftw() returns, it closes any file descriptors it opened; it doesn't close any file descriptors that may have been opened by fn().

Returns:

0: Success.
-1: An error (other than EACCES) occurred (errno is set).

Classification:

ftw() is POSIX 1003.1 OB XSI; ftw64() is Large-file support. The ftw() function is marked as obsolescent, and may be removed from a future version of the standard.

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes

Caveats:

Because ftw() is recursive, it might terminate with a memory fault when applied to very deep file structures.

This function uses malloc() to allocate dynamic storage during its operation. If ftw() is forcibly terminated, for example if longjmp() is executed by fn() or an interrupt routine, ftw() doesn't have a chance to free that storage, so it remains permanently allocated. A safe way to handle interrupts is to store the fact that an interrupt has occurred, and arrange to have fn() return a nonzero value at its next invocation.