Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages
Iterator(3) User Contributed Perl Documentation Iterator(3)

File::Iterator - an object-oriented Perl module for iterating across files in a directory tree.

        use File::Iterator;
        $it = new File::Iterator(
                DIR     => '/etc',
                RECURSE => 0,
                FILTER  => sub { $_[0] =~ /\.cf$/ },
        while ($file = $it->next()) {
                # do stuff with $file

File::Iterator wraps a simple iteration interface around the files in a directory or directory tree. It builds a list of filenames, and maintains a cursor that points to one filename in the list. The user can work through the filenames sequentially by repeatedly doing stuff with the next filename that the cursor points to until their are no filenames left.

new( [ DIR => '$somedir' ] [, RECURSE => 0 ] [, FILTER => sub { ... } ] [, RETURNDIRS => 1] [, FOLLOWSYMLINKS => 1] )
The constructor for a File::Iterator object. The starting directory for the iteration is specified as shown. If DIR is not specified, the current directory is used.
By default, File::Iterator works recursively, and will therefore list all files in the starting directory and all its subdirectories. To use File::Iterator non-recursively, set the RECURSE option to 0. Note that the module does not follow symbolic links to directories. To override this behaviour, set the FOLLOWSYMLINKS option to 1. Be careful though, as this can lead to endless iteration if a link points to a directory higher up its own directory tree.
Use the FILTER option to pass in a reference to a function to filter the files. Such a function will be passed the filename (including path) to filter and should return true if you are interested in that file.
        sub config {
                my $filename = shift;
                return 1 if $filename =~ /\.(cf|conf)$/; # only look for config files
        $it = new File::Iterator(
                DIR => "/etc",
                FILTER => \&config
        # or simply...
        $it = new File::Iterator(
                DIR => "/etc",
                FILTER => sub { $_[0] =~ /\.(cf|conf)$/ }
Don't try to use the FILTER option to exclude subdirectories. This won't work:
        $it = new File::Iterator(
                DIR => "/etc",
                FILTER => sub { ! -d $_[0] }
Set the RECURSE option to 0 instead.
By default, the module only returns filenames and not directory names (although the module will still search subdirectories if the RECURSE option is on). To return directory names as well as filenames, set the RETURNDIRS option to 1.

Returns the name of the next file (including the path) then advances the cursor, or returns undef if there are no more files to process. Note that because next() advances the cursor, the following code will produce erroneous results, because the two calls to next() return different values:
        while ($it->next()) {
                push @textfiles, $it->next() if -T $it->next();
What you wanted to write was:
        while ($file = $it->next()) {
                push @textfiles, $file if -T $file;
Resets the iterator so that the next call to next() returns the first file in the list.

Marius Feraru provided valuable input in the module's early days.
Jamie O'Shaughnessy < > was responsible for the reworking of the FILTER option in 0.07 and gave some good advice about avoiding unnecessary recursion.
Paul Hoffman spotted that the test on $^O in versions pre-0.08 would recognise Darwin as a Windows OS. He probably saved my life. :-)

Copyright 2002 Simon Whitaker <>
2007-03-14 perl v5.28.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.