* doc ice-9 ftw
@ 2003-09-07 23:07 Kevin Ryde
2003-11-03 0:56 ` Kevin Ryde
0 siblings, 1 reply; 2+ messages in thread
From: Kevin Ryde @ 2003-09-07 23:07 UTC (permalink / raw)
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
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2003-11-03 0:56 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2003-09-07 23:07 doc ice-9 ftw Kevin Ryde
2003-11-03 0:56 ` Kevin Ryde
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).