setpwent#

Rewind the password-database iterator so the next 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, 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 to release the database when done.

Synopsis#

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, setpwent, and 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:

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:

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 when done, whether or not you called setpwent:

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.