ftw(3C)								       ftw(3C)

NAME    [Toc]    [Back]

     ftw, ftw64, nftw nftw64 - walk a file tree

SYNOPSIS    [Toc]    [Back]

     #include <ftw.h>

     int ftw (const char *path,	int (*fn) (const char *, const struct
	 stat *, int), int depth);

     int ftw64 (const char *path, int (*fn) (const char	*, const struct
	 stat64	*, int), int depth);

     int nftw (const char *path, int (*fn) (const char *, const	struct
	 stat *, int, struct FTW*), int	depth, int flags);

     int nftw64	(const char *path, int (*fn) (const char *, const struct
	 stat64	*, int,	struct FTW*), int depth, int flags);

DESCRIPTION    [Toc]    [Back]

     ftw recursively descends the directory hierarchy rooted in	path.  For
     each object in the	hierarchy, ftw calls the user-defined function fn,
     passing it	a pointer to a null-terminated character string	containing the
     name of the object, a pointer to a	stat structure (see stat(2))
     containing	information about the object, and an integer.  Possible	values
     of	the integer, defined in	the ftw.h header file, are:

     FTW_F	 The object is a file.

     FTW_D	 The object is a directory.

     FTW_DNR	 The object is a directory that	cannot be read.	 Descendants
		 of the	directory will not be processed.

     FTW_NS	 stat failed on	the object because of lack of appropriate
		 permission or the object is a symbolic	link that points to a
		 non-existent file. The	stat buffer passed to fn is undefined.

     ftw visits	a directory before visiting any	of its descendants.

     The tree traversal	continues until	the tree is exhausted, an invocation
     of	fn returns a nonzero value, or some error is detected within ftw (such
     as	an I/O error).	If the tree is exhausted, ftw returns zero.  If	fn
     returns a nonzero value, ftw stops	its tree traversal and returns
     whatever value was	returned by fn.	 If ftw	detects	an error other than
     EACCES, it	returns	-1, and	sets the error type in errno.

     The function ftw64	is identical to	ftw except that	it passes a pointer to
     a stat64 structure	(see stat64(2))	to the user supplied function fn.

     The function nftw is similar to ftw except	that it	takes an additional
     argument, flags.  The flags field is used to specify:




									Page 1






ftw(3C)								       ftw(3C)



     FTW_PHYS	 Physical walk,	does not follow	symbolic links.	 Otherwise,
		 nftw will follow links	but will not walk down any path	that
		 crosses itself.

     FTW_MOUNT	 The walk will not cross a mount point.

     FTW_DEPTH	 All subdirectories will be visited before the directory
		 itself.

     FTW_CHDIR	 The walk will change to each directory	before reading it.

     The function nftw calls fn	with four arguments at each file and
     directory.	 The first argument is the pathname of the object, the second
     is	a pointer to the stat buffer, the third	is an integer giving
     additional	information, and the fourth is a struct	FTW that contains the
     following members:

	  int base;
	  int level;
     base is the offset	into the pathname of the base name of the object.
     level indicates the depth relative	to the rest of the walk, where the
     root level	is zero.

     The values	of the third argument are as follows:

     FTW_F	 The object is a file.

     FTW_D	 The object is a directory.

     FTW_DP	 The object is a directory and subdirectories have been
		 visited.

     FTW_SLN	 The object is a symbolic link that points to a	non-existent
		 file.

     FTW_DNR	 The object is a directory that	cannot be read.	 fn will not
		 be called for any of its descendants.

     FTW_NS	 stat failed on	the object because of lack of appropriate
		 permission.  The stat buffer passed to	fn is undefined.  stat
		 failure other than lack of appropriate	permission (EACCES) is
		 considered an error and nftw will return -1.

     The function nftw64 is identical to nftw except that it passes a pointer
     to	a stat64 structure (see	stat64(2)) to the user supplied	function fn.

     Both ftw and nftw use one file descriptor for each	level in the tree.
     The depth argument	limits the number of file descriptors so used.	If
     depth is zero or negative,	the effect is the same as if it	were 1.	 depth
     must not be greater than the number of file descriptors currently
     available for use.	 ftw will run faster if	depth is at least as large as
     the number	of levels in the tree.	When ftw and nftw return, they close



									Page 2






ftw(3C)								       ftw(3C)



     any file descriptors they have opened; they do not	close any file
     descriptors that may have been opened by fn.

SEE ALSO    [Toc]    [Back]

     stat(2), malloc(3C).

NOTES    [Toc]    [Back]

     Because ftw is recursive, it is possible for it to	terminate with a
     memory fault when applied to very deep file structures.

     ftw uses malloc(3C) to allocate dynamic storage during its	operation.  If
     ftw is forcibly terminated, such as by longjmp being executed by fn or an
     interrupt routine,	ftw will not have a chance to free that	storage, so it
     will remain permanently allocated.	 A safe	way to handle interrupts is to
     store the fact that an interrupt has occurred, and	arrange	to have	fn
     return a nonzero value at its next	invocation.


									PPPPaaaaggggeeee 3333