.fp 5 CW .TH FTWALK 3 .SH NAME \fBftwalk\fR \- file tree walker .SH SYNOPSIS .ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i .PP .nf \f5 #include <ftwalk.h> int ftwalk(char* path, int (*userf)(struct FTW* ftw), int options, int (*comparf)(struct FTW* ftw1, struct FTW* ftw2)); int ftwflags(void); \fR .fi .SH DESCRIPTION .PP \fIFtwalk\fR traverses a directory hierarchy using depth-first search. Upon visiting each file or directory in the hierarchy, it calls the user function \fIuserf\fP to process that file or directory. On a directory object, \fIuserf\fR may be called twice, once in preorder and once in postorder. On a terminal object such as a file or an unreadable directory, \fIuserf\fP is called only once. Cycles due to hard links or symbolic links are detected to avoid infinite loops. .PP \fIPath\fR is the starting point of the search. It may be an absolute path name or a path name relative to the current directory. If \fIpath\fR is a null pointer or points to an empty string, it is treated as if it points to the current (dot) directory. .PP \fIOptions\fR consists of zero or more of the following bits: .IP FTW_CHILDREN: This implies preorder calls to \fIuserf\fR on directory objects. On such a call to \fIuserf\fR, the field \fIftw->link\fR (below) points to a link list of the children of the respective directory. Upon returning from \fIuserf\fP, if the field \fIftw->status\fR of any child object is set to FTW_SKIP (below), that child is pruned from the search. .IP FTW_DELAY: When \fBFTW_CHILDREN\fP is turned on, the fields \fIftw->statb\fP (\fIstruct stat\fP) of children objects remain undefined until these objects are visited. .IP FTW_DOT: Do not use \fIchdir\fR(2) during the traversal. Normally \fIchdir\fR is used so that the base name of the object about to be processed can be used in accessing its data. This can enhance \fIftwalk\fR efficiency but certain program effects such as core dumps may be generated in unexpected places or may not even be generated at all. Whenever \fIchdir\fR generates an error, if possible, the current directory is restored to the starting directory (see FTW_NAME and FTW_PATH). .IP FTW_MULTIPLE: The \fIpath\fP argument is treated as a \fIchar**\fP pointer to a null-terminated array of path names. All hierarchies rooted at these paths will be searched .IP FTW_POST: Calls to the user function are issued only in postorder. That is, \fIuserf\fP is called on a directory only after its descendants have been processed. The absence of this bit indicates that calls to the user functions are issued in preorder. That is, \fIuserf\fP is called on a directory before its descendants are processed. .IP FTW_PHYSICAL: Use \fIlstat\fR(2) instead of \fIstat\fR(2) to get file status and allow detection of symbolic links. In addition, if each component of the absolute path to the starting object has search permission, the absolute path is used for early detection of cycles. .IP FTW_META|FTW_PHYSICAL: Use \fIstat\fR(2) for top level file status and \fIlstat\fR(2) for all other files. Used to implement the POSIX .B \-H option for commands like .IR ls . .IP FTW_TWICE: Calls to the user function are issued in both preorder and postorder for directory objects. .IP FTW_USER: The first of 6 user defined option bits. These bits are ignored by \fIftwalk\fP. .PP \fIUserf\fR is a user supplied function that is called upon different visits of an object. If the return value of \fIuserf\fR is non-zero, \fIftwalk\fR returns immediately with the same value. The \fIuserf\fP prototype is: .PP .nf int userf(struct FTW* ftw) .fi .PP \fBstruct FTW\fP contains at least the following elements: .PP .nf struct FTW* link; /* link list of children */ struct FTW* parent; /* parent object on the search path */ union { long number; /* local number */ void* pointer; /* local pointer */ } local; /* user defined */ struct stat statb; /* stat buffer of this object */ char* path; /* full pathname */ short pathlen; /* strlen(path) */ unsigned short info; /* type of object */ unsigned short status; /* status of object */ short level; /* depth of object on the search path */ short namelen; /* strlen(name) */ char name[]; /* file name of object */ .fi .PP The \fIlink\fR field is normally NULL. If the option FTW_CHILDREN was turned on, it points to the start of the list of children of the directory being visited in preorder. Finally, if the directory being visited causes a cycle, \fIlink\fR points to the object on the search path that is identical to this directory. Note that if FTW_PHYSICAL was turned on, this may point to a directory that is an ancestor of the starting object. .PP The \fIparent\fR field points to the parent object on the search path. For convenience, a parent object is also supplied for the starting object. In this case, except for the \fIlocal\fR field which is initialized to 0 and the \fIlevel\fR field which contains a negative number, the rest of the structure may be undefined. .PP The \fIinfo\fR field indicates the type of the object being visited and the type of the visit. The types are: .IP FTW_D: A directory being visited in preorder, i.e., none of its children has been visited by the search. .IP FTW_DNX: A directory being visited in preorder that does not have search permission. .IP FTW_DP: A directory being visited in postorder, i.e., all of its descendants have been completely processed. .IP FTW_DC: A directory that causes cycles. This is a terminal object. .IP FTW_DNR: A directory that cannot be opened for reading. This is a terminal object. .IP FTW_F: An ordinary file. .IP FTW_SL: A symbolic link. Unless FTW_FOLLOW (below) is issued by the user function, this object is terminal. .IP FTW_NS: \fIStat\fR failed on this object. The stat buffer \fIstatb\fR is undefined. This object is terminal. .PP The \fIstatus\fR field of \fIstruct FTW\fR is used to communicate information between \fIftwalk\fR and \fIuserf\fR. On calls to \fIuserf\fR, it has one of two values: .IP FTW_NAME: The name of the object as defined in \fIftw->name\fR should be used for accessing its file information. This is because \fIchdir\fR(2) has been used to set the current directory to a suitable place (see FTW_CHDIR). .IP FTW_PATH: The argument \fIpath\fR of \fIuserf\fR should be used for accessing the file information of the object. .PP Upon returning, \fIuserf\fR may set the \fIstatus\fR field to one of the following values: .IP FTW_AGAIN: If this is a directory object being visited in postorder, it will be processed \fIagain\fR as if it had not been visited. .IP FTW_NOPOST: If this is a directory object being visited in preorder, the user function will not be called on its postorder visit. .IP FTW_SKIP: This object and its descendants are pruned from the search. .IP FTW_FOLLOW: If this object is a symbolic link, follow the link to its physical counterpart. .PP \fIComparf\fR, if not NULL, is a pointer to a function used to define a search ordering for children of a directory. If FTW_CHILDREN is turned on, the ordering of the children of a directory is done before the preorder call to \fIuserf\fR on that directory. Therefore, in that case, \fIftw->link\fR will point to the smallest child. .PP The \fIcomparf\fP prototype is: .PP .nf int comparf(struct FTW* ftw1, struct FTW* ftw2) .fi .PP \fIComparf\fR should return a value <0, 0, or >0 to indicate whether \fIftw1\fR is considered smaller, equal, or larger than \fIftw2\fR. .PP \fIFtwalk\fR normally returns 0. On hard errors such as running out of memory, it returns -1. \fIFtwalk\fR may also return other values as discussed with respect to \fIuserf\fR. .PP \fIFtwflags\fR returns a combination of \fB0, FTW_META, FTW_PHYSICAL\fR according to the preferences specified by \fBastconf("PATH_RESOLVE",0,0)\fR: .TP .B logical 0 .TP .B metaphysical .B "FTW_META|FTW_PHYSICAL" .TP .B physical .B FTW_PHYSICAL .SH HISTORY \fIFtwalk\fR performs similar functions as that of the routine \fIftw\fR provided in System V. However, it is more general than \fIftw\fR and suitable for use as a base in implementing popular tools such as \fIls, find, tar, du,\fR and \fIrm\fR. \fIFtwalk\fR also handles symbolic links and hard links gracefully. .SH AUTHORS Phong Vo, Glenn Fowler, Dave Korn .SH SEE ALSO find(1), rm(1), du(1), ls(1), tar(1), stat(2), symlink(2), astfeature(3), ftw(3), pathcd(3)