To load support for the filesystem tree walk procedures
(use-modules (ice-9 ftw))
[NOTE: The following description was adapted from the GNU libc info page, w/
significant modifications for a more "Schemey" interface. Most noticible are
the inlining of
struct FTW * parameters
and the omission of
The X/Open specification defines two functions to process whole
hierarchies of directories and the contained files. Both functions
ftw family take as one of the arguments a callback function
which must be of these types.
Type for callback functions given to the
ftwfunction. The first parameter is a filename, the second parameter is the vector value as returned by calling
The last parameter is a symbol giving more information about filename. It can have one of the following values:
- The current item is a normal file or files which do not fit into one of the following categories. This means especially special files, sockets etc.
- The current item is a directory.
statcall to fill the object pointed to by the second parameter failed and so the information is invalid.
- The item is a directory which cannot be read.
- The item is a symbolic link. Since symbolic links are normally followed seeing this value in a
ftwcallback function means the referenced file does not exist. The situation for
The first three arguments have the same as for the
ftw-callbacktype. A difference is that for the third argument some additional values are defined to allow finer differentiation:
- The current item is a directory and all subdirectories have already been visited and reported. This flag is returned instead of
depthflag is given to
- The current item is a stale symbolic link. The file it points to does not exist.
The last two parameters are described below. They contain information to help interpret filename and give some information about current state of the traversal of the directory hierarchy.
- The value specifies which part of the filename argument given in the first parameter to the callback function is the name of the file. The rest of the string is the path to locate the file. This information is especially important if the
nftwwas set since then the current directory is the one the current item is found in.
- While processing the directory the functions tracks how many directories have been examined to find the current item. This nesting level is 0 for the item given starting item (file or directory) and is incremented by one for each entered directory.
Do a filesystem tree walk starting at filename using proc.
ftwfunction calls the callback function given in the parameter proc for every item which is found in the directory specified by filename and all directories below. The function follows symbolic links if necessary but does not process an item twice. If filename names no directory this item is the only object reported by calling the callback function.
The filename given to the callback function is constructed by taking the filename parameter and appending the names of all passed directories and then the local file name. So the callback function can use this parameter to access the file. Before the callback function is called
statfor this file and passes the information up to the callback function. If this
statcall was not successful the failure is indicated by setting the flag argument of the callback function to
invalid-stat. Otherwise the flag is set according to the description given in the description of
The callback function is expected to return non-#f to indicate that no error occurred and the processing should be continued. If an error occurred in the callback function or the call to
ftwshall return immediately the callback function can return #f. This is the only correct way to stop the function.
The return value of the
ftwfunction is #t if all callback function calls returned #t and all actions performed by the
ftwsucceeded. If some function call failed (other than calling
staton an item) the function returns #f. If a callback function returns a value other than #t this value is returned as the return value of
Do a new-style filesystem tree walk starting at filename using proc. Various optional control-flags alter the default behavior.
nftwfunctions works like the
ftwfunctions. It calls the callback function proc for all items it finds in the directory filename and below.
The differences are that for one the callback function is of a different type. It takes also
levelparameters as described above.
The second difference is that
nftwtakes additional optional arguments which are zero or more of the following symbols:
- While traversing the directory symbolic links are not followed. I.e., if this flag is given symbolic links are reported using the
symlinkvalue for the type parameter to the callback function. Please note that if this flag is used the appearance of
symlinkin a callback function does not mean the referenced file does not exist. To indicate this the extra value
- The callback function is only called for items which are on the same mounted filesystem as the directory given as the filename parameter to
- If this flag is given the current working directory is changed to the directory containing the reported object before the callback function is called.
- If this option is given the function visits first all files and subdirectories before the callback function is called for the directory itself (depth-first processing). This also means the type flag given to the callback function is
The return value is computed in the same way as for
nftwreturns #t if no failure occurred in
nftwand all callback function call return values are also #t. For internal errors such as memory problems the error
ftw-erroris thrown. If the return value of a callback invocation is not #t this very same value is returned.