---
name: bind
signature: 'bind SOCKET, NAME'
since: 5.0
status: documented
categories: ["Sockets"]
---

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

*[Sockets](../perlfunc-by-category)*

# bind

Attach a local address to a socket.

`bind` is the Perl wrapper around the POSIX `bind(2)` system call. It
associates the already-opened `SOCKET` filehandle with the local
address `NAME`, so that subsequent [`listen`](listen) /
[`accept`](accept) calls (for a server) or [`connect`](connect) /
[`send`](send) calls (for a client with a fixed local address) use
that address as their source. `NAME` is a **packed** address
structure in the form the socket's address family expects — the job
of packing is yours, typically via [`Socket`](../../Socket) helpers
such as `` `sockaddr_in` `` or `` `sockaddr_un` ``.

## Synopsis

```perl
bind SOCKET, NAME
```

## What you get back

A true value on success, false on failure (with [`$!`](../perlvar)
set to the underlying errno: `EADDRINUSE`, `EACCES`, `EADDRNOTAVAIL`,
etc.). Always check the return value — unlike [`print`](print), a
failed `bind` is a setup-time error that has to abort the program:

```perl
bind $sock, $addr
    or die "bind failed: $!";
```

## Global state it touches

None directly. `bind` sets [`$!`](../perlvar) on failure; that is the
only interpreter global involved. The socket itself must already be
open — typically produced by [`socket`](socket) or
[`socketpair`](socketpair) — and `bind` mutates its kernel-side
state, not any Perl-level variable.

## Examples

Bind a TCP server socket to port 9000 on all local interfaces and
start listening. `INADDR_ANY` selects "any local address"; the packed
form comes from `` `sockaddr_in` ``:

```perl
use Socket;

socket(my $srv, PF_INET, SOCK_STREAM, getprotobyname("tcp"))
    or die "socket: $!";
bind($srv, sockaddr_in(9000, INADDR_ANY))
    or die "bind: $!";
listen($srv, SOMAXCONN)
    or die "listen: $!";
```

Bind a client socket to a specific local address before connecting —
used when the remote peer filters by source IP, or when a host has
multiple interfaces and you need outgoing traffic on a specific one:

```perl
use Socket;

socket(my $cli, PF_INET, SOCK_STREAM, getprotobyname("tcp"))
    or die "socket: $!";
bind($cli, sockaddr_in(0, inet_aton("192.0.2.17")))
    or die "bind: $!";          # port 0 = kernel picks one
connect($cli, sockaddr_in(443, inet_aton("93.184.216.34")))
    or die "connect: $!";
```

Bind a UNIX-domain listener to a filesystem path. The path must not
already exist — `bind` creates the socket node and leaves it behind
when the process exits, so clean it up yourself:

```perl
use Socket;

my $path = "/tmp/myapp.sock";
unlink $path;                   # clear stale socket from prior run
socket(my $srv, PF_UNIX, SOCK_STREAM, 0)
    or die "socket: $!";
bind($srv, sockaddr_un($path))
    or die "bind $path: $!";
listen($srv, 5) or die "listen: $!";
```

Bind a UDP socket to a fixed local port so replies from the peer
come back to a predictable address:

```perl
use Socket;

socket(my $udp, PF_INET, SOCK_DGRAM, getprotobyname("udp"))
    or die "socket: $!";
bind($udp, sockaddr_in(5300, INADDR_ANY))
    or die "bind: $!";
```

Rebinding a previously-released port in quick succession requires
`SO_REUSEADDR`; otherwise `bind` fails with `EADDRINUSE` during the
`TIME_WAIT` window:

```perl
use Socket;

setsockopt($srv, SOL_SOCKET, SO_REUSEADDR, pack("l", 1))
    or die "setsockopt: $!";
bind($srv, sockaddr_in(9000, INADDR_ANY))
    or die "bind: $!";
```

## Edge cases

- **`SOCKET` must already be open.** `bind` does not create the
  socket — call [`socket`](socket) first. A closed or never-opened
  filehandle fails with `EBADF`.
- **`NAME` is a packed byte string, not a human-readable address.**
  Pass the output of `` `sockaddr_in` ``, `` `sockaddr_in6` ``, or
  `` `sockaddr_un` `` from [`Socket`](../../Socket). Passing a plain
  string like `"127.0.0.1:9000"` produces `EINVAL` or worse — the
  kernel reads the bytes as a `struct sockaddr`.
- **Port 0 means "let the kernel choose"**. After a successful
  `bind` with port 0, retrieve the actual port with
  [`getsockname`](getsockname) and `` `sockaddr_in` `` in unpack mode.
- **Ports below 1024** require elevated privileges on Unix —
  `bind` fails with `EACCES` for an unprivileged process.
- **`EADDRINUSE`** is the most common failure. It fires when another
  process holds the address, when a prior socket on the same address
  is still in `TIME_WAIT`, or when you call `bind` twice on the same
  socket. `SO_REUSEADDR` (see [`setsockopt`](setsockopt)) addresses
  the `TIME_WAIT` case; the others are genuine conflicts.
- **UNIX-domain sockets leave a filesystem entry** that outlives the
  process. Remove it before a fresh `bind` (`unlink $path`) and on
  clean shutdown.
- **Binding after [`connect`](connect) is an error.** Once a socket
  has been connected, its local address is fixed. Call `bind` first
  if you need a specific source address.
- **IPv6 sockets** use `` `sockaddr_in6` `` and `PF_INET6`; mixing
  families between the socket and the packed address fails with
  `EAFNOSUPPORT`.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`socket`](socket) — create the socket filehandle that `bind`
  attaches to; must be called first
- [`connect`](connect) — the client-side counterpart; sets the
  remote address instead of the local one
- [`listen`](listen) — mark a bound socket as willing to accept
  incoming connections
- [`accept`](accept) — pull the next pending connection off a bound,
  listening socket
- [`getsockname`](getsockname) — recover the actual address `bind`
  chose, especially after binding to port 0
- [`setsockopt`](setsockopt) — set `SO_REUSEADDR` and friends
  *before* `bind` to control address reuse
- [`Socket`](../../Socket) — packs and unpacks the `NAME` argument;
  source of `` `sockaddr_in` ``, `` `sockaddr_un` ``, `INADDR_ANY`,
  `PF_INET`, and related constants