Package: manpages-dev Version: 2.28-1 Severity: wishlist Tags: patch I ended up making a number of other changes to ftw.3, which, for example, dropped the duplicated documentation of _fn_.
--- - 2006-05-17 22:49:55.992165000 -0400 +++ fts.3 2006-05-11 19:43:04.000000000 -0400 @@ -746,7 +746,8 @@ .Xr find 1 , .Xr chdir 2 , .Xr stat 2 , -.Xr qsort 3 +.Xr qsort 3 , +.Xr ftw 3 .Sh "CONFORMING TO" 4.4BSD. The .Nm fts --- - 2006-05-17 22:48:56.488835000 -0400 +++ ftw.3 2006-05-17 22:48:25.000000000 -0400 @@ -1,6 +1,9 @@ .\" Copyright (c) 1993 Michael Haardt ([EMAIL PROTECTED]) .\" Copyright (c) 1999 Andries Brouwer ([EMAIL PROTECTED]) -.\" Fri Jun 25 00:34:07 CEST 1999 +.\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith ([EMAIL PROTECTED]) +.\" Modified Wed May 17 22:09:05 2006 by Justin Pryzby +.\" <[EMAIL PROTECTED]>; document FTW_ACTIONRETVAL; +.\" include .SH "RETURN VALUE"; reorganized and rearranged the page .\" .\" This is free documentation; you can redistribute it and/or .\" modify it under the terms of the GNU General Public License as @@ -21,75 +24,69 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" -.\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith ([EMAIL PROTECTED]) -.TH FTW 3 1999-06-25 "Linux" "Linux Programmer's Manual" +.TH FTW 3 2006-05-17 GNU "Linux Programmer's Manual" .SH NAME ftw, nftw \- file tree walk .SH SYNOPSIS .B #include <ftw.h> .sp -.BI "int ftw(const char *" dir ", int (*" fn ")(const" -.BI "char *" file ", const struct stat *" sb ", int " flag ), -.BI "int " nopenfd ); -.sp -.BI "int nftw(const char *" dir ", int (*" fn ")(const" -.BI "char *" file ", const struct stat *" sb ", int " flag , -.BI "struct FTW *" s ), -.BI "int " nopenfd ", int " flags ); +\fBtypedef int (*\fIftw_func_t\fP)(const char *\fPfile\fP, const +struct stat *\fPsb\fP, int \fPflag\fP); +.sp +\fBint ftw(const char *\fIdir\fP, ftw_func_t \fPfn\fP, int \fPnopenfd\fP); +.sp +\fB#define _XOPEN_SOURCE 500 +.sp +\fBtypedef int (*\fInftw_func_t\fP)(const char *\fPfile\fP, const +struct stat *\fPsb\fP, int \fPflag\fP, struct FTW *\fPs\fP); +.sp +\fBint nftw(const char *\fIdir\fP, nftw_func_t \fPfn\fP, int +\fPnopenfd\fP, int \fPflags\fP); .SH DESCRIPTION -\fBftw\fP() walks through the directory tree starting from the indicated -directory \fIdir\fP. For each found entry in the tree, it calls -\fIfn\fP() with the full pathname of the entry, a pointer to the -.BR stat (2) -structure for the entry and an int \fIflag\fP, which value will be one of -the following: +\fBftw\fP() walks recursively through the path hierarchy beginning at +\fIdir\fP, and calls \fIfn\fP() for each directory entry found. +Directories are handled before the files and subdirectories they +contain (\*(lqbreadth\-first\*(rq). + +To avoid exceeding a program's file descriptor limit, \fInopenfd\fP +specifies the maximum number of directories (not including the +deepest, active directory) allowed to be opened by \fBftw\fP() at any +given time. When the given limit is reached, some directories will be +closed and later reopened. + +The pathname of the entry relative to \fIdir\fP is passed to \fIfn\fP +as \fIfile\fP; a pointer to the \fBstat\fP(2) structure for the entry +is available as \fIsb\fP, and a file\-type of the entry is available +as \fIflag\fP, which has one of the following values: +.RS .TP .B FTW_F -Item is a normal file +Entry is a normal file .TP .B FTW_D -Item is a directory +Entry is a directory .TP .B FTW_DNR -Item is a directory which can't be read +Entry is a directory which cannot be read .TP .B FTW_SL -Item is a symbolic link +Entry is a symbolic link .TP .B FTW_NS -The stat failed on the item which is not a symbolic link -.LP -If the item is a symbolic link and stat failed, XPG4v2 states -that it is undefined whether FTW_NS or FTW_SL is used. -.PP -\fBftw\fP() recursively calls itself for traversing found directories, -handling a directory before its files or subdirectories. -To avoid using up all a program's file descriptors, \fInopenfd\fP -specifies the maximum number of simultaneous open directories. When -the search depth exceeds this, \fBftw\fP() will become slower because -directories have to be closed and reopened. \fBftw\fP() uses at most -one file descriptor for each level in the file hierarchy. -.PP -To stop the tree walk, \fIfn\fP() returns a non-zero value; this -value will become the return value of \fBftw\fP(). Otherwise, -\fBftw\fP() will continue until it has traversed the entire tree, in -which case it will return zero, or until it hits an error other than EACCES -(such as a -.BR malloc (3) -failure), in which case it will return \-1. +The \fBstat\fP failed on the entry, which is not a symbolic link +.RE +.sp +If \fIfile\fP is a symbolic link and \fBstat\fP failed, XPG4v2 states +that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP is used. .PP -Because \fBftw\fP() uses dynamic data structures, the only safe way to -exit out of a tree walk is to return a non-zero value. To handle -interrupts, for example, mark that the interrupt occurred and return a -non-zero value\(emdon't use -.BR longjmp (3) -unless the program is going to terminate. - -The function \fBnftw\fP() does precisely the same as \fBftw\fP(), -except that it has one additional argument \fIflags\fP -(and calls the supplied function with one more argument). -This \fIflags\fP argument is an OR of zero or more of the following flags: +If the callback function \fIfn\fP() returns zero, \fBftw\fP() +continues until it has traversed the entire tree. If \fIfn\fP() +returns a non\-zero value, \fBftw\fP() will abort the walk, free its +internally\-allocated resources, and return with that value. + +\fBnftw\fP() behaves like \fBftw\fP(), but accepts the additional +argument \fIflags\fP, which is a bitwise OR of zero or more of the +following values: .TP .B FTW_CHDIR If set, do a @@ -97,50 +94,83 @@ to each directory before handling its contents. .TP .B FTW_DEPTH -If set, do a depth-first search, that is, call the function for -the directory itself only after handling the contents of the directory -and its subdirectories. +If set, do a \*(lqdepth\-first\*(rq walk, calling \fIfn\fP() for each +directory after recursively handling its contents, instead of before. +The \fIflag\fP for all directories is then \fBFTW_DP\fP. .TP .B FTW_MOUNT If set, stay within the same file system. .TP .B FTW_PHYS -If set, do not follow symbolic links. -(This is what you want.) +If set, do not follow symbolic links (this is what you want). If not set, symbolic links are followed, but no file is reported twice. +.TP +.B FTW_ACTIONRETVAL +If set, allows for special actions to be taken by \fBnftw()\fP based +on the return value of \fIfn\fP(); the following values are +recognized: +.RS +.TP +.B FTW_CONTINUE +Instructs \fBnftw\fP() to continue normally. +.TP +.B FTW_STOP +Causes \fBnftw\fP() to return immediately with the return value +\fBFTW_STOP\fP. +.TP +.B FTW_SKIP_SUBTREE +If \fIfn\fP() is called with an object of type \fBFTW_D\fP, this return +value will prevent objects within that directory from being passed as +arguments to \fIfn\fP(). +.TP +.B FTW_SKIP_SIBLINGS +If \fIfn\fP() is passed some object, and it returns this value, then +\*(lqsiblings\*(rq of that object will be skipped. If \fBFTW_DEPTH\fP +is set, the object's parent directory is processed next (with +\fIflag\fP set to \fBFTW_DP\fP). +.RE +.sp +.RS +.R Other return values could be associated with new actions in the +.R future; values with as\-of\-yet defined actions should not be used. +.RE .LP -If FTW_PHYS is not set, but FTW_DEPTH is set, then the function +If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set, then the function .IR fn () is never called for a directory that would be a descendant of itself. -.LP -The function -.IR fn () -is called with four arguments: the pathname of the reported entry, -a pointer to a struct stat for this entry, an integer describing -its type, and a pointer to a struct FTW. The type will be one -of the following: FTW_F, FTW_D, FTW_DNR, FTW_SL, FTW_NS -(with meaning as above; FTW_SL occurs only with FTW_PHYS set) or + +\fIflag\fP has the same meaning as for \fBftw\fP(), and can take on +any of the same values, as well as: .TP .B FTW_DP -Item is a directory and all its descendants have been handled -already. (This occurs only with FTW_DEPTH set.) +Entry is a directory, and \fBFTW_DEPTH\fP was used. All of the files +and subdirectories within \fIfile\fP have been processed. .TP .B FTW_SLN -Item is a symbolic link pointing to a nonexisting file. -(This occurs only with FTW_PHYS unset.) +Entry is a symbolic link pointing to a nonexistant file, and +\fBFTW_PHYS\fP was not set. .LP -The struct FTW pointed to by the fourth argument to -.IR fn () -has at least the fields -.IR base , -the offset of the item's filename in the pathname -given as first argument of -.IR fn (), -and -.IR level , -the depth of the item relative to the starting point -(which has depth 0). +.BR FTW_SL " occurs only when " FTW_PHYS " is set. + +\fIs\->p\fP is the offset into \fIfile\fP of the entry's filename; the +first \fIbase\fP bytes are the \*(lqdirectory component\*(rq, and the +remaining portion is the filename; \fIs\->level\fP is the number of +pathname components of \fIfile\fP relative to \fIdir\fP, including the +filename. +.SH "RETURN VALUE" +These functions return 0 on success, and \-1 if an internal error +(other than EACCES) occurs. + +If \fIfn\fP() returns nonzero, and \fBFTW_ACTIONRETVAL\fP is unset (or +\fBftw\fP() is used), or if \fBFTW_ACTIONRETVAL\fP is set and +\fIfn\fP() returns \fBFTW_STOP\fP, then the walk is aborted with the +return value used by \fIfn\fP. .SH NOTES +The only way to cancel the walk which will cause resources to be freed +is for \fIfn\fP() to return nonzero. Any other method (such as +\fBlongjmp\fP(3)) will leak memory. To handle signals without +leaking, set a flag for \fIfn\fP() to check. + The function .BR nftw () and the use of FTW_SL with @@ -161,8 +191,10 @@ that can be stat'ed but are not a directory. The function .BR nftw () -is available since glibc 2.1. +is available since glibc 2.1. \fBFTW_ACTIONRETVAL\fP is specific to +glibc. .SH "CONFORMING TO" AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2. .SH "SEE ALSO" -.BR stat (2) +.BR stat (2), +.BR fts (3) -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
