.\" SCCSID: @(#)ftw.3	8.2	3/28/91.TH ftw 3.SH Nameftw \- walk a file tree.SH Syntax.B #include <ftw.h>.PP.B int ftw (\fIpath, fn, depth\fP).br.B char *\fIpath\fP;.br.B int (*\fIfn) ( )\fP;.br.B int \fIdepth\fP;.SH Description.NXR "ftw subroutine".NXR "directory" "descending tree"The.PN ftwsubroutine recursively descends the directory hierarchyrooted in.IR path .For each object in the hierarchy,.PN ftwcalls.IR fn ,passing it a pointer to a null-terminatedcharacter string containing the name of the object,a pointer to a.B statstructurecontaining information about the object, and an integer.For further information, see .MS stat 2 .Possible values of the integer, defined in the <ftw.h> header file,are FTW_F for a file, FTW_D for a directory, FTW_DNR fora directory that cannot be read, and FTW_NS for an objectfor which.B statcould not successfully be executed.If the integer is FTW_DNR,descendants of that directory will not be processed.If the integer is FTW_NS, the the contents of the.B statstructure will be undefined. An example of an object that would causeFTW_NS to be passed to.I fn\^would be a file in a directorywith read but without execute (search) permission..PPThe.PN ftwsubroutine visits a directory before visiting any of its descendants..PPThe tree traversal continues until the tree is exhausted,an invocation of.I fn\^returns a nonzero value,or some error is detected within.PN ftw(such as an I/O error).If the tree is exhausted,.PN ftwreturns zero.If.I fn\^returns a nonzero value,.PN ftwstops its tree traversal and returns whatevervalue was returned by.IR fn .If.PN ftwdetects an error, it returns\-1, and sets the error type in.IR errno ..PPThe.PN ftwsubroutineuses one file descriptor for each level in the tree.The.I depth\^argument limits the number of file descriptors so used.If.I depth\^is zero or negative, the effect is the same as if it were 1.The.I depth\^must not be greater than the number of file descriptors currentlyavailable for use.The.PN ftwsubroutine will run more quickly if.I depth\^is at least as large as the number of levels in the tree..SH RestrictionsBecause.PN ftwis recursive, it is possible for it to terminate with a memoryfault when applied to very deep file structures..brIt could be made to run faster and use less storage on deepstructures at the cost of considerable complexity..brThe.PN ftwsubroutine uses .MS malloc 3to allocate dynamic storage during its operation.If.PN ftwis forcibly terminated, such as by.I longjmp\^being executed by.I fn\^or an interrupt routine,.PN ftwwill not have a chance to free that storage,so it will remain permanently allocated.A safe way to handle interrupts is to storethe fact that an interrupt has occurred,and arrange to have.I fn\^return a nonzero value at its next invocation..SH Diagnostics.TP 15[EACCES] Search permission is denied on a component of \fIpath\fP or readpermission is denied for path..TP[ENAMETOOLONG]The length of the path string exceeds {PATH_MAX}, ora pathname component is longer than {NAME_MAX}..TP[ENOENT]The path argument points to the name of a file whichdoes not exist, or to an empty string and the environmentdefined is POSIX or SYSTEM_FIVE..TP[ENOTDIR]A component of \fIpath\fP is not a directory..TP[ENOMEM]Not enough memory was available to complete the file treewalk..SH See Alsostat(2), malloc(3)