ftw(3C) 																   ftw(3C)

NAME

       ftw(), nftw() - walk a file tree executing a function

SYNOPSIS

   UNIX95
   Obsolescent Interfaces
DESCRIPTION

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

	      The object is a file.

	      The object is a directory.

	      The object is a symbolic link.

	      The object is a directory without read permission.
			     fn will not be called for any of its descendants.

	      failed on the object.  The contents of the
			     structure	are undefined.	If the failure was caused by a lack of permissions, the walk will continue.  For all other
			     errors will terminate the walk and return

       Tree traversal continues until the tree is exhausted, an invocation of fn returns a nonzero value, or an error is detected within  such	as
       an  I/O error.  If the tree is exhausted, returns zero.	If fn returns a nonzero value, stops its tree traversal and returns the same value
       as returned by fn.  If detects an error, it returns and sets the error type in (see errno(2)).

       reports a directory before reporting any of its descendants.

       and use one file descriptor for each level in the tree.	The depth argument limits the number of file descriptors that  can  be	used.	If
       depth  is  0  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.  For best performance, depth should be at least as large as the number of levels in the tree.

       is similar to except that it takes the additional argument flags, and does not report or enter a directory which has already  been  visited
       during the walk.  The flags field is the inclusive OR of the following values, as defined in the header file:

	      If set,	     does a physical walk.  It will not follow symbolic links, but will follow hard links.

			     If  clear,  follows  both	symbolic  and  hard  links.  In addition, if the environment is defined, no object will be
			     reported to fn more than once.  Classic HP behavior will report a file as many times as it is referenced.

	      If set,	     will only report files in the same file system as path.  (See for	one  exception	involving  loopback  file  systems
			     (LOFS)).

			     If clear, will report all objects encountered in the walk.

	      If set,	     performs a depth-first search.  A directory's contents will be reported before the directory is reported to fn.

			     If clear, the directory will be reported before its descendants.

	      If set, the walk does a
			     (see chdir(2)) to each directory before reading its contents.  At the time a directory is reported to fn, the current
			     working directory will be the parent of the reported directory.  A directory must have both read and execute  permis-
			     sions, otherwise the directory is reported as a object, no will be done and it will not be entered.

			     If  clear,  will not alter the process' current working directory, and the directory only needs read permission to be
			     reported as a or object.

	      If set and any or failure occurs, fn is called with the object flag and the walk continues.

			     If clear and or fails due to lack of permissions, fn is called with the object type.  If the environment is  defined,
			     the walk continues.  The HP classic behavior will terminate the walk and return For any error other than permissions,
			     or any error from other system calls such as opendir(3C) or readdir(3C), does not call fn, terminates  the  walk  and
			     returns

       calls  fn with four arguments for each object reported.	The first argument is the path name of the file, directory, or symbolic link.  The
       second argument is a pointer to a structure (see lstat(2)) containing information about the object.  The third argument is an integer  giv-
       ing additional information as follows:

	      The object is a file.

	      The object is a directory.

	      The object is a directory and subdirectories have been visited.
			     This can be passed to fn only if is specified.

	      The object is a symbolic link.
			     This can be passed to fn only if is specified.

	      The object is a symbolic link that does not point to an existing object.
			     This can be passed to fn only if is not specified.

	      The object is a directory that cannot be read, or does not have execute
			     permissions when is specified.  The function fn is not called for any of the directory's descendants.

	      or	     failed on the object.  The contents of the structure passed to fn are undefined.  If the failure occurred due to lack
			     of permissions, is set to If the environment is defined, the walk will always continue after permissions errors.  For
			     classic HP behavior, the flag must be set for the walk to continue.

			     Note that this behavior differs from

       The  fourth  argument  is  different for the default environment and the environment. For the default environment, the fourth argument is a
       structure For the environment, the fourth argument is a pointer to a structure (ie: contains the following members:

       The value of base is the offset from the first character in the path name to where the base name of the object starts; this  path  name	is
       passed  as  the	first  argument  to fn.  The value of level indicates depth relative to the start of the walk, where the start level has a
       value of zero.

APPLICATION USAGE

       can execute concurrently in separate threads.  and are serialized if the path argument is relative (i.e., does not start with '/'), or  the
       flag is set.  For best concurrency, call with an absolute starting path and do not set

       To  use	the  prototype, the environment must be defined. This is done by defining the environment variable, passing the flag as a compiler
       option, and adding to your path. This can be done as follows:

       1.
       2.
       3.

       is to be obsoleted at a future date.

ERRORS

       If or fails, it sets (see errno(2)) to one of the following values:

	      [EACCES]		   If a component of the path prefix denies search permission, or if  read  permission	is  denied  for  path,	fn
				   returns and does not reset

	      [EINVAL]		   The value of the depth argument is invalid.

	      [ENAMETOOLONG]	   The	length	of  the  specified  path name exceeds bytes, or the length of a component of the path name exceeds
				   bytes while is in effect.

	      [ENOENT]		   path points to the name of a file that does not exist, or points to an empty string.

	      [ENOTDIR] 	   A component of path is not a directory.

	      [EOVERFLOW]	   One or more of the values in or is too large to store in the structure to be passed to the function pointed	to
				   by fn.  Use or instead for 32-bit applications.

       In addition, if the function pointed to by fn encounters system errors, may be set accordingly.

WARNINGS

       For  32-bit  applications,  will be truncated to its least significant 32-bits for filesystems that use 64-bit values.  Note that this will
       even occur for calls because is defined as an unsigned long.

       For 32-bit applications accessing large file systems, use or instead in order to avoid overflow of the structure.

       contains some recursion and it is possible for it to terminate with a memory fault when applied to file trees which contain a large  number
       of directories, or a large number of files when FTW_PHYS is clear and the UNIX95 environment is defined.

       uses  to  allocate  dynamic  storage  during  operation (see malloc(3C)).  If it is forcibly terminated (such as if is executed by fn or an
       interrupt routine), the calling function will not have a chance to free that storage, causing it to remain allocated until the process ter-
       minates.   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.

       If the starting path is in a loopback file system (LOFS) and is set (to stay within the LOFS), but is clear (symbolic and  hard	links  are
       followed),  cannot  determine  whether  a link referencing a file on the same _device_ is really within the LOFS.  It is possible with this
       specific combination of factors to have some files reported to fn which should not be.

   Obsolescent Interfaces
       is to be obsoleted at a future date.

AUTHOR

       and were developed by AT&T and HP.

SEE ALSO

       stat(2), fgetpos64(3S), malloc(3C), thread_safety(5).

STANDARDS CONFORMANCE

																	   ftw(3C)