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

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

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

# 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`](socket) and
[`setsockopt`](setsockopt) want.

## Synopsis

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

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

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

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

```perl
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`](getprotobynumber), [`getprotoent`](getprotoent),
  [`setprotoent`](setprotoent), and [`endprotoent`](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`](getprotoent) iteration loop.
- On some platforms the underlying `getprotobyname(3)` sets
  [`$!`](../perlvar) / `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`](socket):

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

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

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

```perl
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`](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`](undef).
- **Iteration cursor side-effects.** If your program is in the
  middle of a [`getprotoent`](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`](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.

## See also

- [`getprotobynumber`](getprotobynumber) — the inverse lookup; use
  when you have the numeric protocol and want its name
- [`getprotoent`](getprotoent) — iterate every entry in the protocol
  database one record at a time
- [`setprotoent`](setprotoent) / [`endprotoent`](endprotoent) —
  control the iteration cursor shared with this function
- [`getservbyname`](getservbyname) — the equivalent lookup for
  services (ports), not protocols; the two are often confused
- [`socket`](socket) — the usual consumer of the returned protocol
  number
- `Net::protoent` — object-oriented wrapper that returns a blessed
  record with named accessors instead of a positional list