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.

    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.

    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" 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", "Blocking" 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?

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>

