ftw man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

ftw(3C)			 Standard C Library Functions		       ftw(3C)

NAME
       ftw, nftw - walk a file tree

SYNOPSIS
       #include <ftw.h>

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

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

DESCRIPTION
       The  ftw() function 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. Pos‐
       sible values of the integer, defined in the <ftw.h> header, 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 are not processed.

       FTW_NS	  The  stat() function 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.

       The ftw() function visits  a  directory	before	visiting  any  of  its
       descendants.

       The tree traversal continues until the tree is exhausted, an invocation
       of fn returns a non-zero value, or some error is detected within	 ftw()
       (such  as  an I/O error). If the tree is exhausted, ftw() returns 0. If
       fn returns a non-zero value, ftw() stops its tree traversal and returns
       whatever value was returned by fn.

       The  nftw() function is similar to ftw() except that it takes the addi‐
       tional argument flags, which is a bitwise-inclusive OR of zero or  more
       of the following flags:

       FTW_CHDIR    If	set,  nftw()  changes the current working directory to
		    each directory as it reports files in that	directory.  If
		    clear,  nftw()  does not change the current working direc‐
		    tory.

       FTW_DEPTH    If set, nftw() reports all files  in  a  directory	before
		    reporting  the  directory itself. If clear, nftw() reports
		    any directory before reporting the files  in  that	direc‐
		    tory.

       FTW_MOUNT    If	set, nftw() reports only files in the same file system
		    as path. If clear, nftw() reports  all  files  encountered
		    during the walk.

       FTW_PHYS	    If	set, nftw() performs a physical walk and does not fol‐
		    low symbolic links.

       If FTW_PHYS is clear and FTW_DEPTH is set, nftw() follows links instead
       of  reporting  them,  but does not report any directory that would be a
       descendant of itself. If FTW_PHYS is  clear  and	 FTW_DEPTH  is	clear,
       nftw() follows links instead of reporting them, but does not report the
       contents of any directory that would be a descendant of itself.

       At each file it encounters, nftw() calls the user-supplied function  fn
       with four arguments:

	   o	  The first argument is the pathname of the object.

	   o	  The second argument is a pointer to the stat buffer contain‐
		  ing information on the object.

	   o	  The third argument is an integer giving additional  informa‐
		  tion. Its value is one of the following:

		  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. (This condition only occurs if  the
			     FTW_DEPTH flag is included in flags.)

		  FTW_SL     The  object  is  a symbolic link. (This condition
			     only occurs if the FTW_PHYS flag is  included  in
			     flags.)

		  FTW_SLN    The  object  is  a symbolic link that points to a
			     non-existent file. (This condition only occurs if
			     the FTW_PHYS flag is not included in flags.)

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

		  FTW_NS     The  stat() function failed on the object because
			     of lack of appropriate permission. The stat  buf‐
			     fer passed to fn is undefined.  Failure of stat()
			     for any other reason is considered an  error  and
			     nftw() returns −1.

	   o	  The  fourth  argument	 is a pointer to an FTW structure that
		  contains the following members:

		    int	  base;
		    int	  level;

		  The base member is the offset of the	object's  filename  in
		  the pathname passed as the first argument to fn(). The value
		  of level indicates the depth relative to  the	 root  of  the
		  walk, where the root level is 0.

		  The results are unspecified if the application-supplied fn()
		  function does not preserve the current working directory.

       Both ftw() and nftw() use one file descriptor for  each	level  in  the
       tree. The depth argument limits the number of file descriptors used. If
       depth is zero or negative, the effect is the same as if it were	1.  It
       must  not  be  greater  than  the  number of file descriptors currently
       available for use.  The ftw() function runs faster if depth is at least
       as large as the number of levels in the tree. Both ftw() and nftw() are
       able to descend to arbitrary depths in a file hierarchy and do not fail
       due  to	path  length  limitations unless either the length of the path
       name pointed to by the path argument exceeds  {PATH_MAX}	 requirements,
       or  for	ftw(),	the specified depth is less than 2, or for nftw(), the
       specified depth is less than 2 and FTW_CHDIR is not set. When ftw() and
       nftw()  return,	they close any file descriptors they have opened; they
       do not close any file descriptors that might have been opened by fn.

