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: |