---
name: rewinddir
signature: 'rewinddir DIRHANDLE'
since: 5.0
status: documented
categories: ["I/O"]
---

```{index} single: rewinddir; Perl built-in
```

*[I/O](../perlfunc-by-category)*

# 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`](readdir) call
returns the first entry again. It is the directory-handle counterpart
to [`seek`](seek) on a file handle: no re-open, no re-scan of the
parent directory — just a position reset on the open handle.

## Synopsis

```perl
rewinddir DIRHANDLE
```

## What you get back

`1` on success, `0` on failure (with [`$!`](../perlvar) 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:

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

## Typical use

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

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

```perl
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 [`$!`](../perlvar). 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`](opendir) returned. The underlying `rewinddir(3)` operates on
  the kernel's cached directory stream; whether a rewound scan
  observes concurrent [`mkdir`](mkdir), [`unlink`](unlink), or [`rename`](rename) in the same
  directory is filesystem- and OS-dependent. If you need a fresh
  snapshot, [`closedir`](closedir) and [`opendir`](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`](telldir) / [`seekdir`](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.

## See also

- [`opendir`](opendir) — open a directory and obtain the handle that
  `rewinddir` operates on
- [`readdir`](readdir) — read the next entry; resumes from wherever
  `rewinddir` left the stream (the beginning)
- [`closedir`](closedir) — release the handle; pair with
  [`opendir`](opendir) when a rewound scan is not enough and you need a
  fresh snapshot of the directory
- [`telldir`](telldir) — record the current position so you can return
  to it later
- [`seekdir`](seekdir) — restore a position previously captured by
  [`telldir`](telldir); `rewinddir $dh` is equivalent to `seekdir $dh, 0`
  on conforming systems, but `rewinddir` is the portable spelling