ftw

FTW(3)			  Linux Programmer’s Manual		       FTW(3)



NAME
       ftw, nftw - file tree walk

SYNOPSIS
       #include <ftw.h>

       int ftw(const char *dir, int (*fn)(const char *file, const struct stat
       *sb, int flag), int nopenfd);

       int nftw(const char *dir, int (*fn)(const  char	*file,	const  struct
       stat *sb, int flag, struct FTW *s), int nopenfd, int flags);

DESCRIPTION
       ftw()  walks  through  the  directory tree starting from the indicated
       directory dir.  For each found entry in the tree, it calls  fn()	 with
       the full pathname of the entry, a pointer to the stat(2) structure for
       the entry and an int flag, which value will be one of the following:

       FTW_F  Item is a normal file

       FTW_D  Item is a directory

       FTW_DNR
	      Item is a directory which can’t be read

       FTW_SL Item is a symbolic link

       FTW_NS The stat failed on the item which is not a symbolic link

       If the item is a symbolic link and stat failed, XPG4v2 states that  it
       is undefined whether FTW_NS or FTW_SL is used.

       ftw()  recursively calls itself for traversing found directories, han-
       dling a directory before its files or subdirectories.  To avoid	using
       up  all	a  program’s  file descriptors, nopenfd specifies the maximum
       number of  simultaneous	open  directories.   When  the	search	depth
       exceeds	this, ftw() will become slower because directories have to be
       closed and reopened. ftw() uses at most one file descriptor  for	 each
       level in the file hierarchy.

       To  stop the tree walk, fn() returns a non-zero value; this value will
       become the return value of  ftw().   Otherwise,	ftw()  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 malloc(3)
       failure), in which case it will return -1.

       Because	ftw() uses dynamic data structures, the only safe way to exit
       out of a tree walk is to return a non-zero value.   To  handle  inter-
       rupts, for example, mark that the interrupt occurred and return a non-
       zero value—don’t use longjmp(3) unless the program is going to  termi-
       nate.

       The  function  nftw() does precisely the same as ftw(), except that it
       has one additional argument flags (and  calls  the  supplied  function
       with one more argument).	 This flags argument is an OR of zero or more
       of the following flags:

       FTW_CHDIR
	      If set, do a chdir() to each directory before handling its con-
	      tents.

       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.

       FTW_MOUNT
	      If set, stay within the same file system.

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

       If  FTW_PHYS  is not set, but FTW_DEPTH is set, then the function fn()
       is never called for a directory that would be a descendant of  itself.

       The  function  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

       FTW_DP Item  is	a directory and all its descendants have been handled
	      already. (This occurs only with FTW_DEPTH set.)

       FTW_SLN
	      Item is a symbolic link pointing to a nonexisting file.	(This
	      occurs only with FTW_PHYS unset.)

       The  struct FTW pointed to by the fourth argument to fn() has at least
       the fields base, the offset of the item’s  filename  in	the  pathname
       given as first argument of fn(), and level, the depth of the item rel-
       ative to the starting point (which has depth 0).

NOTES
       The function nftw() and the use of FTW_SL with ftw()  were  introduced
       in XPG4v2.

       On  some	 systems ftw() will never use FTW_SL, on other systems FTW_SL
       occurs only for symbolic links that do not point to an existing	file,
       and  again  on  other  systems ftw() will use FTW_SL for each symbolic
       link. For predictable control, use nftw().

       Under Linux, libc4 and libc5 and glibc 2.0.6 will use  FTW_F  for  all
       objects	(files,	 symbolic  links, fifos, etc) that can be stat’ed but
       are not a directory.  The function nftw()  is  available	 since	glibc
       2.1.

CONFORMING TO
       AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2.

SEE ALSO
       stat(2)




Linux				  1999-06-25			       FTW(3)