da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.TH FTWALK 3
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fBftwalk\fR \- file tree walker
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH SYNOPSIS
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint ftwalk(char* path, int (*userf)(struct FTW* ftw), int options,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin int (*comparf)(struct FTW* ftw1, struct FTW* ftw2));
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint ftwflags(void);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH DESCRIPTION
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIFtwalk\fR traverses a directory hierarchy using depth-first search.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinUpon visiting each file or directory in the hierarchy, it calls
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe user function \fIuserf\fP to process that file or directory.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinOn a directory object, \fIuserf\fR may be called twice, once in preorder
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinand once in postorder.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinOn a terminal object such as a file or an unreadable directory,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIuserf\fP is called only once.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinCycles due to hard links or symbolic links are detected
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto avoid infinite loops.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIPath\fR is the starting point of the search.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt may be an absolute path name or a path name relative to
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe current directory.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fIpath\fR is a null pointer or points to an empty string, it is treated
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinas if it points to the current (dot) directory.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIOptions\fR consists of zero or more of the following bits:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_CHILDREN:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis implies preorder calls to \fIuserf\fR on directory objects.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinOn such a call to \fIuserf\fR,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe field \fIftw->link\fR (below) points to a link list of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe children of the respective directory.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinUpon returning from \fIuserf\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinif the field \fIftw->status\fR of any child object
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis set to FTW_SKIP (below), that child is pruned from the search.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_DELAY: When \fBFTW_CHILDREN\fP is turned on,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe fields \fIftw->statb\fP (\fIstruct stat\fP) of children objects
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinremain undefined until these objects are visited.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_DOT: Do not use \fIchdir\fR(2) during the traversal.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinNormally \fIchdir\fR is used so that
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe base name of the object about to be processed can be used
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinin accessing its data.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis can enhance \fIftwalk\fR efficiency but certain program effects
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinsuch as core dumps may be generated in unexpected places
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinor may not even be generated at all.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinWhenever \fIchdir\fR generates an error, if possible,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe current directory is restored to the starting directory
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin(see FTW_NAME and FTW_PATH).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_MULTIPLE: The \fIpath\fP argument is treated as a \fIchar**\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinpointer to a null-terminated array of path names.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAll hierarchies rooted at these paths will be searched
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_POST: Calls to the user function are issued only in postorder.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThat is, \fIuserf\fP is called on a directory only after its descendants have
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbeen processed.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe absence of this bit indicates that calls to the user functions
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinare issued in preorder. That is, \fIuserf\fP is
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincalled on a directory before its descendants are processed.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_PHYSICAL: Use \fIlstat\fR(2) instead of \fIstat\fR(2) to get
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfile status and allow detection of symbolic links.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIn addition, if each component
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinof the absolute path to the starting object has search permission,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe absolute path is used for early detection of cycles.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_META|FTW_PHYSICAL: Use \fIstat\fR(2) for top level file status and
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIlstat\fR(2) for all other files.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinUsed to implement the POSIX
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinoption for commands like
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_TWICE: Calls to the user function are issued in both preorder and postorder
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfor directory objects.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_USER: The first of 6 user defined option bits.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThese bits are ignored by \fIftwalk\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIUserf\fR is a user supplied function that is
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincalled upon different visits of an object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf the return value of \fIuserf\fR is non-zero,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIftwalk\fR returns immediately with the same value.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIuserf\fP prototype is:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin int userf(struct FTW* ftw)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fBstruct FTW\fP contains at least the following elements:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin struct FTW* link; /* link list of children */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin struct FTW* parent; /* parent object on the search path */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin long number; /* local number */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin void* pointer; /* local pointer */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin } local; /* user defined */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin struct stat statb; /* stat buffer of this object */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin char* path; /* full pathname */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin short pathlen; /* strlen(path) */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin unsigned short info; /* type of object */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin unsigned short status; /* status of object */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin short level; /* depth of object on the search path */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin short namelen; /* strlen(name) */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin char name[]; /* file name of object */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIlink\fR field is normally NULL.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf the option FTW_CHILDREN was turned on,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinit points to the start of the list of children
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinof the directory being visited in preorder.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFinally, if the directory being visited causes a cycle,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIlink\fR points to the object on the search path that is
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinidentical to this directory. Note that if FTW_PHYSICAL was turned on,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthis may point to a directory that is an ancestor of the starting
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIparent\fR field points to the parent object
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinon the search path. For convenience, a parent object is also supplied for
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe starting object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIn this case, except for the \fIlocal\fR field which is initialized
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto 0 and the \fIlevel\fR field which contains a negative number,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe rest of the structure may be undefined.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIinfo\fR field indicates the type of the object
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbeing visited and the type of the visit. The types are:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_D: A directory being visited in preorder, i.e.,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinnone of its children has been visited by the search.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_DNX: A directory being visited in preorder that does not have
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinsearch permission.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_DP: A directory being visited in postorder, i.e., all of its
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chindescendants have been completely processed.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_DC: A directory that causes cycles. This is a terminal object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_DNR: A directory that cannot be opened for reading. This is a terminal object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_F: An ordinary file.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_SL: A symbolic link.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinUnless FTW_FOLLOW (below) is issued by the user function,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthis object is terminal.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_NS: \fIStat\fR failed on this object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe stat buffer \fIstatb\fR is undefined.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis object is terminal.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIstatus\fR field of \fIstruct FTW\fR is used to communicate information
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbetween \fIftwalk\fR and \fIuserf\fR. On calls to \fIuserf\fR, it has one of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chintwo values:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_NAME: The name of the object as defined in \fIftw->name\fR should be used for
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinaccessing its file information. This is because \fIchdir\fR(2) has been used
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto set the current directory to a suitable place (see FTW_CHDIR).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_PATH: The argument \fIpath\fR of \fIuserf\fR should be used
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfor accessing the file information of the object.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinUpon returning, \fIuserf\fR may set the \fIstatus\fR field
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto one of the following values:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_AGAIN: If this is a directory object being visited in postorder,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinit will be processed \fIagain\fR as if it had not been visited.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_NOPOST: If this is a directory object being visited in preorder,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe user function will not be called on its postorder visit.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_SKIP: This object and its descendants are pruned from the search.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFTW_FOLLOW: If this object is a symbolic link,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfollow the link to its physical counterpart.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIComparf\fR, if not NULL, is a pointer to a function
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinused to define a search ordering for children of a directory.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf FTW_CHILDREN is turned on, the ordering of the children of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china directory is done before the preorder call to \fIuserf\fR on that directory.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinTherefore, in that case, \fIftw->link\fR will point to the smallest child.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIcomparf\fP prototype is:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin int comparf(struct FTW* ftw1, struct FTW* ftw2)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIComparf\fR should return a value <0, 0, or >0 to indicate whether
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIftw1\fR is considered smaller, equal, or larger than \fIftw2\fR.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIFtwalk\fR normally returns 0.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinOn hard errors such as running out of memory, it returns -1.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIFtwalk\fR may also return other values as discussed with respect
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto \fIuserf\fR.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIFtwflags\fR returns a combination of \fB0, FTW_META, FTW_PHYSICAL\fR
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinaccording to the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinpreferences specified by
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fBastconf("PATH_RESOLVE",0,0)\fR:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.B metaphysical
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.B "FTW_META|FTW_PHYSICAL"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.B physical
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.B FTW_PHYSICAL
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH HISTORY
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIFtwalk\fR performs similar functions as that of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe routine \fIftw\fR provided in System V.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinHowever, it is more general than \fIftw\fR
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinand suitable for use as a base in implementing
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinpopular tools such as \fIls, find, tar, du,\fR and \fIrm\fR.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIFtwalk\fR also handles symbolic links and hard links gracefully.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH AUTHORS
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinPhong Vo, Glenn Fowler, Dave Korn
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH SEE ALSO
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfind(1), rm(1), du(1), ls(1), tar(1), stat(2), symlink(2),
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinastfeature(3), ftw(3), pathcd(3)