Click above to get retro games delivered to your door ever month!

ftw
===

Syntax
------

     #include <ftw.h>
     
     int ftw(const char *dir,
             int (*func)(const char *path, struct stat *stbuf, int flag),
             int depth);

Description
-----------

This function recursively descends the directory hierarchy which starts
with DIR.  For each file in the hierarchy, `ftw' calls the user-defined
function FUNC which is passed a pointer to a `NULL'-terminated
character array in PATH holding the full pathname of the file, a
pointer to a `stat' structure (stat:.) STBUF with a filesystem   
information about that file, and an integer FLAG.  Possible values of
FLAG are:

`FTW_F'
     This is a regular file.

`FTW_D'
     This is a directory.

`FTW_VL'
     This is a volume label.

`FTW_DNR'
     This is a directory which cannot be read with `readdir()'.  (This
     will never happen in DJGPP.)

`FTW_NS'
     This file exists, but `stat' fails for it.

If FLAG is `FTW_DNR', the descendants of that directory won't be
processed.  If FLAG is `FTW_NS', then STBUF will be garbled.

This function always visits a directory before any of its siblings.  The
argument DIR must be a directory, or `ftw' will fail and set ERRNO to
`ENOTDIR'.  The function FUNC is called with DIR as its argument before
the recursive descent begins.

The DEPTH argument has no meaning in the DJGPP implementation and is
always ignored.

The tree traversal continues until one of the following events:

(1)  The tree is exhausted (i.e., all descendants of DIR are
processed).  In this case, `ftw' returns 0, meaning a success.

(2)  An invocation of FUNC returns a non-zero value.  In this case,
`ftw' stops the tree traversal and returns whatever FUNC returned.

(3)  An error is detected within `ftw'.  In that case, `ftw' returns -1
and sets ERRNO (errno:.) to a suitable value.   

Return Value
------------

Zero in case the entire tree was successfully traversed, -1 if `ftw'
detected some error during its operation, or any other non-zero value
which was returned by the user-defined function FUNC.

Implementation Notes
--------------------

This function uses `malloc' (malloc:.) for dynamic memory   
allocation during its operation.  If FUNC disrupts the normal flow of
code execution by e.g. calling `longjump' or if an interrupt handler
which never returns is executed, this memory will remain permanently
allocated.

This function calls `opendir()' and `readdir()' functions to read the
directory entries.  Therefore, you can control what files will your
FUNC get by setting the appropriate bits in the external variable
__OPENDIR_FLAGS.  opendir:, for description of these bits.   

This function also calls `stat' for every directory entry it passes to
FUNC.  If your application only needs some part of the information
returned in the `stat' structure, you can make your application
significantly faster by setting bits in the external variable
_DJSTAT_FLAGS (_djstat_flags:. for details).  The most expensive   
`stat' features are `_STAT_EXEC_MAGIC' and `_STAT_DIRSIZE'.

Example
-------

     #include <stdlib.h>
     
     int
     file_walker(const char *path, struct stat *sb, int flag)
     {
       char *base;
     
       printf("%s:\t%u\t", path, sb->st_size);
       if (S_ISLABEL(sb->st_mode))
         printf("V");
       if (S_ISDIR(sb->st_mode))
         printf("D");
       if (S_ISCHR(sb->st_mode))
         printf("C");
       if (sb->st_mode & S_IRUSR)
         printf("r");
       if (sb->st_mode & S_IWUSR)
         printf("w");
       if (sb->st_mode & S_IXUSR)
         printf("x");
     
       if (flag == FTW_NS)
         printf("  !!no_stat!!");
       printf("\n");
     
       base = strrchr(path, '/');
       if (base == 0)
         base = strrchr(path, '\\');
       if (base == 0)
         base = strrchr(path, ':');
       if (strcmp(base == 0 ? path : base + 1, "xxxxx") == 0)
         return 42;
       return 0;
     }
     
     int
     main(int argc, char *argv[])
     {
       if (argc > 1)
         {
           char msg[80];
     
           sprintf(msg, "file_tree_walk: %d",
                        ftw(argv[1], file_walker, 0));
           if (errno)
             perror(msg);
           else
             puts(msg);
         }
       else
         printf("Usage: %s dir\n", argv[0]);
     
       return 0;
     }