---
name: sethostent
signature: 'sethostent STAYOPEN'
since: 5.0
status: documented
categories: ["Network info"]
---

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

*[Network info](../perlfunc-by-category)*

# 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`](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

```perl
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`](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 [`$!`](../perlvar)
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:

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

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

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

```perl
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`](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`](endhostent).** Leaving the database
  open after iteration can leak a file descriptor or a resolver
  connection. Always close the walk with [`endhostent`](endhostent).

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`gethostent`](gethostent) — read the next entry from the hosts
  database after `sethostent` has primed the cursor
- [`endhostent`](endhostent) — close the database and release
  resolver state when iteration is done
- [`gethostbyname`](gethostbyname) — point lookup by name; benefits
  from `sethostent(1)` on platforms that honour it
- [`gethostbyaddr`](gethostbyaddr) — point lookup by address; same
  caveat as `gethostbyname`
- [`setnetent`](setnetent) — the networks-database counterpart,
  same iteration pattern
- [`setservent`](setservent) — the services-database counterpart