rewinddir#

Reset a directory handle to the start of its listing.

rewinddir sets the current position of DIRHANDLE back to the beginning of the directory, so that the next readdir call returns the first entry again. It is the directory-handle counterpart to seek on a file handle: no re-open, no re-scan of the parent directory — just a position reset on the open handle.

Synopsis#

rewinddir DIRHANDLE

What you get back#

1 on success, 0 on failure (with $! set). Failure is rare in practice — the usual cause is a handle that was never opened or has already been closed. Check the return value if you care about either case:

rewinddir $dh
    or die "rewinddir failed: $!";

Typical use#

You have already walked a directory with readdir and want to walk it again without paying for another opendir:

opendir my $dh, $path or die "opendir $path: $!";

my @all = readdir $dh;          # first pass: collect everything

rewinddir $dh;                  # back to the top

while (my $entry = readdir $dh) {   # second pass: process one by one
    next if $entry =~ /^\.\.?\z/;
    process("$path/$entry");
}

closedir $dh;

A second common pattern is reusing one handle across several scans with different filters, where re-opening would be wasteful or would race against concurrent directory changes:

opendir my $dh, $path or die $!;

my @perl = grep { /\.p[lm]\z/ } readdir $dh;
rewinddir $dh;
my @text = grep { /\.txt\z/  } readdir $dh;

closedir $dh;

Edge cases#

Unopened or closed handle: returns 0 and sets $!. Under use warnings you also get a rewinddir() attempted on invalid dirhandle warning.
Mid-scan directory changes: rewinddir is not guaranteed to surface entries created (or hide entries removed) after opendir returned. The underlying rewinddir(3) operates on the kernel’s cached directory stream; whether a rewound scan observes concurrent mkdir, unlink, or rename in the same directory is filesystem- and OS-dependent. If you need a fresh snapshot, closedir and opendir again.
Not a seek to an arbitrary position: rewinddir resets to the start and nothing else. To return to a remembered mid-directory position use telldir / seekdir instead.
Entry order is unspecified: rewinding replays the same stream the kernel gave you, but the order of entries is whatever the filesystem produces — not sorted, not creation order, not the order you saw last time on a different handle. Sort explicitly if order matters.
Portability: rewinddir is a POSIX call. On platforms without a working rewinddir(3) it may be implemented by closing and re-opening the directory; see L<perlport/rewinddir> for the historical list. On Linux (the platform pperl targets) this is not a concern.

Differences from upstream#

Fully compatible with upstream Perl 5.42.