NAME "IO::Socket::IP" - Use IPv4 and IPv6 sockets in a protocol-independent way SYNOPSIS use IO::Socket::IP; my $sock = IO::Socket::IP->new( PeerHost => "www.google.com", PeerService => "www", ) or die "Cannot construct socket - $@"; printf "Now connected to %s:%s\n", $sock->peerhost_service; ... DESCRIPTION This module provides a protocol-independent way to use IPv4 and IPv6 sockets. It allows new connections to be made by specifying the hostname and service name or port number. It allows for connections to be accepted by sockets listening on local ports, by service name or port number. It uses Socket::GetAddrInfo's "getaddrinfo" function to convert hostname/service name pairs into sets of possible addresses to connect to. This allows it to work for IPv6 where the system supports it, while still falling back to IPv4-only on systems which don't. It provides an API which, for most typical cases, should be a drop-in replacement for IO::Socket::INET; most constructor arguments and methods are provided in a compatible way. CONSTRUCTOR $sock = IO::Socket::IP->new( %args ) Creates a new "IO::Socket::IP" object. If any arguments are passed it will be configured to contain a newly created socket handle, and be configured according to the argmuents. The recognised arguments are: Type => INT The socket type (e.g. "SOCK_STREAM", "SOCK_DGRAM"). Will be inferred by "getaddrinfo" from the service name if not supplied. Proto => INT IP protocol for the socket connection. Will be inferred by "getaddrinfo" from the service name, or by the kernel from the socket type, if not supplied. PeerHost => STRING PeerService => STRING 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", "PeerAddr" and "PeerPort" are accepted as synonyms respectively. PeerAddrInfo => ARRAY Alternate form of specifying the peer to "connect()" to. This should be an array of the form returned by "Socket::GetAddrInfo::getaddrinfo". This parameter overrides "PeerHost" and "PeerService", and will ignore any values given for "Type" or "Proto". Listen => INT Puts the socket into listening mode where new connections can be accepted using the "accept" method. LocalHost => STRING LocalService => STRING Hostname and service name for the local address to "bind()" to. For symmetry with the accessor methods and compatibility with "IO::Socket::INET", "LocalAddr" and "LocalPort" are accepted as synonyms respectively. LocalAddrInfo => ARRAY Alternate form of specifying the local address to "bind()" to. This should be an array of the form returned by "Socket::GetAddrInfo::getaddrinfo". This parameter overrides "LocalHost" and "LocalService", and will ignore any values given for "Type" or "Proto". ReuseAddr => BOOL If true, set the "SO_REUSEADDR" sockopt ReusePort => BOOL If true, set the "SO_REUSEPORT" sockopt (not all OSes implement this sockopt) Broadcast => BOOL If true, set the "SO_BROADCAST" sockopt Blocking => BOOL If false, the socket will be set to nonblocking mode. If absent or true it will be in blocking mode. See "NON-BLOCKING" below for more detail. If the constructor fails, it will set $@ 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. If either "LocalHost" or "PeerHost" (or their "...Addr" synonyms) have any of the following special forms, they are split to imply both the hostname and service name: hostname.example.org:port # DNS name 10.0.0.1:port # IPv4 address [fe80::123]:port # IPv6 address In each case, "port" is passed to the "LocalService" or "PeerService" argument. Either of "LocalService" or "PeerService" (or their "...Port" synonyms) can be either a service name, a decimal number, or a string containing both a service name and number, in the form name(number) In this case, the name will be tried first, but if the resolver does not understand it then the port number will be used instead. $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. The example in the SYNOPSIS section may also therefore be written as my $sock = IO::Socket::IP->new( "www.google.com:www" ) or die "Cannot construct socket - $@"; METHODS ( $host, $service ) = $sock->sockhost_service( $numeric ) Return the hostname and service name for the local endpoint (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. This method is used to implement the following for convenience wrappers. If both host and service names are required, this method is preferrable to the following wrappers, because it will call getnameinfo(3) only once. $addr = $sock->sockhost Return the numeric form of the local address $port = $sock->sockport Return the numeric form of the local port number $host = $sock->sockhostname Return the resolved name of the local address $service = $sock->sockservice Return the resolved name of the local port number ( $host, $service ) = $sock->peerhost_service( $numeric ) Similar to the "sockhost_service" method, but instead returns the hostname and service name for the peer endpoint (that is, the socket address given by the "peername" method). $addr = $sock->peerhost Return the numeric form of the peer address $port = $sock->peerport Return the numeric form of the peer port number $host = $sock->peerhostname Return the resolved name of the peer address $service = $sock->peerservice Return the resolved name of the peer port number NON-BLOCKING If the constructor is passed a false value for the "Blocking" argument, then the socket is put into nonblocking mode. When in nonblocking mode, an actual "connect" operation will not have been completed by the time the constructor returns, because this may block. In order to use this mode, the caller should poll for writeability on the filehandle, each time it indicates write-readiness, the user code should call the "connect" method, with no arguments. Once the socket has been connected to the peer, "connect" will return true. If it returns false, the value of $! indicates whether it should be tried again ("EINPROGRESS"), or whether a permanent error has occured. This API is an extension of the "IO::Socket::INET" API, unique to "IO::Socket::IP", because the former does not support multi-homed nonblocking connect. use IO::Socket::IP; use Errno qw( EINPROGRESS ); use Socket qw( SOCK_STREAM ); my $socket = IO::Socket::IP->new( PeerHost => "192.168.1.1", PeerService => "25", Type => SOCK_STREAM, Blocking => 0, ) or die "Cannot construct socket - $@"; while( !$socket->connect and $! == EINPROGRESS ) { my $wvec = ''; vec( $wvec, fileno $socket, 1 ) = 1; select( undef, $wvec, undef, undef ) or die "Cannot select - $!"; } die "Cannot connect - $!" if $!; ... This example uses "select()", but any similar mechanism should work analogously. "IO::Socket::IP" takes care when creating new socket filehandles to preserve the actual file descriptor number, so such techniques as "poll" or "epoll" should be transparent to its reallocation of a different socket underneath, perhaps in order to switch protocol family between "PF_INET" and "PF_INET6". When performing a non-blocking connect, it may be preferred to use the alternative "LocalAddrInfo" and "PeerAddrInfo" arguments. These allow the caller to perform the "getaddrinfo" calls required, because if "IO::Socket::IP" makes them they will definitely block. These arguments are provided for the case where the caller already has the "getaddrinfo" results, perhaps obtained by some non-blocking method like Net::LibAsyncNS, or by performing the lookup in a child process and passing the results back to the main process in an event loop of some kind. TODO * Cache the returns from "sockhost_service" and "peerhost_service" to avoid double-lookup overhead in such code as printf "Peer is %s:%d\n", $sock->peerhost, $sock->peerport; * Implement constructor args "Timeout" and maybe "Domain". Except that "Domain" is harder because IO::Socket wants to dispatch to subclasses based on it. Maybe "Family" might be a better name? * Investigate whether "POSIX::dup2" upsets BSD's "kqueue" watchers, and if so, consider what possible workarounds might be applied. BUGS * Nonblocking connect fails unit tests on MSWin32 smoke-testing machines. The specifics of the failure are that "connect()" seems to block anyway despite being asked not to, and that failure to connect is not detected properly. I am as yet unsure why this is. Blocking connect on MSWin32, and both blocking and nonblocking connect on other platforms, all test OK on smoke testing. AUTHOR Paul Evans