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 (see section 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 (see section 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 (see section 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. See section 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 (see section _djstat_flags for details). The most expensive stat features are _STAT_EXEC_MAGIC and _STAT_DIRSIZE.

Portability

ANSI/ISO C	No
POSIX	No

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; }