| Skip Navigation Links | |
| Exit Print View | |
 | man pages section 3: Basic Library Functions Oracle Solaris 11 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
| man pages section 3: Basic Library Functions Oracle Solaris 11 Information Library |
enable_extended_FILE_stdio(3C)
posix_spawnattr_getschedparam(3C)
posix_spawnattr_getschedpolicy(3C)
posix_spawnattr_getsigdefault(3C)
posix_spawnattr_getsigignore_np(3C)
posix_spawnattr_getsigmask(3C)
posix_spawnattr_setschedparam(3C)
posix_spawnattr_setschedpolicy(3C)
posix_spawnattr_setsigdefault(3C)
posix_spawnattr_setsigignore_np(3C)
posix_spawnattr_setsigmask(3C)
posix_spawn_file_actions_addclose(3C)
posix_spawn_file_actions_addclosefrom_np(3C)
posix_spawn_file_actions_adddup2(3C)
posix_spawn_file_actions_addopen(3C)
posix_spawn_file_actions_destroy(3C)
posix_spawn_file_actions_init(3C)
pthread_attr_getdetachstate(3C)
pthread_attr_getinheritsched(3C)
pthread_attr_getschedparam(3C)
pthread_attr_getschedpolicy(3C)
pthread_attr_setdetachstate(3C)
pthread_attr_setinheritsched(3C)
pthread_attr_setschedparam(3C)
pthread_attr_setschedpolicy(3C)
pthread_barrierattr_destroy(3C)
pthread_barrierattr_getpshared(3C)
pthread_barrierattr_setpshared(3C)
pthread_condattr_getpshared(3C)
pthread_condattr_setpshared(3C)
pthread_cond_reltimedwait_np(3C)
pthread_key_create_once_np(3C)
pthread_mutexattr_getprioceiling(3C)
pthread_mutexattr_getprotocol(3C)
pthread_mutexattr_getpshared(3C)
pthread_mutexattr_getrobust(3C)
pthread_mutexattr_setprioceiling(3C)
pthread_mutexattr_setprotocol(3C)
pthread_mutexattr_setpshared(3C)
pthread_mutexattr_setrobust(3C)
pthread_mutex_getprioceiling(3C)
pthread_mutex_reltimedlock_np(3C)
pthread_mutex_setprioceiling(3C)
pthread_rwlockattr_destroy(3C)
pthread_rwlockattr_getpshared(3C)
pthread_rwlockattr_setpshared(3C)
pthread_rwlock_reltimedrdlock_np(3C)
pthread_rwlock_reltimedwrlock_np(3C)
pthread_rwlock_timedrdlock(3C)
pthread_rwlock_timedwrlock(3C)
rctlblk_get_enforced_value(3C)
- walk a file tree
#include <ftw.h>intftw(const char *path,int (*fn) (const char *,const struct stat *,int),intdepth);
intnftw(const char *path,int (*fn) (const char *,const struct stat *,int,struct FTW *),intdepth,intflags);
Theftw() function recursively descends the directory hierarchy rooted inpath. Foreach object in the hierarchy,ftw() calls the user-defined functionfn, passingit a pointer to a null-terminated character string containing the name of theobject, a pointer to astat structure (seestat(2)) containing information aboutthe object, and an integer. Possible values of the integer, defined in the<ftw.h> header, are:
The object is a file.
The object is a directory.
The object is a directory that cannot be read. Descendants of the directory are not processed.
Thestat() 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. Thestat buffer passed tofn is undefined.
Theftw() function visits a directory before visiting any of its descendants.
The tree traversal continues until the tree is exhausted, an invocation offn returns a non-zero value, or some error is detected withinftw()(such as an I/O error). If the tree is exhausted,ftw() returns0. Iffn returns a non-zero value,ftw() stops its tree traversal andreturns whatever value was returned byfn.
Thenftw() function is similar toftw() except that it takesthe additional argumentflags, which is a bitwise-inclusive OR of zero ormore of the following flags:
If set,nftw() changes the current working directory to each directory as it reports files in that directory. If clear,nftw() does not change the current working directory.
If set,nftw() reports all files in a directory before reporting the directory itself. If clear,nftw() reports any directory before reporting the files in that directory.
If set,nftw() reports only files in the same file system as path. If clear,nftw() reports all files encountered during the walk.
If set,nftw() performs a physical walk and does not follow symbolic links.
IfFTW_PHYS is clear andFTW_DEPTH is set,nftw() follows links insteadof reporting them, but does not report any directory that would bea descendant of itself. IfFTW_PHYS is clear andFTW_DEPTH is clear,nftw()follows links instead of reporting them, but does not report the contentsof any directory that would be a descendant of itself.
At each file it encounters,nftw() calls the user-supplied functionfn withfour arguments:
The first argument is the pathname of the object.
The second argument is a pointer to thestat buffer containing information on the object.
The third argument is an integer giving additional information. Its value is one of the following:
The object is a file.
The object is a directory.
The object is a directory and subdirectories have been visited. (This condition only occurs if the FTW_DEPTH flag is included in flags.)
The object is a symbolic link. (This condition only occurs if the FTW_PHYS flag is included in flags.)
The object is a symbolic link that points to a non-existent file. (This condition only occurs if the FTW_PHYS flag is not included in flags.)
The object is a directory that cannot be read. The user-defined functionfn will not be called for any of its descendants.
Thestat() function failed on the object because of lack of appropriate permission. The stat buffer passed tofn is undefined. Failure ofstat() for any other reason is considered an error andnftw() returns -1.
The fourth argument is a pointer to anFTW structure that contains the following members:
int base;int level;
Thebase member is the offset of the object's filename in the pathname passed as the first argument tofn(). The value oflevel indicates the depth relative to the root of the walk, where the root level is 0.
The results are unspecified if the application-suppliedfn() function does not preserve the current working directory.
Bothftw() andnftw() use one file descriptor for each level inthe tree. Thedepth argument limits the number of file descriptors used.Ifdepth is zero or negative, the effect is the same asif it were 1. It must not be greater than the number offile descriptors currently available for use. Theftw() function runs fasterifdepth is at least as large as the number of levelsin the tree. Bothftw() andnftw() are able to descend to arbitrarydepths in a file hierarchy and do not fail due to pathlength limitations unless either the length of the path name pointed toby thepath argument exceeds {PATH_MAX} requirements, or forftw(), the specified depthis less than 2, or fornftw(), the specified depth is lessthan 2 andFTW_CHDIR is not set. Whenftw() andnftw() return,they close any file descriptors they have opened; they do not closeany file descriptors that might have been opened byfn.
If the tree is exhausted,ftw() andnftw() return0. If thefunction pointed to byfn returns a non-zero value,ftw() andnftw()stop their tree traversal and return whatever value was returned by the functionpointed to byfn. Ifftw() andnftw() detect an error, they return-1 and seterrno to indicate the error.
Ifftw() andnftw() encounter an error other thanEACCES (seeFTW_DNR andFTW_NS above), they return-1 and seterrno toindicate the error. The external variableerrno can contain any error value thatis possible when a directory is opened or when one of thestat functions is executed on a directory or file.
Theftw() andnftw() functions will fail if:
A loop exists in symbolic links encountered during resolution of thepath argument
The length of the path name pointed to by thepath argument exceeds {PATH_MAX}, or a path name component is longer than {NAME_MAX}.
A component ofpath does not name an existing file orpath is an empty string.
A component ofpath is not a directory.
A field in thestat structure cannot be represented correctly in the current programming environment for one or more files found in the file hierarchy.
Theftw() function will fail if:
Search permission is denied for any component ofpath or read permission is denied forpath.
Theftw() function has descended to a path that exceeds {PATH_MAX} and the depth argument specified by the application is less than 2 andFTW_CHDIR is not set.
Thenftw() function will fail if:
Search permission is denied for any component ofpath or read permission is denied forpath, orfn() returns -1 and does not reseterrno.
Thenftw() andftw() functions may fail if:
Too many symbolic links were encountered during resolution of thepath argument.
Pathname resolution of a symbolic link in the path name pointed to by thepath argument produced an intermediate result whose length exceeds {PATH_MAX}.
Theftw() function may fail if:
The value of thedepth argument is invalid.
Thenftw() function may fail if:
There are {OPEN_MAX} file descriptors currently open in the calling process.
Too many files are currently open in the system.
If the function pointed to byfn encounters system errors,errno maybe set accordingly.
Example 1 Walk a directory structure usingftw().
The following example walks the current directory structure, calling thefn() functionfor every directory entry, using at most 10 file descriptors:
#include <ftw.h>...if (ftw(".", fn, 10) != 0) { perror("ftw"); exit(2);}Example 2 Walk a directory structure usingnftw().
The following example walks the/tmp directory and its subdirectories, calling thenftw() function for every directory entry, to a maximum of 5 levelsdeep.
#include <ftw.h> ...int nftwfunc(const char *, const struct stat *, int, struct FTW *);int nftwfunc(const char *filename, const struct stat *statptr, int fileflags, struct FTW *pfwt){ return 0;}...char *startpath = "/tmp";int depth = 5;int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;int ret;ret = nftw(startpath, nftwfunc, depth, flags);Becauseftw() andnftw() are recursive, they can terminate with a memoryfault when applied by a thread with a small stack to verydeep file structures.
Theftw() andnftw() functions allocate resources (memory, file descriptors) during theiroperation. Ifftw() they are forcibly terminated, such as bylongjmp(3C) beingexecuted byfn or an interrupt routine, they will not have achance to free those resources, so they remain permanently allocated. A safeway to handle interrupts is to store the fact that an interrupthas occurred and arrange to havefn return a non-zero value at itsnext invocation.
Theftw() andnftw() functions have transitional interfaces for 64-bit file offsets. Seelf64(5).
Theftw() function is safe in multithreaded applications. Thenftw() function issafe in multithreaded applications when theFTW_CHDIR flag is not set.
Seeattributes(5) for descriptions of the following attributes:
|
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.Legal Notices |   |