IO::Socket::IP - Family-neutral IP socket supporting both IPv4 and IPv6
use IO::Socket::IP;
my $sock = IO::Socket::IP->new(
PeerHost => "www.google.com",
PeerPort => "http",
Type => SOCK_STREAM,
) or die "Cannot construct socket - $IO::Socket::errstr";
my $familyname = ( $sock->sockdomain == PF_INET6 ) ? "IPv6" :
( $sock->sockdomain == PF_INET ) ? "IPv4" :
"unknown";
printf "Connected to google via %s\n", $familyname;This module provides a protocol-independent way to use IPv4 and IPv6 sockets, intended as a replacement for IO::Socket::INET. Most constructor arguments and methods are provided in a backward-compatible way. For a list of known differences, see the IO::Socket::INET INCOMPATIBILITES section below.
It uses the getaddrinfo(3) function to convert hostnames and service names or port numbers into sets of possible addresses to connect to or listen on. This allows it to work for IPv6 where the system supports it, while still falling back to IPv4-only on systems which don't.
IO::Socket DEFAULT BEHAVIOURBy placing -register in the import list to IO::Socket::IP, it will register itself with IO::Socket as the class that handles PF_INET. It will also ask to handle PF_INET6 as well, provided that constant is available.
Changing IO::Socket's default behaviour means that calling the IO::Socket constructor with either PF_INET or PF_INET6 as the Domain parameter will yield an IO::Socket::IP object.
use IO::Socket::IP -register;
my $sock = IO::Socket->new(
Domain => PF_INET6,
LocalHost => "::1",
Listen => 1,
) or die "Cannot create socket - $IO::Socket::errstr\n";
print "Created a socket of type " . ref($sock) . "\n";Note that -register is a global setting that applies to the entire program; it cannot be applied only for certain callers, removed, or limited by lexical scope.
$sock = IO::Socket::IP->new( %args )Creates a new IO::Socket::IP object, containing a newly created socket handle according to the named arguments passed. The recognised arguments are:
Hostname and service name for the peer to connect() to. The service name may be given as a port number, as a decimal string.
For symmetry with the accessor methods and compatibility with IO::Socket::INET, these are accepted as synonyms for PeerHost and PeerService respectively.
Alternate form of specifying the peer to connect() to. This should be an array of the form returned by Socket::getaddrinfo.
This parameter takes precedence over the Peer*, Family, Type and Proto arguments.
Hostname and service name for the local address to bind() to.
For symmetry with the accessor methods and compatibility with IO::Socket::INET, these are accepted as synonyms for LocalHost and LocalService respectively.
Alternate form of specifying the local address to bind() to. This should be an array of the form returned by Socket::getaddrinfo.
This parameter takes precedence over the Local*, Family, Type and Proto arguments.
The address family to pass to getaddrinfo (e.g. AF_INET, AF_INET6). Normally this will be left undefined, and getaddrinfo will search using any address family supported by the system.
The socket type to pass to getaddrinfo (e.g. SOCK_STREAM, SOCK_DGRAM). Normally defined by the caller; if left undefined getaddrinfo may attempt to infer the type from the service name.
The IP protocol to use for the socket (e.g. 'tcp', IPPROTO_TCP, 'udp',IPPROTO_UDP). Normally this will be left undefined, and either getaddrinfo or the kernel will choose an appropriate value. May be given either in string name or numeric form.
More flags to pass to the getaddrinfo() function. If not supplied, a default of AI_ADDRCONFIG will be used.
These flags will be combined with AI_PASSIVE if the Listen argument is given. For more information see the documentation about getaddrinfo() in the Socket module.
If defined, puts the socket into listening mode where new connections can be accepted using the accept method. The value given is used as the listen(2) queue size.
If true, set the SO_REUSEADDR sockopt
If true, set the SO_REUSEPORT sockopt (not all OSes implement this sockopt)
If true, set the SO_BROADCAST sockopt
An optional array of other socket options to apply after the three listed above. The value is an ARRAY containing 2- or 3-element ARRAYrefs. Each inner array relates to a single option, giving the level and option name, and an optional value. If the value element is missing, it will be given the value of a platform-sized integer 1 constant (i.e. suitable to enable most of the common boolean options).
For example, both options given below are equivalent to setting ReuseAddr.
Sockopts => [
[ SOL_SOCKET, SO_REUSEADDR ],
[ SOL_SOCKET, SO_REUSEADDR, pack( "i", 1 ) ],
]If defined, set the IPV6_V6ONLY sockopt when creating PF_INET6 sockets to the given value. If true, a listening-mode socket will only listen on the AF_INET6 addresses; if false it will also accept connections from AF_INET addresses.
If not defined, the socket option will not be changed, and default value set by the operating system will apply. For repeatable behaviour across platforms it is recommended this value always be defined for listening-mode sockets.
Note that not all platforms support disabling this option. Some, at least OpenBSD and MirBSD, will fail with EINVAL if you attempt to disable it. To determine whether it is possible to disable, you may use the class method
if( IO::Socket::IP->CAN_DISABLE_V6ONLY ) {
...
}
else {
...
}If your platform does not support disabling this option but you still want to listen for both AF_INET and AF_INET6 connections you will have to create two listening sockets, one bound to each protocol.
This IO::Socket::INET-style argument is ignored, except if it is defined but false. See the IO::Socket::INET INCOMPATIBILITES section below.
However, the behaviour it enables is always performed by IO::Socket::IP.
If defined but false, the socket will be set to non-blocking mode. Otherwise it will default to blocking mode. See the NON-BLOCKING section below for more detail.
If defined, gives a maximum time in seconds to block per connect() call when in blocking mode. If missing, no timeout is applied other than that provided by the underlying operating system. When in non-blocking mode this parameter is ignored.
Note that if the hostname resolves to multiple address candidates, the same timeout will apply to each connection attempt individually, rather than to the operation as a whole. Further note that the timeout does not apply to the initial hostname resolve operation, if connecting by hostname.
This behaviour is copied inspired by IO::Socket::INET; for more fine grained control over connection timeouts, consider performing a nonblocking connect directly.
If neither Type nor Proto hints are provided, a default of SOCK_STREAM and IPPROTO_TCP respectively will be set, to maintain compatibility with IO::Socket::INET. Other named arguments that are not recognised are ignored.
If neither Family nor any hosts or addresses are passed, nor any *AddrInfo, then the constructor has no information on which to decide a socket family to create. In this case, it performs a getaddinfo call with the AI_ADDRCONFIG flag, no host name, and a service name of "0", and uses the family of the first returned result.
If the constructor fails, it will set $IO::Socket::errstr and $@ to an appropriate error message; this may be from $! or it may be some other string; not every failure necessarily has an associated errno value.
$sock = IO::Socket::IP->new( $peeraddr )As a special case, if the constructor is passed a single argument (as opposed to an even-sized list of key/value pairs), it is taken to be the value of the PeerAddr parameter. This is parsed in the same way, according to the behaviour given in the PeerHost AND LocalHost PARSING section below.
As well as the following methods, this class inherits all the methods in IO::Socket and IO::Handle.
( $host, $service ) = $sock->sockhost_service( $numeric )Returns the hostname and service name of the local address (that is, the socket address given by the sockname method).
If $numeric is true, these will be given in numeric form rather than being resolved into names.
The following four convenience wrappers may be used to obtain one of the two values returned here. If both host and service names are required, this method is preferable to the following wrappers, because it will call getnameinfo(3) only once.
$addr = $sock->sockhostReturn the numeric form of the local address as a textual representation
$port = $sock->sockportReturn the numeric form of the local port number
$host = $sock->sockhostnameReturn the resolved name of the local address
$service = $sock->sockserviceReturn the resolved name of the local port number
$addr = $sock->sockaddrReturn the local address as a binary octet string
( $host, $service ) = $sock->peerhost_service( $numeric )Returns the hostname and service name of the peer address (that is, the socket address given by the peername method), similar to the sockhost_service method.
The following four convenience wrappers may be used to obtain one of the two values returned here. If both host and service names are required, this method is preferable to the following wrappers, because it will call getnameinfo(3) only once.
$addr = $sock->peerhostReturn the numeric form of the peer address as a textual representation
$port = $sock->peerportReturn the numeric form of the peer port number
$host = $sock->peerhostnameReturn the resolved name of the peer address
$service = $sock->peerserviceReturn the resolved name of the peer port number