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#

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

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:

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

Round-trip against getnetbyaddr — name to number, then number back to name:

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:

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, not zero:

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, 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.
The returned number is host-byte-order, not a packed string. Unlike 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, 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 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.