doc ice-9 ftw

[Kevin Ryde <user42@zip.com.au>]

This is some words for the manual about the ice-9 ftw module, to go
under "Part V: Guile Modules".  Mostly put together from the comments
in ftw.scm.

The comments say ftw-error is thrown by nftw, but it looks like the
code doesn't do that, so I left it out of the description.

The comments also say #f is returned if some procedure call other than
stat fails, but that doesn't look right either, so I left it out.
Presumably it won't arise unless there's something badly wrong with
the system anyway.



File Tree Walk
==============

The functions in this section traverse a tree of files and directories,
in a fashion similar to the C `ftw' and `nftw' routines (*note Working
with Directory Trees: (libc)Working with Directory Trees.).

     (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, 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 `ftw' is safe
     against circular 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 name of the item.  STATINFO is the return from `stat' on
     FILENAME (*note File System::).  FLAG is one of the following
     symbols,

    `regular'
          FILENAME is a file, including special files like devices,
          sockets, etc.

    `directory'
          FILENAME is a directory.

    `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 only reported if the target does not exist.

     The return value from `ftw' is `#t' if it ran to completion, or
     the non-`#t' value from PROC which caused a stop.

     An optional parameter which is the symbol `hash-size' and an
     integer N can be given to set the size of the hash table used to
     track items already visited.  A prime number somewhat bigger than
     the expected number of items would be a good choice.

     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 name of the item.  STATINFO is the return from `stat' on
     FILENAME (*note File System::).  BASENAME it the item name without
     any path.  LEVEL is an integer giving the 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,
          sockets, 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 only reported if the target does not exist.

          Under the `physical' option described below, `symlink' is
          instead given for symbolic links whose target exists.

    `stale-symlink'
          FILENAME is a dangling symbolic link, meaning its target does
          not exist.  This is only given under the `physical' option
          described below, normally `symlink' is used for a dangling
          link.

     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 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 is `directory-processed'
          instead of `directory'.

    `hash-size' N
          Set the size of the hash table used to track items already
          visited.  A prime somewhat bigger than the expected number of
          items would be a good choice.

    `mount'
          Don't cross a mount point, meaning only visit items on the
          same filesystem as STARTNAME.

    `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
     the non-`#t' value from PROC which caused a 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.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel