sethostent#

Open or rewind the hosts database for iteration.

sethostent prepares the system hosts database (typically /etc/hosts plus any name-service sources configured by the platform) for a sequential walk with gethostent, and rewinds the cursor if iteration is already in progress. STAYOPEN is a flag passed through to the underlying C sethostent(3) call: a true value asks the resolver to keep the database open across subsequent gethostby* lookups, which on some systems avoids reopening the file or reconnecting to the name service for every query.

Synopsis#

sethostent STAYOPEN
sethostent 0
sethostent 1

What you get back#

Returns nothing useful. The call is invoked for its side effect of priming the iterator; ignore the return value.

Global state it touches#

Mutates process-global resolver state maintained by the C library: the hosts-database file descriptor or name-service handle, and the per-process iteration cursor read by gethostent. Two pieces of code in the same process walking the hosts database simultaneously will step on each other — there is one cursor, not one per caller. On failure $! is set by the underlying system call; there is no h_errno-style reporting for this function.

Examples#

Walk every entry in the hosts database:

sethostent(0);
while (my ($name, $aliases, $addrtype, $length, @addrs)
        = gethostent()) {
    print "$name\n";
}
endhostent();

Ask the resolver to keep the database open while a batch of name-to-address lookups runs, then close it:

sethostent(1);
for my $host (@hosts) {
    my $packed = gethostbyname($host);
    # ...
}
endhostent();

Rewind an in-progress iteration to start over from the first entry:

sethostent(0);
my $first = (gethostent())[0];
sethostent(0);                      # back to the top
my $first_again = (gethostent())[0];

Edge cases#

STAYOPEN is mandatory syntax, not mandatory semantics. The argument must be present — sethostent; is a compile error — but many platforms ignore the flag and always keep the database open for the duration of the iteration. Pass 0 when you have no preference.
Not every platform has a meaningful hosts iterator. On systems where the hosts database is served exclusively by DNS or a name service that does not expose enumeration, gethostent returns the empty list on the first call regardless of sethostent. The call itself still succeeds.
Thread safety. The resolver cursor is per-process, not per-thread. Two threads iterating concurrently will interleave records and neither will see the full list. Upstream Perl substitutes *_r variants for point lookups like gethostbyname where available; there is no thread-safe variant of the iterator.
Interaction with gethostby* caches. On some libc implementations a sethostent(1) issued before a burst of gethostbyname / gethostbyaddr calls keeps the backing file open between queries; on others it has no effect. Measure before relying on it as an optimisation.
Pair with endhostent. Leaving the database open after iteration can leak a file descriptor or a resolver connection. Always close the walk with endhostent.

Differences from upstream#

Fully compatible with upstream Perl 5.42.