Socket#

📦 std

BSD socket constants and address pack/unpack helpers that feed Perl’s built-in socket, bind, connect, accept, send, recv, setsockopt, and shutdown.

Typical flow: import a constant, pack it into a sockaddr, hand the result to the built-in.

use Socket;
socket(my $sock, PF_INET, SOCK_STREAM, IPPROTO_TCP) or die $!;
my $addr = pack_sockaddr_in(80, inet_aton("127.0.0.1"));
connect($sock, $addr) or die $!;

What lives here#

  • Address families: AF_INET, AF_INET6, AF_UNIX, AF_LOCAL, AF_UNSPEC, plus the matching PF_* protocol families.

  • Socket types: SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, SOCK_SEQPACKET.

  • Well-known addresses: INADDR_ANY, INADDR_LOOPBACK, INADDR_BROADCAST, INADDR_NONE, IN6ADDR_ANY, IN6ADDR_LOOPBACK (packed binary, ready for pack_sockaddr_in / pack_sockaddr_in6).

  • Protocol numbers: IPPROTO_IP, IPPROTO_TCP, IPPROTO_UDP, IPPROTO_IPV6, IPPROTO_ICMP, IPPROTO_RAW.

  • Socket-option levels and names: SOL_SOCKET, SO_REUSEADDR, SO_KEEPALIVE, SO_BROADCAST, SO_LINGER, SO_SNDBUF, SO_RCVBUF, SO_ERROR, SO_TYPE, and the rest of the SO_* family.

  • TCP options: TCP_NODELAY.

  • IP options: IP_TOS, IP_TTL, IP_MULTICAST_TTL, IP_MULTICAST_LOOP, IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP, plus the IPV6_* counterparts.

  • Message flags: MSG_OOB, MSG_PEEK, MSG_DONTWAIT, MSG_WAITALL, MSG_NOSIGNAL.

  • Shutdown modes: SHUT_RD, SHUT_WR, SHUT_RDWR.

  • Address packing: pack_sockaddr_in, unpack_sockaddr_in, pack_sockaddr_in6, unpack_sockaddr_in6, pack_sockaddr_un, unpack_sockaddr_un, plus the dual-mode sockaddr_in / sockaddr_in6 shortcuts and the sockaddr_family extractor.

  • Address parsing: inet_aton, inet_ntoa, inet_pton, inet_ntop.

  • Name resolution: getaddrinfo, getnameinfo, plus the AI_*, NI_*, and EAI_* flag and error constants.

The dual-mode shortcuts#

sockaddr_in, sockaddr_in6 and sockaddr_un pack in scalar context and unpack in list context:

my $sin           = sockaddr_in(80, inet_aton("127.0.0.1"));
my ($port, $addr) = sockaddr_in(getpeername($sock));

A wrong argument count for the chosen direction croaks with a usage message. The old six-argument sockaddr_in($af, $port, @quad) still packs, and warns “6-ARG sockaddr_in call is deprecated” under use warnings 'Socket'.

A constant this system does not have dies when called: a name Socket knows but the platform lacks (AF_802, SO_STATE) with “Your vendor has not defined Socket macro AF_802, used at FILE line N”, any other name with “FOO is not a valid Socket macro at FILE line N”.

Differences from upstream#

One, where perl 5.44 with Socket.xs fails: unpack_sockaddr_un of an abstract address (a sun_path starting with a NUL byte) that is longer than sun_path returns the 108 bytes sun_path holds. Socket.xs trusts the given length and returns bytes read from past the end of its copy of the structure (t/81-xs-native/Socket/190-or-better.t).

Functions#

Address packing#

pack_ip_mreq#

Pack an IPv4 multicast group membership request, the value the IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP socket options take.

unpack_ip_mreq#

Split a packed IPv4 multicast group membership request back into its two addresses.

pack_ip_mreq_source#

Pack a source-specific IPv4 multicast group membership request, the value the IP_ADD_SOURCE_MEMBERSHIP family of socket options takes.

unpack_ip_mreq_source#

Split a packed source-specific IPv4 multicast group membership request back into its three addresses.

pack_ipv6_mreq#

Pack an IPv6 multicast group membership request, the value the IPV6_ADD_MEMBERSHIP and IPV6_DROP_MEMBERSHIP socket options take.

unpack_ipv6_mreq#

Split a packed IPv6 multicast group membership request back into its address and interface index.

pack_sockaddr_in#

Build a packed sockaddr_in from a port number and a 4-byte IPv4 address, ready to hand to bind or connect.

unpack_sockaddr_in#

Split a packed sockaddr_in back into its port and 4-byte address.

pack_sockaddr_in6#

Build a packed sockaddr_in6 from a port, a 16-byte IPv6 address, and optional scope and flow-info fields.

unpack_sockaddr_in6#

Split a packed sockaddr_in6 into port, 16-byte address, scope id, and flow-info.

pack_sockaddr_un#

Build a packed sockaddr_un from a filesystem path, for use with Unix-domain sockets.

unpack_sockaddr_un#

Extract the filesystem path from a packed sockaddr_un.

sockaddr_family#

Read the address-family byte from any packed sockaddr without committing to one unpacking shape.

sockaddr_in#

Dual-mode shortcut: in scalar context it behaves like pack_sockaddr_in; in list context it behaves like unpack_sockaddr_in.

sockaddr_in6#

Dual-mode IPv6 shortcut: in scalar context it behaves like pack_sockaddr_in6; in list context it behaves like unpack_sockaddr_in6.

Address parsing#

inet_aton#

Turn a dotted-quad string or a hostname into a 4-byte packed IPv4 address, or undef if the name cannot be resolved.

inet_ntoa#

Turn a 4-byte packed IPv4 address back into a dotted-quad string.

inet_pton#

Parse an address string into its packed binary form for either IPv4 or IPv6, selected by the first argument.

inet_ntop#

Turn a packed IPv4 or IPv6 address back into its printable string form, selected by the first argument.

Name resolution#

getaddrinfo#

Resolve a host name and/or service name into a list of ready-to-use address records, honouring IPv4/IPv6 and protocol preferences carried through a hints hash.

getnameinfo#

Turn a packed sockaddr into a host name and service name, with optional flags to force numeric output or demand a successful DNS lookup.