ftw(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | USAGE | SUMMARY OF TRUSTED SOLARIS CHANGES | ATTRIBUTES | SEE ALSO

NAME

ftw, nftw- Walk a file tree

SYNOPSIS

#include <ftw.h>

int ftw(const char * path, int (* fn ) (const char *, const struct stat *, int), int depth);
int nftw(const char * path, int (* fn ) (const char *, const struct stat *, int, struct FTW*), int depth, int flags);

DESCRIPTION

The ftw() function recursively descends the directory hierarchy rooted in path . For each object in the hierarchy, ftw() calls the user-defined function fn , passing it a pointer to a null-terminated character string containing the name of the object, a pointer to a stat structure (see stat(2) ) containing information about the object, and 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 cannot be read. Descendants of the directory will not be processed.

FTW_NS

The stat() function failed on the object because of lack of appropriate permission or the object is a symbolic link that points to a non-existent file. The stat buffer passed to fn is undefined.

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 non-zero value, or some error is detected within ftw() (such as an I/O error). If the tree is exhausted, ftw() returns 0 . If fn returns a non-zero value, ftw() stops its tree traversal and returns whatever value was returned by fn .

nftw(3C) recursively descends the directory hierarchy rooted in path . The flags argument is used to control the tree walk and holds one of these values:

FTW_PHYS

Physical walk, does not follow symbolic links. Otherwise, nftw() will follow links but will not walk down any path that crosses itself.

FTW_MOUNT

The walk will not cross a mount point.

FTW_DEPTH

All subdirectories will be visited before the directory itself.

FTW_CHDIR

The walk will change to each directory before reading it.

FTW_TSOL_MLD

In all multilevel directories ( MLD s) encountered as nftw() walks the tree, the walk will visit single-level directories ( SLD s) that are dominated by the sensitivity label of the process if the process is run without privilege. If the effective privilege set of the process includes the PRIV_FILE_MAC_READ and PRIV_FILE_MAC_SEARCH privileges, the walk visits all SLD s in each MLD . The file system enforces all underlying DAC policies and privilege interpretations.

If the FTW_TSOL_MLD flag is not specified and path points to an adorned MLD , the walk traverses only the SLD s of this MLD . All other MLD s encountered while walking down the tree are automatically translated to the SLD at the sensitivity label of the process even if the process is run with all privileges.

If the FTW_TSOL_MLD flag is not specified and path points to an unadorned MLD , when the walk down the tree encounters this and all other MLD s, then the function automatically translates to the SLD at the sensitivity label of the process.

If the FTW_TSOL_MLD flag is not specified and path does not point to an MLD , when the walk down the tree encounters any MLD s, then the function automatically translates to the SLD at the sensitivity label of the process even if the process is run with all privileges.

The nftw() function calls fn with four arguments at each file and directory. The first argument is the pathname of the object, the second is a pointer to the stat structure [see stat(2) ] containing information about the object, the third is an integer giving additional information, and the fourth is a struct FTW that contains the following members:

      int   base;
      int   level;

The base member is the offset into the pathname of the base name of the object. The level member indicates the depth relative to the rest of the walk, where the root level is zero.

The values of the third argument are as follows:

FTW_F

The object is a file.

FTW_D

The object is a directory.

FTW_DP

The object is a directory and subdirectories have been visited.

FTW_SL

The object is a symbolic link.

FTW_SLN

The object is a symbolic link that points to a non-existent file.

FTW_DNR

The object is a directory that cannot be read. ]The user-defined function fn will not be called for any of its descendants.

FTW_NS

The stat() function failed on the object because of lack of appropriate permission. The stat buffer passed to fn is undefined. The stat() function failed for a reason other than lack of appropriate permission. EACCES is considered an error and nftw() will return -1 .

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

Both ftw() and nftw() use one file descriptor for each level in the tree. The depth argument limits the number of file descriptors so used. If depth is zero or negative, the effect is the same as if it were 1 . It must not be greater than the number of file descriptors currently available for use. The ftw() function will run faster if depth is at least as large as the number of levels in the tree. When ftw() and nftw() return, they close any file descriptors they have opened; they do not close any file descriptors that may have been opened by fn .

RETURN VALUES

ftw() and nftw() return:

0

On success.

-1

If either function detects an error other than EACCES , and sets errno to indicate the error.

USAGE

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

The ftw() function uses malloc(3C) to allocate dynamic storage during its operation. If ftw() is forcibly terminated, such as by longjmp(3C) being executed by fn or an interrupt routine, ftw() will not have a chance to free that storage, so it will remain 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 non-zero value at its next invocation.

The ftw() and nftw() functions have transitional interfaces for 64-bit file offsets. See lf64(5) .

The ftw() function is safe in multithreaded applications. The nftw() function is safe in multithreaded applications when the FTW_CHDIR flag is not set.

There are two versions of nftw() . The Solaris version, which does not traverse multilevel directories ( MLD s), is located in libc ; the Trusted Solaris version, which traverses MLD s, is located in libtsol . To use the Trusted Solaris version of nftw() , make sure that the application uses the version of nftw located in libtsol .

SUMMARY OF TRUSTED SOLARIS CHANGES

The libc versions of ftw() and nftw() are unchanged. The Trusted Solaris version of nftw() , which has the additional flag FTW_TSOL_MLD , is available in libtsol . You must be careful of the library sequence when linking.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	Safe with exceptions.

SEE ALSO

Trusted Solaris 7 Reference Manual

stat(2)

SunOS 5.7 Reference Manual

longjmp(3C) , malloc(3C) , attributes(5) , lf64(5)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | USAGE | SUMMARY OF TRUSTED SOLARIS CHANGES | ATTRIBUTES | SEE ALSO