---
name: getnetbyname
signature: 'getnetbyname NAME'
since: 5.0
status: documented
categories: ["Network info"]
---

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

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

# getnetbyname

Look up a network record by name.

`getnetbyname` resolves a symbolic network name (as listed in the
system's networks database, typically `/etc/networks`) to its numeric
network address by calling the C `getnetbyname(3)` routine. The
scalar-context form returns the network number; the list-context form
exposes the full record: canonical name, aliases, address family, and
network number.

## Synopsis

```perl
my $net = getnetbyname $name;
my ($name, $aliases, $addrtype, $net) = getnetbyname $name;
```

## What you get back

**Scalar context** — the network number as a plain integer, or
[`undef`](undef) if the name is not in the networks database. This is
the host-byte-order network portion of an IPv4 address, not a packed
string. For the class-C network `192.168.0`, the returned value is
`12625920` (that is, `0xC0A800`).

**List context** — a four-element list mirroring the C `struct netent`:

- `$name` — the canonical network name.
- `$aliases` — a space-separated string of alternate names.
- `$addrtype` — the address family, typically `AF_INET` (`2`).
- `$net` — the network number, same integer as the scalar-context form.

On lookup failure in list context, the return is the empty list.

## Global state it touches

- The networks database iteration cursor shared with
  [`getnetent`](getnetent), [`setnetent`](setnetent), and
  [`endnetent`](endnetent). A call to `getnetbyname` may reset a
  cursor left open by `getnetent`.

## Examples

Scalar form — look up a named network and print it as dotted-quad:

```perl
my $net = getnetbyname("loopback");
defined $net or die "no networks entry for loopback";
printf "%d.%d.%d.%d\n",
    ($net >> 24) & 0xFF, ($net >> 16) & 0xFF,
    ($net >> 8)  & 0xFF,  $net        & 0xFF;   # 127.0.0.0
```

List form — every field of the record:

```perl
my ($name, $aliases, $type, $net) = getnetbyname("loopback");
print "name=$name aliases=$aliases type=$type net=$net\n";
```

Round-trip against [`getnetbyaddr`](getnetbyaddr) — name to number,
then number back to name:

```perl
use Socket qw(AF_INET);
my $net  = getnetbyname("loopback");
my $back = getnetbyaddr($net, AF_INET);
print "$back\n";                        # loopback
```

By-name interface via the `Net::netent` override — accessor methods
instead of positional unpacking:

```perl
use Net::netent;
my $n = getnetbyname("loopback");
print $n->name, " ", $n->net, "\n";
```

Guard against a missing entry — a name that is not in the database
returns [`undef`](undef), not zero:

```perl
my $net = getnetbyname("no-such-network");
if (defined $net) {
    print "found: $net\n";
} else {
    print "not in /etc/networks\n";
}
```

## Edge cases

- **Check for [`undef`](undef), not falsehood.** A network number of
  `0` is a legal (if unusual) record; treating the return value as a
  boolean will misread that case as failure. Always test with
  [`defined`](defined).
- **The returned number is host-byte-order, not a packed string.**
  Unlike [`gethostbyname`](gethostbyname), which returns a four-byte
  packed address, `getnetbyname` returns a plain integer. Do not pass
  it to `Socket::inet_ntoa` — that function expects a packed string
  and will produce garbage on an integer.
- **Aliases are one scalar, not a list.** `$aliases` in the list form
  is a single space-separated string. Split on whitespace if you need
  a list.
- **Networks are typically class-boundary numbers.** The entries in
  `/etc/networks` are traditionally stored as the network portion only
  — `127` for loopback, `10` for the private class-A, not full
  four-octet addresses. On modern CIDR-routed networks the utility of
  this database is limited; most deployments keep only a handful of
  legacy entries.
- **No DNS fallback.** Unlike [`gethostbyname`](gethostbyname), this
  call consults only the local networks database. There is no
  equivalent of DNS for network names.
- **Empty list vs. undef.** Scalar context returns [`undef`](undef) on
  failure; list context returns the empty list. The two are not
  interchangeable — code written for one context will misbehave in
  the other.
- **Thread safety.** The underlying C routine keeps per-process static
  state for the networks cursor. Concurrent calls from multiple
  threads may interleave results.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`getnetbyaddr`](getnetbyaddr) — the reverse lookup: network number
  → network record
- [`getnetent`](getnetent) — iterate every entry in the networks
  database instead of looking up one name
- [`setnetent`](setnetent) — rewind the networks iterator and control
  whether the file stays open across lookups
- [`endnetent`](endnetent) — close the networks database after an
  iteration
- [`gethostbyname`](gethostbyname) — the host-level counterpart, for
  resolving a hostname to an IP address
- `Net::netent` — by-name object wrapper returning accessor methods
  instead of a positional list