Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
Standard C Library Functionsftw(3C)


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 are not 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.

The nftw() function is similar to ftw() except that it takes the additional argument flags, whose possible values are:

FTW_PHYS
Physical walk, does not follow symbolic links. Otherwise, nftw() follows 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 are visited before the directory itself.
FTW_CHDIR
The walk changes to each directory before reading it.

At each file it encounters, nftw() calls the user-supplied function fn with four arguments:

  • The first argument is the pathname of the object.
  • The second argument is a pointer to the stat buffer containing information on the object.
  • The third argument is an integer giving additional information. Its value is one of the following:
    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() returns -1.
  • The fourth argument is a pointer to an FTW structure that contains the following members:
     
    int   base;
    int   level;

    The base member is the offset of the object's filename in the pathname passed as the first argument to fn(). The value of level indicates the depth relative to the root of the walk, where the root level is 0.

Both ftw() and nftw() use one file descriptor for each level in the tree. The depth argument limits the number of file descriptors 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 runs 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 might have been opened by fn.

RETURN VALUES

 

If the tree is exhausted, ftw() and nftw() return 0. If the function pointed to by fn returns a non-zero value, ftw() and nftw() stop their tree traversal and return whatever value was returned by the function pointed to by fn. If ftw() and nftw() detect an error, they return -1 and set errno to indicate the error.

If ftw() and nftw() encounter an error other than EACCES (see FTW_DNR and FTW_NS above), they return -1 and set errno to indicate the error. The external variable errno can contain any error value that is possible when a directory is opened or when one of the stat functions is executed on a directory or file.

ERRORS

 

The ftw() and nftw() functions will fail if:

ENAMETOOLONG
The length of the path exceeds PATH_MAX, or a path name component is longer than NAME_MAX.
ENOENT
A component of path does not name an existing file or path is an empty string.
ENOTDIR
A component of path is not a directory.

The ftw() function will fail if:

EACCES
Search permission is denied for any component of path or read permission is denied for path.
ELOOP
Too many symbolic links were encountered.

The nftw() function will fail if:

EACCES
Search permission is denied for any component of path or read permission is denied for path, or fn() returns -1 and does not reset errno.

The ftw() and nftw() functions may fail if:

ENAMETOOLONG
Pathname resolution of a symbolic link produced an intermediate result whose length exceeds PATH_MAX.

The ftw() function may fail if:

EINVAL
The value of the ndirs argument is invalid.

The nftw() function may fail if:

ELOOP
Too many symbolic links were encountered in resolving path.
EMFILE
There are OPEN_MAX file descriptors currently open in the calling process.
ENFILE
Too many files are currently open in the system.

In addition, if the function pointed to by fn encounters system errors, errno may be set accordingly.

USAGE

 

Because ftw() is recursive, it can 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 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 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.

ATTRIBUTES

 

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

ATTRIBUTE TYPEATTRIBUTE VALUE
Interface Stabilitynftw is Standard
MT-LevelSafe with exceptions

SEE ALSO

 

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


SunOS 5.9Go To TopLast Changed 29 Jan 2002

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.