getprotobyname#

Look up an IP protocol by its textual name and return its database entry.

getprotobyname is the Perl wrapper around the system C library’s getprotobyname(3). Given a protocol name such as "tcp", "udp", or "icmp", it returns the matching entry from the system’s /etc/protocols database (or whatever backend nsswitch.conf directs to). The typical use is turning a human-readable protocol name into the numeric value that socket and setsockopt want.

Synopsis#

getprotobyname NAME
my ($name, $aliases, $proto) = getprotobyname NAME;
my $proto                    = getprotobyname NAME;   # scalar context

What you get back#

In list context, a four-element-looking list with three fields:

my ($name, $aliases, $proto) = getprotobyname("tcp");
# $name    => canonical name, e.g. "tcp"
# $aliases => space-separated alias list, e.g. "TCP"
# $proto   => numeric protocol number, e.g. 6

In scalar context, just the numeric protocol number ($proto). That is the common form, because the protocol number is the whole reason the lookup was performed:

my $tcp = getprotobyname("tcp");   # 6

If the protocol is not found, the return is an empty list in list context and undef in scalar context. Always check definedness before using the result — 0 is a valid protocol number ("ip"), so truth-testing alone is wrong.

defined(my $tcp = getprotobyname("tcp"))
    or die "tcp protocol not in /etc/protocols";

Global state it touches#

Shares the protocol-database iteration cursor with getprotobynumber, getprotoent, setprotoent, and endprotoent. A call to getprotobyname may reposition or reset that cursor depending on the system C library; do not interleave name lookups with a getprotoent iteration loop.
On some platforms the underlying getprotobyname(3) sets $! / errno on failure. Portable code should not rely on it — treat an undefined return as “not found” and move on.

Examples#

Turn a name into a protocol number for socket:

use Socket;
my $proto = getprotobyname("tcp")
    // die "tcp not configured";
socket(my $sock, PF_INET, SOCK_STREAM, $proto)
    or die "socket: $!";

List form, to see the canonical name and aliases a system uses:

my ($name, $aliases, $proto) = getprotobyname("TCP");
print "name=$name aliases=$aliases number=$proto\n";
# name=tcp aliases=TCP number=6

Defensive lookup with a fallback for the two protocols every script actually needs:

my %num_for = (tcp => 6, udp => 17, icmp => 1);
sub proto_num {
    my ($name) = @_;
    return getprotobyname($name) // $num_for{lc $name};
}

Scalar context is required when the return value feeds an expression; list context would flatten into the surrounding list:

my @args = (SOCK_STREAM, scalar getprotobyname("tcp"));

Edge cases#

Case sensitivity is system-dependent. glibc’s getprotobyname(3) matches the canonical name and every alias case-insensitively; other C libraries may not. If portability matters, pass the lowercase form ("tcp", not "TCP").
Protocol number 0 is valid ("ip"). Use defined(...), not boolean truth, when checking for success.
Not the same as a port number. getprotobyname("http") returns undef — "http" is a service name, not a protocol. Use getservbyname for service lookups.
Empty alias string is normal. Many entries have no aliases; the second return value is then the empty string, not undef.
Iteration cursor side-effects. If your program is in the middle of a getprotoent loop, calling getprotobyname may reset the cursor and skip or repeat entries. Finish the iteration, or save state, before doing name lookups.
Thread safety. The underlying C call is not thread-safe on every platform — it typically uses a per-process static buffer. Perl may use the reentrant getprotobyname_r form when available, but do not assume it.
Missing /etc/protocols entry. On minimal containers the database may be absent, in which case every call returns undef. Build protocol tables into your code when the target environment is not guaranteed to ship a protocol database.

Differences from upstream#

Fully compatible with upstream Perl 5.42.