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 / accept calls (for a server) or connect / 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 helpers such as `sockaddr_in` or `sockaddr_un`.

Synopsis#

bind SOCKET, NAME

What you get back#

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

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

Global state it touches#

None directly. bind sets $! on failure; that is the only interpreter global involved. The socket itself must already be open — typically produced by socket or 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`:

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:

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:

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:

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:

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 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. 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 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) 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 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.