(use-modules (ice-9 ftw))

— Function: ftw startname proc ['hash-size n]

Walk the filesystem tree descending from startname, calling proc for each file and directory.

Hard links and symbolic links are followed. A file or directory is reported to proc only once, and skipped if seen again in another place. One consequence of this is that ftw is safe against circularly linked directory structures.

Each proc call is (proc filename statinfo flag) and it should return #t to continue, or any other value to stop.

filename is the item visited, being startname plus a further path and the name of the item. statinfo is the return from stat (see File System) on filename. flag is one of the following symbols,

regular

filename is a file, this includes special files like devices, named pipes, etc.

directory

filename is a directory.

invalid-stat

An error occurred when calling stat, so nothing is known. statinfo is #f in this case.

directory-not-readable

filename is a directory, but one which cannot be read and hence won't be recursed into.

symlink

filename is a dangling symbolic link. Symbolic links are normally followed and their target reported, the link itself is reported if the target does not exist.

The return value from ftw is #t if it ran to completion, or otherwise the non-#t value from proc which caused the stop.

Optional argument symbol hash-size and an integer can be given to set the size of the hash table used to track items already visited. (see Hash Table Reference)

In the current implementation, returning non-#t from proc is the only valid way to terminate ftw. proc must not use throw or similar to escape.

— Function: nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]

Walk the filesystem tree starting at startname, calling proc for each file and directory. nftw has extra features over the basic ftw described above.

Like ftw, hard links and symbolic links are followed. A file or directory is reported to proc only once, and skipped if seen again in another place. One consequence of this is that nftw is safe against circular linked directory structures.

Each proc call is (proc filename statinfo flag base level) and it should return #t to continue, or any other value to stop.

filename is the item visited, being startname plus a further path and the name of the item. statinfo is the return from stat on filename (see File System). base is an integer offset into filename which is where the basename for this item begins. level is an integer giving the directory nesting level, starting from 0 for the contents of startname (or that item itself if it's a file). flag is one of the following symbols,

regular

filename is a file, including special files like devices, named pipes, etc.

directory

filename is a directory.

directory-processed

filename is a directory, and its contents have all been visited. This flag is given instead of directory when the depth option below is used.

invalid-stat

An error occurred when applying stat to filename, so nothing is known about it. statinfo is #f in this case.

directory-not-readable

filename is a directory, but one which cannot be read and hence won't be recursed into.

stale-symlink

filename is a dangling symbolic link. Links are normally followed and their target reported, the link itself is reported if its target does not exist.

symlink

When the physical option described below is used, this indicates filename is a symbolic link whose target exists (and is not being followed).

The following optional arguments can be given to modify the way nftw works. Each is passed as a symbol (and hash-size takes a following integer value).

chdir

Change to the directory containing the item before calling proc. When nftw returns the original current directory is restored.

Under this option, generally the base parameter to each proc call should be used to pick out the base part of the filename. The filename is still a path but with a changed directory it won't be valid (unless the startname directory was absolute).

depth

Visit files “depth first”, meaning proc is called for the contents of each directory before it's called for the directory itself. Normally a directory is reported first, then its contents.

Under this option, the flag to proc for a directory is directory-processed instead of directory.

hash-size n

Set the size of the hash table used to track items already visited. (see Hash Table Reference)

mount

Don't cross a mount point, meaning only visit items on the same filesystem as startname (ie. the same stat:dev).

physical

Don't follow symbolic links, instead report them to proc as symlink. Dangling links (those whose target doesn't exist) are still reported as stale-symlink.

The return value from nftw is #t if it ran to completion, or otherwise the non-#t value from proc which caused the stop.

In the current implementation, returning non-#t from proc is the only valid way to terminate ftw. proc must not use throw or similar to escape.