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 bygetaddrinfo
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
andPeerPort
are accepted as synonyms respectively. - 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
andLocalPort
are accepted as synonyms respectively. - 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
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
TODO
Cache the returns from
sockhost_service
andpeerhost_service
to avoid double-lookup overhead in such code asprintf "Peer is %s:%d\n", $sock->peerhost, $sock->peerport;
Implement constructor args
Timeout
,Blocking
and maybeDomain
. Except thatDomain
is harder because IO::Socket wants to dispatch to subclasses based on it. MaybeFamily
might be a better name?
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>