---
name: setpwent
signature: 'setpwent'
since: 5.0
status: documented
categories: ["User and group info"]
---

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

*[User and group info](../perlfunc-by-category)*

# setpwent

Rewind the password-database iterator so the next [`getpwent`](getpwent) call returns the first entry again.

`setpwent` wraps the C library's `setpwent(3)` call. It (re)opens the
system password database and resets the iteration cursor used by
[`getpwent`](getpwent), so a subsequent loop starts from the top. Use it when
you want to iterate the password database more than once in the same
process, or when you want to restart iteration after a partial walk.
Pair it with [`endpwent`](endpwent) to release the database when done.

## Synopsis

```perl
setpwent;
setpwent();
```

## What you get back

Return value is **not useful** and must not be relied on. On most
systems the underlying `setpwent(3)` has a `void` return; Perl yields a
single meaningless true value. Call `setpwent` for its side effect,
never for its value.

## Global state it touches

- The per-process cursor shared by [`getpwent`](getpwent),
  [`setpwent`](setpwent), and [`endpwent`](endpwent). This cursor is
  owned by the C library, not by Perl — forking a child inherits
  an open database handle, and two threads iterating concurrently
  will interleave and lose records.
- `$!` is **not** set by `setpwent`; errors from the underlying
  `setpwent(3)` are swallowed by the platform.

## Examples

Iterate the password database twice in the same program:

```perl
while (my @pw = getpwent) {
    print "$pw[0]\n";           # first pass: every login name
}
setpwent;
while (my @pw = getpwent) {
    print "uid=$pw[2]\n";       # second pass: every uid
}
endpwent;
```

Restart iteration after an early exit:

```perl
while (my @pw = getpwent) {
    last if $pw[0] eq 'root';
}
setpwent;                       # rewind so the next walk sees root again
```

Typical cleanup pattern — always call [`endpwent`](endpwent) when done,
whether or not you called `setpwent`:

```perl
setpwent;
while (my ($name, undef, $uid) = getpwent) {
    print "$name => $uid\n" if $uid >= 1000;
}
endpwent;
```

## Edge cases

- **No arguments.** `setpwent` takes no arguments. Writing `setpwent
  $x` is a syntax trap: like other list operators, it will try to
  consume `$x` as the first element of a list.
- **Before any `getpwent` call.** Safe. `setpwent` opens the
  database if it is not already open, so it doubles as an explicit
  "open" call.
- **After `endpwent`.** Safe. The database is reopened.
- **Forked children.** Each process has its own iteration cursor
  after the fork, but the underlying file descriptor may be shared;
  interleaved reads from parent and child produce missing or
  duplicated records. Call `setpwent` in the child to get a clean
  iterator.
- **Threads.** `getpwent` iteration is per-process, not per-thread.
  Concurrent iteration from multiple threads loses records. Upstream
  Perl substitutes thread-safe `_r` variants for `getpwnam` and
  `getpwuid` when the platform provides them; there is no
  `setpwent_r`, and this function remains process-global.
- **NSS-backed databases.** On systems where `/etc/nsswitch.conf`
  routes `passwd` through LDAP, SSSD, or similar, `setpwent` may
  block on a network round-trip. Do not call it from signal handlers
  or latency-critical code paths.
- **Shadow passwords.** `setpwent` does not affect the shadow-password
  iterator (if any); it only resets the regular `passwd` walk.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`getpwent`](getpwent) — fetch the next entry; the function
  `setpwent` exists to rewind
- [`endpwent`](endpwent) — release the password database when you
  are finished iterating
- [`getpwnam`](getpwnam) — direct lookup by login name; does not
  interact with the iteration cursor
- [`getpwuid`](getpwuid) — direct lookup by uid; does not interact
  with the iteration cursor
- [`setgrent`](setgrent) — the same rewind operation for the group
  database
- `User::pwent` — object-oriented wrapper that returns named-field
  objects instead of 10-element lists