(use-modules (ice-9 ftw))

— callback-type: ftw-callback filename statinfo flag

Type for callback functions given to the ftw function. The first parameter is a filename, the second parameter is the vector value as returned by calling stat on filename.

The last parameter is a symbol giving more information about filename. It can have one of the following values:

regular

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.

directory

The current item is a directory.

invalid-stat

The stat call to fill the object pointed to by the second parameter failed and so the information is invalid.

directory-not-readable

The item is a directory which cannot be read.

symlink

The item is a symbolic link. Since symbolic links are normally followed seeing this value in a ftw callback function means the referenced file does not exist. The situation for nftw is different.

— callback-type: nftw-callback filename statinfo flag base level

The first three arguments have the same as for the ftw-callback type. A difference is that for the third argument some additional values are defined to allow finer differentiation:

directory-processed

The current item is a directory and all subdirectories have already been visited and reported. This flag is returned instead of directory if the depth flag is given to nftw (see below).

stale-symlink

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.

base

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 chdir flag for nftw was set since then the current directory is the one the current item is found in.

level

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.

— Scheme Procedure: ftw filename proc [options...]

Do a filesystem tree walk starting at filename using proc.

The ftw function 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 ftw calls stat for this file and passes the information up to the callback function. If this stat call 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 ftw-callback above.

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 ftw shall return immediately the callback function can return #f. This is the only correct way to stop the function.

The return value of the ftw function is #t if all callback function calls returned #t and all actions performed by the ftw succeeded. If some function call failed (other than calling stat on 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 ftw.

— Scheme Procedure: nftw filename proc [control-flags...]

Do a new-style filesystem tree walk starting at filename using proc. Various optional control-flags alter the default behavior.

The nftw functions works like the ftw functions. 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 base and level parameters as described above.

The second difference is that nftw takes additional optional arguments which are zero or more of the following symbols:

physical

While traversing the directory symbolic links are not followed. I.e., if this flag is given symbolic links are reported using the symlink value for the type parameter to the callback function. Please note that if this flag is used the appearance of symlink in a callback function does not mean the referenced file does not exist. To indicate this the extra value stale-symlink exists.

mount

The callback function is only called for items which are on the same mounted filesystem as the directory given as the filename parameter to nftw.

chdir

If this flag is given the current working directory is changed to the directory containing the reported object before the callback function is called.

depth

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 directory-processed and not directory.

The return value is computed in the same way as for ftw. nftw returns #t if no failure occurred in nftw and all callback function call return values are also #t. For internal errors such as memory problems the error ftw-error is thrown. If the return value of a callback invocation is not #t this very same value is returned.