VMS Help  —  CRTL  ftw
    Walks a file tree.

    Format

      #include  <ftw.h>

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

1  –  Arguments

 path

    The directory hierarchy to be searched.

 function

    The function to be invoked for each file in the directory
    hierarchy.

 depth

    The maximum number of directory streams or file descriptors, or
    both, available for use by ftw. This argument should be in the
    range of 1 to OPEN_MAX.

2  –  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.

3  –  Return Values

    0                  Indicates success.
    x                  Indicates that the function specified by
                       the function argument stops its search, and
                       returns the value that was returned by the
                       function.
    -1                 Indicates an error; errno is set to one of the
                       following values:

                       o  EACCES - Search permission is denied for
                          any component of the path argument or read
                          permission is denied for the path argument.

                       o  ENAMETOOLONG - The length of the path
                          string exceeds PATH_MAX, or a pathname
                          component is longer than NAME_MAX while
                          [_POSIX_NO_TRUNC] is in effect.

                       o  ENOENT - The path argument points to the
                          name of a file that does not exist or
                          points to an empty string.

                       o  ENOMEM - There is insufficient memory for
                          this operation.

                       Also, if the function pointed to by the
                       function argument encounters an error, errno
                       can be set accordingly.
Close Help