(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.

Hard links and symbolic links are followed, but 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 basename 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). basename it the item name without any path. 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, this includes 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.

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.

Under the physical option described below, symlink is instead given for symbolic links whose target does exist.

stale-symlink

Under the physical option described below, this indicates filename is a dangling symbolic link, meaning its target does not exist. Without the physical option plain symlink indicates this.

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 basename parameter should be used to access the item in each proc call. The filename parameter still has a path as normal and this will only be valid if 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, and report dangling links 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.