.\" Copyright (c) 1993 Michael Haardt (u31b3hs@pool.informatik.rwth-aachen.de), Sun Jul 18 17:47:18 MET DST 1993 .\" .\" This is free documentation; you can redistribute it and/or .\" modify it under the terms of the GNU General Public License as .\" published by the Free Software Foundation; either version 2 of .\" the License, or (at your option) any later version. .\" .\" The GNU General Public License's references to "object code" .\" and "executables" are to be interpreted as the output of any .\" document formatting or typesetting system, including .\" intermediate and printed output. .\" .\" This manual is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, .\" USA. .\" .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu) .TH FTW 3 "July 18, 1993" "Linux" "Linux Programmer's Manual" .SH NAME ftw \- file tree walk .SH SYNOPSIS .B #include .sp .BI "int ftw(const char *" directory ", int (*" funcptr .BI ")(const char *" file ", struct stat *" sb ", int " flag "), int " depth ); .SH DESCRIPTION \fBftw\fP() walks through the directory tree starting from the indicated \fIdirectory\fP. For each found entry in the tree, it calls \fIfuncptr\fP with the full pathname of the entry relative to \fIdirectory\fP, a pointer to a the second argument is a pointer to the .BR stat (2) structure for the entry and an int, which value will be one of the following: .RS .ta 1i .nf \fBFTW_F\fP Item is a normal file \fBFTW_D\fP Item is a directory \fBFTW_NS\fP The stat failed on the item \fBFTW_DNR\fP Item is a directory which can't be read .fi .RE Warning: Anything other than directories, like symbolic links, gets the \fBFTW_F\fP tag. .PP \fBftw\fP() recursively calls itself for traversing found directories. To avoid using up all a program's file descriptors, the \fIdepth\fP specifies the number of simultaneous open directories. When the depth is exceeded, \fBftw\fP() will become slower because directories have to be closed and reopened. .PP To stop the tree walk, \fIfuncptr\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 such as a .BR malloc (3) failure, in which case it will return \-1. .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. .SH "CONFORMING TO" AES, SVID2, SVID3, XPG2, XPG3, XPG4 .SH "SEE ALSO" .BR stat (2)