ftw man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

ftw(3C)								       ftw(3C)

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

   Obsolescent Interfaces
       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 val‐
       ues 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  sym‐
			     bolic 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

			     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	 envi‐
			     ronment  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 argu‐
       ment  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 giving
       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
			     This  can	be  passed to fn only if is not speci‐

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

	      or	     failed on the object.  The contents of the struc‐
			     ture 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

			     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

       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:


       is to be obsoleted at a future date.

       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

	      [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

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

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

       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 fol‐
       lowed), 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.

       and were developed by AT&T and HP.

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


List of man pages available for HP-UX

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]
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