Return to ftwalk.3 CVS log

Up to [Research Unix] / researchv10dc / cmd / odist / pax / man / man3

Annotation of researchv10dc/cmd/odist/pax/man/man3/ftwalk.3, revision 1.1

1.1     ! root        1: .TH FTWALK 3
        !             2: .SH NAME
        !             3: \fBftwalk\fR \- file tree walker
        !             4: .SH SYNOPSIS
        !             5: .ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i
        !             6: .PP
        !             7: .nf
        !             8: \fB
        !             9: #include <ftwalk.h>
        !            10: 
        !            11: ftwalk(char* path, int (*userf)(struct FTW* ftw), int options,
        !            12:        int (*comparf)(struct FTW* ftw1, struct FTW* ftw2))
        !            13: \fR
        !            14: .fi
        !            15: .SH DESCRIPTION
        !            16: .PP
        !            17: \fIFtwalk\fR traverses a directory hierarchy using depth-first search.
        !            18: Upon visiting each file or directory in the hierarchy, it calls
        !            19: the user function \fIuserf\fP to process that file or directory.
        !            20: On a directory object, \fIuserf\fR may be called twice, once in preorder
        !            21: and once in postorder.
        !            22: On a terminal object such as a file or an unreadable directory,
        !            23: \fIuserf\fP is called only once.
        !            24: Cycles due to hard links or symbolic links are detected
        !            25: to avoid infinite loops.
        !            26: .PP
        !            27: \fIPath\fR is the starting point of the search.
        !            28: It may be an absolute path name or a path name relative to
        !            29: the current directory.
        !            30: If \fIpath\fR is a null pointer or points to an empty string, it is treated
        !            31: as if it points to the current (dot) directory.
        !            32: .PP
        !            33: \fIOptions\fR consists of zero or more of the following bits:
        !            34: .IP
        !            35: FTW_CHILDREN:
        !            36: This implies preorder calls to \fIuserf\fR on directory objects.
        !            37: On such a call to \fIuserf\fR,
        !            38: the field \fIftw->link\fR (below) points to a link list of
        !            39: the children of the respective directory.
        !            40: Upon returning from \fIuserf\fP,
        !            41: if the field \fIftw->status\fR of any child object
        !            42: is set to FTW_SKIP (below), that child is pruned from the search.
        !            43: .IP
        !            44: FTW_DELAY: When \fBFTW_CHILDREN\fP is turned on,
        !            45: the fields \fIftw->statb\fP (\fIstruct stat\fP) of children objects
        !            46: remain undefined until these objects are visited.
        !            47: .IP
        !            48: FTW_DOT: Do not use \fIchdir\fR(2) during the traversal.
        !            49: Normally \fIchdir\fR is used so that
        !            50: the base name of the object about to be processed can be used
        !            51: in accessing its data.
        !            52: This can enhance \fIftwalk\fR efficiency but certain program effects
        !            53: such as core dumps may be generated in unexpected places
        !            54: or may not even be generated at all.
        !            55: Whenever \fIchdir\fR generates an error, if possible,
        !            56: the current directory is restored to the starting directory
        !            57: (see FTW_NAME and FTW_PATH).
        !            58: .IP
        !            59: FTW_MULTIPLE: The \fIpath\fP argument is treated as a \fIchar**\fP
        !            60: pointer to a null-terminated array of path names.
        !            61: All hierarchies rooted at these paths will be searched
        !            62: .IP
        !            63: FTW_POST: Calls to the user function are issued only in postorder.
        !            64: That is, \fIuserf\fP is called on a directory only after its descendants have
        !            65: been processed.
        !            66: The absence of this bit indicates that calls to the user functions
        !            67: are issued in preorder. That is, \fIuserf\fP is
        !            68: called on a directory before its descendants  are processed.
        !            69: .IP
        !            70: FTW_PHYSICAL: Use \fIlstat\fR(2) instead of \fIstat\fR(2) to get
        !            71: file status and allow detection of symbolic links.
        !            72: In addition, if each component
        !            73: of the absolute path to the starting object has search permission,
        !            74: the absolute path is used for early detection of cycles.
        !            75: .IP
        !            76: FTW_TWICE: Calls to the user function are issued in both preorder and postorder
        !            77: for directory objects.
        !            78: .IP
        !            79: FTW_USER: The first of 6 user defined option bits.
        !            80: These bits are ignored by \fIftwalk\fP.
        !            81: .PP
        !            82: \fIUserf\fR is a user supplied function that is
        !            83: called upon different visits of an object.
        !            84: If the return value of \fIuserf\fR is non-zero,
        !            85: \fIftwalk\fR returns immediately with the same value.
        !            86: The \fIuserf\fP prototype is:
        !            87: .PP
        !            88: .nf
        !            89:        int userf(struct FTW* ftw)
        !            90: .fi
        !            91: .PP
        !            92: \fBstruct FTW\fP contains at least the following elements:
        !            93: .PP
        !            94: .nf
        !            95:     struct FTW*    link;    /* link list of children */
        !            96:     struct FTW*    parent;  /* parent object on the search path */
        !            97:     union
        !            98:     {
        !            99:     long           number;  /* local number */
        !           100:     void*          pointer; /* local pointer */
        !           101:     }              local;   /* user defined */
        !           102:     struct stat    statb;   /* stat buffer of this object */
        !           103:     char*          path;    /* full pathname */
        !           104:     short          pathlen; /* strlen(path) */
        !           105:     unsigned short info;    /* type of object */
        !           106:     unsigned short status;  /* status of object */ 
        !           107:     short          level;   /* depth of object on the search path */
        !           108:     short          namelen; /* strlen(name) */
        !           109:     char           name[];  /* file name of object */
        !           110: .fi
        !           111: .PP
        !           112: The \fIlink\fR field is normally NULL.
        !           113: If the option FTW_CHILDREN was turned on,
        !           114: it points to the start of the list of children
        !           115: of the directory being visited in preorder.
        !           116: Finally, if the directory being visited causes a cycle,
        !           117: \fIlink\fR points to the object on the search path that is
        !           118: identical to this directory. Note that if FTW_PHYSICAL was turned on,
        !           119: this may point to a directory that is an ancestor of the starting
        !           120: object.
        !           121: .PP
        !           122: The \fIparent\fR field points to the parent object
        !           123: on the search path. For convenience, a parent object is also supplied for
        !           124: the starting object.
        !           125: In this case, except for the \fIlocal\fR field which is initialized
        !           126: to 0 and the \fIlevel\fR field which contains a negative number,
        !           127: the rest of the structure may be undefined.
        !           128: .PP
        !           129: The \fIinfo\fR field indicates the type of the object
        !           130: being visited and the type of the visit. The types are:
        !           131: .IP
        !           132: FTW_D: A directory being visited in preorder, i.e.,
        !           133: none of its children has been visited by the search.
        !           134: .IP
        !           135: FTW_DNX: A directory being visited in preorder that does not have
        !           136: search permission.
        !           137: .IP
        !           138: FTW_DP: A directory being visited in postorder, i.e., all of its
        !           139: descendants have been completely processed.
        !           140: .IP
        !           141: FTW_DC: A directory that causes cycles. This is a terminal object.
        !           142: .IP
        !           143: FTW_DNR: A directory that cannot be opened for reading. This is a terminal object.
        !           144: .IP
        !           145: FTW_F: An ordinary file.
        !           146: .IP
        !           147: FTW_SL: A symbolic link.
        !           148: Unless FTW_FOLLOW (below) is issued by the user function,
        !           149: this object is terminal.
        !           150: .IP
        !           151: FTW_NS: \fIStat\fR failed on this object.
        !           152: The stat buffer \fIstatb\fR is undefined.
        !           153: This object is terminal.
        !           154: .PP
        !           155: The \fIstatus\fR field of \fIstruct FTW\fR is used to communicate information
        !           156: between \fIftwalk\fR and \fIuserf\fR. On calls to \fIuserf\fR, it has one of
        !           157: two values:
        !           158: .IP
        !           159: FTW_NAME: The name of the object as defined in \fIftw->name\fR should be used for
        !           160: accessing its file information. This is because \fIchdir\fR(2) has been used
        !           161: to set the current directory to a suitable place (see FTW_CHDIR).
        !           162: .IP
        !           163: FTW_PATH: The argument \fIpath\fR of \fIuserf\fR should be used
        !           164: for accessing the file information of the object.
        !           165: .PP
        !           166: Upon returning, \fIuserf\fR may set the \fIstatus\fR field
        !           167: to one of the following values:
        !           168: .IP
        !           169: FTW_AGAIN: If this is a directory object being visited in postorder,
        !           170: it will be processed \fIagain\fR as if it had not been visited.
        !           171: .IP
        !           172: FTW_NOPOST: If this is a directory object being visited in preorder,
        !           173: the user function will not be called on its postorder visit.
        !           174: .IP
        !           175: FTW_SKIP: This object and its descendants are pruned from the search.
        !           176: .IP
        !           177: FTW_FOLLOW: If this object is a symbolic link,
        !           178: follow the link to its physical counterpart.
        !           179: .PP
        !           180: \fIComparf\fR, if not NULL, is a pointer to a function
        !           181: used to define a search ordering for children of a directory.
        !           182: If FTW_CHILDREN is turned on, the ordering of the children of
        !           183: a directory is done before the preorder call to \fIuserf\fR on that directory.
        !           184: Therefore, in that case, \fIftw->link\fR will point to the smallest child.
        !           185: .PP
        !           186: The \fIcomparf\fP prototype is:
        !           187: .PP
        !           188: .nf
        !           189:        int comparf(struct FTW* ftw1, struct FTW* ftw2)
        !           190: .fi
        !           191: .PP
        !           192: \fIComparf\fR should return a value <0, 0, or >0 to indicate whether
        !           193: \fIftw1\fR is considered smaller, equal, or larger than \fIftw2\fR.
        !           194: .PP
        !           195: \fIFtwalk\fR normally returns 0.
        !           196: On hard errors such as running out of memory, it returns -1.
        !           197: \fIFtwalk\fR may also return other values as discussed with respect
        !           198: to \fIuserf\fR. 
        !           199: .SH HISTORY
        !           200: \fIFtwalk\fR performs similar functions as that of
        !           201: the routine \fIftw\fR provided in System V.
        !           202: However, it is more general than \fIftw\fR
        !           203: and suitable for use as a base in implementing
        !           204: popular tools such as \fIls, find, tar, du,\fR and \fIrm\fR.
        !           205: \fIFtwalk\fR also handles symbolic links and hard links gracefully.
        !           206: .SH AUTHORS
        !           207: Phong Vo, Glenn Fowler, Dave Korn
        !           208: .SH SEE ALSO
        !           209: find(1), rm(1), du(1), ls(1), tar(1), stat(2), symlink(2), chdir(3), ftw(3).

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.