1fswalk_new
2
3 SYNOPSIS
4  Create an object to walk the filesystem tree
5
6 USAGE
7  obj = fswalk_new (Ref_Type dirfunc, Ref_Type filefunc; qualifiers)
8
9 DESCRIPTION
10  The `fswalk_new' function creates an object that is useful
11  for exploring a filesystem tree.  It requires two arguments that
12  are references to functions to be called when a directory or file is
13  encountered.  Each of these functions is passed at least two
14  arguments: the name of the file or directory (including leading path
15  elements relative to the directory where processing started), and
16  the stat structure of the of the file or directory.  Qualifiers may
17  be used to specify additional arguments.
18
19  The object's `walk' method is the one that actually walks the
20  filesystem.
21
22  The directory callback function must return an integer value that
23  indicates how it should be processed.  If the function returns 0,
24  then the directory will be skipped (pruned).  A positive value
25  indicates that the directory will processed.  If the function
26  returns a negative value, then no further processing by the walk
27  function will take place and control will pass to the user.
28
29  The file callback function must also return an integer that
30  indicates how processing should continue.  If it returns a positive
31  value, then additional files in the corresponding directory will be
32  processed.  If it returns 0, then no further files or subdirectories
33  of the directory will be processed, and processing will continue to
34  take place in the parent directory.  Otherwise, the return value is
35  negative, which indicates that processing should be stopped and
36  control will pass back to the caller.
37
38 QUALIFIERS
39  The following qualifiers are supported:
40
41   dargs={args...}
42
43    `dargs' is a list of additional arguments that will be added when
44    calling the directory callback function.
45
46   fargs={args...}
47
48    `fargs' is a list of additional arguments that will be added when
49    calling the file callback function.
50
51   followlinks[=val]
52
53    The `followlinks' qualifier may be used to indicate whether
54    or not directories that are symbolic links are to be followed.  By
55    default, they are not.  If `followlinks' is present with no
56    value, or has a non-zero value, then symbolic links will be
57    followed.  Otherwise, if `followlinks' is not present, or is
58    set to 0, then directories that are symbolic links will be skipped.
59
60 METHODS
61
62   .walk (String_Type top_dir)
63
64    The `.walk' function walks the filesystem starting at the
65    specified top-level directory calling the directory and file
66    callback functions as it goes.
67
68 EXAMPLE
69  Print a list of all files containing a `.png' extension under
70  the current directory:
71
72     private define file_callback (name, st)
73     {
74        if (".png" == path_extname (name))
75          message (name);
76        return 1;
77     }
78     variable w = fswalk_new (NULL, &file_callback);
79     w.walk (".");
80
81
82  Get a list of all directories that are symbolic links under /usr.
83
84     private define dir_callback (name, st, list)
85     {
86        st = lstat_file (name);
87        if (stat_is ("lnk", st.st_mode))
88          {
89            list_append (list, name);
90            return 0;
91          }
92        return 1;
93     }
94
95     define get_symdir_list (top)
96     {
97        variable list = {};
98        variable w = fswalk_new (&dir_callback, NULL
99                                 ;dargs={list}, followlinks);
100        w.walk (top);
101        return list;
102     }
103     symdirlist = get_symdir_list ("/usr");
104
105  Note that in this example, the dir_callback function returns 0 if
106  the directory corresponds to a symbolic link.  This causes the link
107  to not be followed.
108
109  Get a list of dangling symbolic links:
110
111     private define file_callback (name, st, list)
112     {
113        if (stat_is ("lnk", st.st_mode))
114          {
115             if ((NULL == stat_file (name))
116                 && (errno == ENOENT))
117               list_append (list, name);
118          }
119        return 1;
120     }
121
122     define get_badlinks (top)
123     {
124        variable list = {};
125        variable w = fswalk_new (NULL, &file_callback ;fargs={list});
126        w.walk (top);
127        return list;
128     }
129
130
131 SEE ALSO
132  glob, stat_file, lstat_file, listdir;
133
134--------------------------------------------------------------
135