Description

   The ftw function recursively searches the directory hierarchy
   that descends from the directory specified by the path argument.
   The path argument can be specified in OpenVMS style or UNIX
   style.

   For each file in the hierarchy, ftw calls the function specified
   by the function argument, passes it a pointer to a null-
   terminated character string containing the name of the file, a
   pointer to a stat structure containing information about the
   file, and an integer.

   The integer identifies the file type. Possible values, defined in
   <ftw.h> are:

   FTW_F          Regular file.
   FTW_D          Directory.
   FTW_DNR        Directory that cannot be read.
   FTW_NS         A file on which stat could not successfully be
                  executed.

   If the integer is FTW_DNR, then the files and subdirectories
   contained in that directory are not processed.

   If the integer is FTW_NS, then the stat structure contents are
   meaningless. For example, a file in a directory for which you
   have read permission but not execute (search) permission can
   cause the function argument to pass FTW_NS.

   The ftw function finishes processing a directory before
   processing any of its files or subdirectories.

   The ftw function continues the search until:

   o  The directory hierarchy specified by the path argument is
      completed.

   o  An invocation of the function specified by the function
      argument returns a nonzero value.

   o  An error (such as an I/O error) is detected within the ftw
      function.

   Because the ftw function is recursive, it is possible for it
   to terminate with a memory fault because of stack overflow when
   applied to very deep file structures.

   The ftw function uses the malloc function to allocate dynamic
   storage during its operation. If ftw is forcibly terminated,
   as with a call to longjmp from the function pointed to by the
   function argument, ftw has no chance to free that storage. It
   remains allocated.

   A safe way to handle interrupts is to store the fact that
   an interrupt has occurred, and arrange to have the function
   specified by the function argument return a nonzero value the
   next time it is called.

                                 NOTES

      o  The ftw function is reentrant; make sure that the
         function supplied as argument function is also reentrant.

      o  The C RTL supports a standard-compliant definition of the
         stat structure and associated definitions. To use them,
         compile your application with the _USE_STD_STAT feature-
         test macro defined. See the <stat.h> header file on your
         system for more information.

      o  The ftw function supports UNIX style path name
         specifications.

   See also malloc, longjump, and stat.