/[guile]/guile/guile-core/doc/ref/misc-modules.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/misc-modules.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.5 by ttn, Tue Jan 8 08:29:00 2002 UTC revision 1.6 by kryde, Mon Nov 3 00:52:32 2003 UTC
# Line 421  Test whether obj is a compiled regular e Line 421  Test whether obj is a compiled regular e
421  @end deffn  @end deffn
422    
423    
424    @node File Tree Walk
425    @chapter File Tree Walk
426    @cindex file tree walk
427    
428    The functions in this section traverse a tree of files and
429    directories, in a fashion similar to the C @code{ftw} and @code{nftw}
430    routines (@pxref{Working with Directory Trees,,, libc, GNU C Library
431    Reference Manual}).
432    
433    @example
434    (use-modules (ice-9 ftw))
435    @end example
436    @sp 1
437    
438    @defun ftw startname proc ['hash-size n]
439    Walk the filesystem tree descending from @var{startname}, calling
440    @var{proc} for each file and directory.
441    
442    Hard links and symbolic links are followed.  A file or directory is
443    reported to @var{proc} only once, and skipped if seen again in another
444    place.  One consequence of this is that @code{ftw} is safe against
445    circularly linked directory structures.
446    
447    Each @var{proc} call is @code{(@var{proc} filename statinfo flag)} and
448    it should return @code{#t} to continue, or any other value to stop.
449    
450    @var{filename} is the item visited, being @var{startname} plus a
451    further path and the name of the item.  @var{statinfo} is the return
452    from @code{stat} (@pxref{File System}) on @var{filename}.  @var{flag}
453    is one of the following symbols,
454    
455    @table @code
456    @item regular
457    @var{filename} is a file, this includes special files like devices,
458    named pipes, etc.
459    
460    @item directory
461    @var{filename} is a directory.
462    
463    @item invalid-stat
464    An error occurred when calling @code{stat}, so nothing is known.
465    @var{statinfo} is @code{#f} in this case.
466    
467    @item directory-not-readable
468    @var{filename} is a directory, but one which cannot be read and hence
469    won't be recursed into.
470    
471    @item symlink
472    @var{filename} is a dangling symbolic link.  Symbolic links are
473    normally followed and their target reported, the link itself is
474    reported if the target does not exist.
475    @end table
476    
477    The return value from @code{ftw} is @code{#t} if it ran to completion,
478    or otherwise the non-@code{#t} value from @var{proc} which caused the
479    stop.
480    
481    Optional argument symbol @code{hash-size} and an integer can be given
482    to set the size of the hash table used to track items already visited.
483    (@pxref{Hash Table Reference})
484    
485    @c  Actually, it's probably safe to escape from ftw, just need to
486    @c  check it.
487    @c
488    In the current implementation, returning non-@code{#t} from @var{proc}
489    is the only valid way to terminate @code{ftw}.  @var{proc} must not
490    use @code{throw} or similar to escape.
491    @end defun
492    
493    
494    @defun nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]
495    Walk the filesystem tree starting at @var{startname}, calling
496    @var{proc} for each file and directory.  @code{nftw} has extra
497    features over the basic @code{ftw} described above.
498    
499    Hard links and symbolic links are followed, but a file or directory is
500    reported to @var{proc} only once, and skipped if seen again in another
501    place.  One consequence of this is that @code{nftw} is safe against
502    circular linked directory structures.
503    
504    Each @var{proc} call is @code{(@var{proc} filename statinfo flag
505    basename level)} and it should return @code{#t} to continue, or any
506    other value to stop.
507    
508    @var{filename} is the item visited, being @var{startname} plus a
509    further path and the name of the item.  @var{statinfo} is the return
510    from @code{stat} on @var{filename} (@pxref{File System}).
511    @var{basename} it the item name without any path.  @var{level} is an
512    integer giving the directory nesting level, starting from 0 for the
513    contents of @var{startname} (or that item itself if it's a file).
514    @var{flag} is one of the following symbols,
515    
516    @table @code
517    @item regular
518    @var{filename} is a file, this includes special files like devices,
519    named pipes, etc.
520    
521    @item directory
522    @var{filename} is a directory.
523    
524    @item directory-processed
525    @var{filename} is a directory, and its contents have all been visited.
526    This flag is given instead of @code{directory} when the @code{depth}
527    option below is used.
528    
529    @item invalid-stat
530    An error occurred when applying @code{stat} to @var{filename}, so
531    nothing is known about it.  @var{statinfo} is @code{#f} in this case.
532    
533    @item directory-not-readable
534    @var{filename} is a directory, but one which cannot be read and hence
535    won't be recursed into.
536    
537    @item symlink
538    @var{filename} is a dangling symbolic link.  Symbolic links are
539    normally followed and their target reported, the link itself is
540    reported if the target does not exist.
541    
542    Under the @code{physical} option described below, @code{symlink} is
543    instead given for symbolic links whose target does exist.
544    
545    @item stale-symlink
546    Under the @code{physical} option described below, this indicates
547    @var{filename} is a dangling symbolic link, meaning its target does
548    not exist.  Without the @code{physical} option plain @code{symlink}
549    indicates this.
550    @end table
551    
552    The following optional arguments can be given to modify the way
553    @code{nftw} works.  Each is passed as a symbol (and @code{hash-size}
554    takes a following integer value).
555    
556    @table @asis
557    @item @code{chdir}
558    Change to the directory containing the item before calling @var{proc}.
559    When @code{nftw} returns the original current directory is restored.
560    
561    Under this option, generally the @var{basename} parameter should be
562    used to access the item in each @var{proc} call.  The @var{filename}
563    parameter still has a path as normal and this will only be valid if
564    the @var{startname} directory was absolute.
565    
566    @item @code{depth}
567    Visit files ``depth first'', meaning @var{proc} is called for the
568    contents of each directory before it's called for the directory
569    itself.  Normally a directory is reported first, then its contents.
570    
571    Under this option, the @var{flag} to @var{proc} for a directory is
572    @code{directory-processed} instead of @code{directory}.
573    
574    @item @code{hash-size @var{n}}
575    Set the size of the hash table used to track items already visited.
576    (@pxref{Hash Table Reference})
577    
578    @item @code{mount}
579    Don't cross a mount point, meaning only visit items on the same
580    filesystem as @var{startname}.  (Ie.@: the same @code{stat:dev}.)
581    
582    @item @code{physical}
583    Don't follow symbolic links, instead report them to @var{proc} as
584    @code{symlink}, and report dangling links as @code{stale-symlink}.
585    @end table
586    
587    The return value from @code{nftw} is @code{#t} if it ran to
588    completion, or otherwise the non-@code{#t} value from @var{proc} which
589    caused the stop.
590    
591    @c  For reference, one reason not to esacpe is that the current
592    @c  directory is not saved and restored with dynamic-wind.  Maybe
593    @c  changing that would be enough to allow escaping.
594    @c
595    In the current implementation, returning non-@code{#t} from @var{proc}
596    is the only valid way to terminate @code{ftw}.  @var{proc} must not
597    use @code{throw} or similar to escape.
598    @end defun
599    
600    
601  @c Local Variables:  @c Local Variables:
602  @c TeX-master: "guile.texi"  @c TeX-master: "guile.texi"
603  @c End:  @c End:

Legend:
Removed from v.1.5  
changed lines
  Added in v.1.6

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26