From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Kevin Ryde Newsgroups: gmane.lisp.guile.devel Subject: doc ice-9 ftw Date: Mon, 08 Sep 2003 09:07:46 +1000 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: <87vfs4ryd9.fsf@zip.com.au> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1062979624 8313 80.91.224.253 (8 Sep 2003 00:07:04 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 8 Sep 2003 00:07:04 +0000 (UTC) Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Mon Sep 08 02:07:01 2003 Return-path: Original-Received: from monty-python.gnu.org ([199.232.76.173]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 19w9Yb-0003pU-01 for ; Mon, 08 Sep 2003 02:07:01 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.22) id 19w9XZ-0004xK-KM for guile-devel@m.gmane.org; Sun, 07 Sep 2003 20:05:57 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.22) id 19w9QK-00080Y-Gk for guile-devel@gnu.org; Sun, 07 Sep 2003 19:58:28 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.22) id 19w9Pl-0007BN-Cc for guile-devel@gnu.org; Sun, 07 Sep 2003 19:57:54 -0400 Original-Received: from [199.232.41.8] (helo=mx20.gnu.org) by monty-python.gnu.org with esmtp (TLSv1:DES-CBC3-SHA:168) (Exim 4.22) id 19w9PX-0004ZA-DP for guile-devel@gnu.org; Sun, 07 Sep 2003 19:57:39 -0400 Original-Received: from [61.8.0.36] (helo=snoopy.pacific.net.au) by mx20.gnu.org with esmtp (Exim 4.22) id 19w9PK-0006M8-Qr for guile-devel@gnu.org; Sun, 07 Sep 2003 19:57:27 -0400 Original-Received: from mongrel.pacific.net.au (mongrel.pacific.net.au [61.8.0.107]) by snoopy.pacific.net.au (8.12.3/8.12.3/Debian-6.4) with ESMTP id h87N7tBt017663 for ; Mon, 8 Sep 2003 09:07:55 +1000 Original-Received: from localhost (ppp81.dyn228.pacific.net.au [203.143.228.81]) by mongrel.pacific.net.au (8.12.3/8.12.3/Debian-6.4) with ESMTP id h87N6MBC026864 for ; Mon, 8 Sep 2003 09:06:23 +1000 Original-Received: from gg by localhost with local (Exim 3.35 #1 (Debian)) id 19w8dH-0000VS-00; Mon, 08 Sep 2003 09:07:47 +1000 Original-To: guile-devel@gnu.org Mail-Copies-To: never User-Agent: Gnus/5.1003 (Gnus v5.10.3) Emacs/21.3 (gnu/linux) X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.2 Precedence: list List-Id: Developers list for Guile, the GNU extensibility library List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.lisp.guile.devel:2761 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:2761 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