RETURN VALUES
       If the tree is exhausted, ftw() and nftw() return 0.  If	 the  function
       pointed	to by fn returns a non-zero value, ftw() and nftw() stop their
       tree traversal and return whatever value was returned by	 the  function
       pointed	to by fn. If ftw() and nftw() detect an error,	they return −1
       and set errno to indicate the error.

       If ftw() and nftw() encounter an error other than EACCES (see   FTW_DNR
       and FTW_NS above),  they return −1 and set errno to indicate the error.
       The external variable errno can contain any error value that is	possi‐
       ble  when  a  directory	is opened or when one of the stat functions is
       executed on a directory or file.

ERRORS
       The ftw() and nftw() functions will fail if:

       ELOOP	       A loop exists in symbolic links encountered during res‐
		       olution of the path argument

       ENAMETOOLONG    The  length  of	the  path  name pointed to by the path
		       argument exceeds {PATH_MAX}, or a path  name  component
		       is longer than {NAME_MAX}.

       ENOENT	       A  component  of path does not name an existing file or
		       path is an empty string.

       ENOTDIR	       A component of path is not a directory.

       EOVERFLOW       A field in the stat  structure  cannot  be  represented
		       correctly  in  the  current programming environment for
		       one or more files found in the file hierarchy.

       The ftw() function will fail if:

       EACCES	       Search permission is denied for any component  of  path
		       or read permission is denied for path.

       ENAMETOOLONG    The ftw() function has descended to a path that exceeds
		       {PATH_MAX} and the  depth  argument  specified  by  the
		       application is less than 2 and FTW_CHDIR is not set.

       The nftw() function will fail if:

       EACCES	 Search permission is denied for any component of path or read
		 permission is denied for path, or fn() returns	 −1  and  does
		 not reset errno.

       The nftw() and ftw() functions may fail if:

       ELOOP	       Too many symbolic links were encountered during resolu‐
		       tion of the path argument.

       ENAMETOOLONG    Pathname resolution of a symbolic link in the path name
		       pointed	to by the path argument produced an intermedi‐
		       ate result whose length exceeds {PATH_MAX}.

       The ftw() function may fail if:

       EINVAL	 The value of the depth argument is invalid.

       The nftw() function may fail if:

       EMFILE	 There are {OPEN_MAX} file descriptors currently open  in  the
		 calling process.

       ENFILE	 Too many files are currently open in the system.

       If the function pointed to by fn encounters system errors, errno may be
       set accordingly.

EXAMPLES
       Example 1 Walk a directory structure using ftw().

       The following example walks the current	directory  structure,  calling
       the  fn()  function  for	 every	directory entry, using at most 10 file
       descriptors:

	 #include <ftw.h>
	 ...
	 if (ftw(".", fn, 10) != 0) {
		perror("ftw"); exit(2);
	 }

       Example 2 Walk a directory structure using nftw().

       The following example walks the /tmp directory and its  subdirectories,
       calling	the nftw() function for every directory entry, to a maximum of
       5 levels deep.

	 #include <ftw.h>
	 ...
	 int nftwfunc(const char *, const struct stat *, int, struct FTW *);
	 int nftwfunc(const char *filename, const struct stat *statptr,
	       int fileflags, struct FTW *pfwt)
	 {
	       return 0;
	 }
	 ...
	 char *startpath = "/tmp";
	 int depth = 5;
	 int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
	 int ret;
	 ret = nftw(startpath, nftwfunc, depth, flags);

USAGE
       Because ftw() and nftw() are recursive, they can terminate with a  mem‐
       ory fault when applied by a thread with a small stack to very deep file
       structures.

       The  ftw()  and	nftw()	functions  allocate  resources	(memory,  file
       descriptors)  during their operation. If ftw() they are forcibly termi‐
       nated, such as by longjmp(3C) being executed by fn or an interrupt rou‐
       tine,  they  will  not  have  a chance to free those resources, so they
       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 non-zero value at its next invocation.

       The ftw() and nftw() functions have transitional interfaces for	64-bit
       file offsets.  See lf64(5).

       The  ftw()  function  is safe in multithreaded applications. The nftw()
       function is safe in multithreaded applications when the FTW_CHDIR  flag
       is not set.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Committed			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT-Safe with exceptions	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Standard		     │See standards(5).		   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       stat(2), longjmp(3C), attributes(5), lf64(5), standards(5)

SunOS 5.11			  30 Jan 2007			       ftw(3C)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net