common/man/ftwalk.3

.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)