*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Linux man pages -> ftw (3)              



NAME    [Toc]    [Back]

       ftw, nftw - file tree walk

SYNOPSIS    [Toc]    [Back]

       #include <ftw.h>

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

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

DESCRIPTION    [Toc]    [Back]

       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    [Toc]    [Back]
	      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, handling
 a directory before its files or subdirectories.  To  avoid  using
       up  all a program's file descriptors, the depth specifies the number of
       simultaneous open directories.  When the depth is exceeded, 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	interrupts,
  for example, mark that the interrupt occurred and return a nonzero
 value--don't use longjmp(3) unless the program is going to	terminate.

       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    [Toc]    [Back]
	      If set, do a chdir() to each directory before handling its  contents.

       FTW_DEPTH    [Toc]    [Back]
	      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    [Toc]    [Back]
	      If set, stay within the same file system.

       FTW_PHYS    [Toc]    [Back]
	      If  set, do not follow symbolic links.  (This is what you want.)
	      If not set, symbolic links are followed, but no file is reported

       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    [Toc]    [Back]
	      Item  is	a symbolic link pointing to a nonexisting file.  (This
	      occurs only with FTW_PHYS unset.)

       The struct FTW pointed at 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 relative
 to the starting point (which has depth 0).

NOTES    [Toc]    [Back]

       The function nftw() and the use of FTW_SL with ftw() were introduced in
       XPG4v2.	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.  First glibc 2.1 supports FTW_SL and nftw().

CONFORMING TO    [Toc]    [Back]

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

SEE ALSO    [Toc]    [Back]


Linux				  1999-06-25				FTW(3)
[ Back ]
 Similar pages
Name OS Title
ftw IRIX walk a file tree
nftw Tru64 Walk a file tree
ftw OpenBSD traverse (walk) a file tree
nftw OpenBSD traverse (walk) a file tree
find OpenBSD walk a file hierarchy
find FreeBSD walk a file hierarchy
DXmSvnSetTreePosition Tru64 Sets the position of the tree in tree display mode.
ftw Tru64 Walks a file tree
dtfilsys HP-UX CDE file system; directory tree structure
tlink IRIX clone a file tree using symbolic links
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service