cpan/IO-Socket-IP/README

   1 NAME
   2     `IO::Socket::IP' - Family-neutral IP socket supporting both IPv4 and
   3     IPv6
   4
   5 SYNOPSIS
   6      use IO::Socket::IP;
   7
   8      my $sock = IO::Socket::IP->new(
   9         PeerHost => "www.google.com",
  10         PeerPort => "http",
  11         Type     => SOCK_STREAM,
  12      ) or die "Cannot construct socket - $@";
  13
  14      my $familyname = ( $sock->sockdomain == PF_INET6 ) ? "IPv6" :
  15                       ( $sock->sockdomain == PF_INET  ) ? "IPv4" :
  16                                                           "unknown";
  17
  18      printf "Connected to google via %s\n", $familyname;
  19
  20 DESCRIPTION
  21     This module provides a protocol-independent way to use IPv4 and IPv6
  22     sockets, intended as a replacement for IO::Socket::INET. Most
  23     constructor arguments and methods are provided in a backward-compatible
  24     way. For a list of known differences, see the `IO::Socket::INET'
  25     INCOMPATIBILITES section below.
  26
  27     It uses the `getaddrinfo(3)' function to convert hostnames and service
  28     names or port numbers into sets of possible addresses to connect to or
  29     listen on. This allows it to work for IPv6 where the system supports it,
  30     while still falling back to IPv4-only on systems which don't.
  31
  32 REPLACING `IO::Socket' DEFAULT BEHAVIOUR
  33     By placing `-register' in the import list, IO::Socket uses
  34     `IO::Socket::IP' rather than `IO::Socket::INET' as the class that
  35     handles `PF_INET'. `IO::Socket' will also use `IO::Socket::IP' rather
  36     than `IO::Socket::INET6' to handle `PF_INET6', provided that the
  37     `AF_INET6' constant is available.
  38
  39     Changing `IO::Socket''s default behaviour means that calling the
  40     `IO::Socket' constructor with either `PF_INET' or `PF_INET6' as the
  41     `Domain' parameter will yield an `IO::Socket::IP' object.
  42
  43      use IO::Socket::IP -register;
  44
  45      my $sock = IO::Socket->new(
  46         Domain    => PF_INET6,
  47         LocalHost => "::1",
  48         Listen    => 1,
  49      ) or die "Cannot create socket - $@\n";
  50
  51      print "Created a socket of type " . ref($sock) . "\n";
  52
  53     Note that `-register' is a global setting that applies to the entire
  54     program; it cannot be applied only for certain callers, removed, or
  55     limited by lexical scope.
  56
  57 CONSTRUCTORS
  58   $sock = IO::Socket::IP->new( %args )
  59     Creates a new `IO::Socket::IP' object, containing a newly created socket
  60     handle according to the named arguments passed. The recognised arguments
  61     are:
  62
  63     PeerHost => STRING
  64     PeerService => STRING
  65             Hostname and service name for the peer to `connect()' to. The
  66             service name may be given as a port number, as a decimal string.
  67
  68     PeerAddr => STRING
  69     PeerPort => STRING
  70             For symmetry with the accessor methods and compatibility with
  71             `IO::Socket::INET', these are accepted as synonyms for
  72             `PeerHost' and `PeerService' respectively.
  73
  74     PeerAddrInfo => ARRAY
  75             Alternate form of specifying the peer to `connect()' to. This
  76             should be an array of the form returned by
  77             `Socket::getaddrinfo'.
  78
  79             This parameter takes precedence over the `Peer*', `Family',
  80             `Type' and `Proto' arguments.
  81
  82     LocalHost => STRING
  83     LocalService => STRING
  84             Hostname and service name for the local address to `bind()' to.
  85
  86     LocalAddr => STRING
  87     LocalPort => STRING
  88             For symmetry with the accessor methods and compatibility with
  89             `IO::Socket::INET', these are accepted as synonyms for
  90             `LocalHost' and `LocalService' respectively.
  91
  92     LocalAddrInfo => ARRAY
  93             Alternate form of specifying the local address to `bind()' to.
  94             This should be an array of the form returned by
  95             `Socket::getaddrinfo'.
  96
  97             This parameter takes precedence over the `Local*', `Family',
  98             `Type' and `Proto' arguments.
  99
 100     Family => INT
 101             The address family to pass to `getaddrinfo' (e.g. `AF_INET',
 102             `AF_INET6'). Normally this will be left undefined, and
 103             `getaddrinfo' will search using any address family supported by
 104             the system.
 105
 106     Type => INT
 107             The socket type to pass to `getaddrinfo' (e.g. `SOCK_STREAM',
 108             `SOCK_DGRAM'). Normally defined by the caller; if left undefined
 109             `getaddrinfo' may attempt to infer the type from the service
 110             name.
 111
 112     Proto => STRING or INT
 113             The IP protocol to use for the socket (e.g. `'tcp'',
 114             `IPPROTO_TCP', `'udp'',`IPPROTO_UDP'). Normally this will be
 115             left undefined, and either `getaddrinfo' or the kernel will
 116             choose an appropriate value. May be given either in string name
 117             or numeric form.
 118
 119     GetAddrInfoFlags => INT
 120             More flags to pass to the `getaddrinfo()' function. If not
 121             supplied, a default of `AI_ADDRCONFIG' will be used.
 122
 123             These flags will be combined with `AI_PASSIVE' if the `Listen'
 124             argument is given. For more information see the documentation
 125             about `getaddrinfo()' in the Socket module.
 126
 127     Listen => INT
 128             If defined, puts the socket into listening mode where new
 129             connections can be accepted using the `accept' method. The value
 130             given is used as the `listen(2)' queue size.
 131
 132     ReuseAddr => BOOL
 133             If true, set the `SO_REUSEADDR' sockopt
 134
 135     ReusePort => BOOL
 136             If true, set the `SO_REUSEPORT' sockopt (not all OSes implement
 137             this sockopt)
 138
 139     Broadcast => BOOL
 140             If true, set the `SO_BROADCAST' sockopt
 141
 142     V6Only => BOOL
 143             If defined, set the `IPV6_V6ONLY' sockopt when creating
 144             `PF_INET6' sockets to the given value. If true, a listening-mode
 145             socket will only listen on the `AF_INET6' addresses; if false it
 146             will also accept connections from `AF_INET' addresses.
 147
 148             If not defined, the socket option will not be changed, and
 149             default value set by the operating system will apply. For
 150             repeatable behaviour across platforms it is recommended this
 151             value always be defined for listening-mode sockets.
 152
 153             Note that not all platforms support disabling this option. Some,
 154             at least OpenBSD and MirBSD, will fail with `EINVAL' if you
 155             attempt to disable it. To determine whether it is possible to
 156             disable, you may use the class method
 157
 158              if( IO::Socket::IP->CAN_DISABLE_V6ONLY ) {
 159                 ...
 160              }
 161              else {
 162                 ...
 163              }
 164
 165             If your platform does not support disabling this option but you
 166             still want to listen for both `AF_INET' and `AF_INET6'
 167             connections you will have to create two listening sockets, one
 168             bound to each protocol.
 169
 170     MultiHomed
 171             This `IO::Socket::INET'-style argument is ignored, except if it
 172             is defined but false. See the `IO::Socket::INET'
 173             INCOMPATIBILITES section below.
 174
 175             However, the behaviour it enables is always performed by
 176             `IO::Socket::IP'.
 177
 178     Blocking => BOOL
 179             If defined but false, the socket will be set to non-blocking
 180             mode. Otherwise it will default to blocking mode. See the
 181             NON-BLOCKING section below for more detail.
 182
 183     If neither `Type' nor `Proto' hints are provided, a default of
 184     `SOCK_STREAM' and `IPPROTO_TCP' respectively will be set, to maintain
 185     compatibility with `IO::Socket::INET'. Other named arguments that are
 186     not recognised are ignored.
 187
 188     If neither `Family' nor any hosts or addresses are passed, nor any
 189     `*AddrInfo', then the constructor has no information on which to decide
 190     a socket family to create. In this case, it performs a `getaddinfo' call
 191     with the `AI_ADDRCONFIG' flag, no host name, and a service name of
 192     `"0"', and uses the family of the first returned result.
 193
 194     If the constructor fails, it will set `$@' to an appropriate error
 195     message; this may be from `$!' or it may be some other string; not every
 196     failure necessarily has an associated `errno' value.
 197
 198   $sock = IO::Socket::IP->new( $peeraddr )
 199     As a special case, if the constructor is passed a single argument (as
 200     opposed to an even-sized list of key/value pairs), it is taken to be the
 201     value of the `PeerAddr' parameter. This is parsed in the same way,
 202     according to the behaviour given in the `PeerHost' AND `LocalHost'
 203     PARSING section below.
 204
 205 METHODS
 206     As well as the following methods, this class inherits all the methods in
 207     IO::Socket and IO::Handle.
 208
 209   ( $host, $service ) = $sock->sockhost_service( $numeric )
 210     Returns the hostname and service name of the local address (that is, the
 211     socket address given by the `sockname' method).
 212
 213     If `$numeric' is true, these will be given in numeric form rather than
 214     being resolved into names.
 215
 216     The following four convenience wrappers may be used to obtain one of the
 217     two values returned here. If both host and service names are required,
 218     this method is preferable to the following wrappers, because it will
 219     call `getnameinfo(3)' only once.
 220
 221   $addr = $sock->sockhost
 222     Return the numeric form of the local address as a textual representation
 223
 224   $port = $sock->sockport
 225     Return the numeric form of the local port number
 226
 227   $host = $sock->sockhostname
 228     Return the resolved name of the local address
 229
 230   $service = $sock->sockservice
 231     Return the resolved name of the local port number
 232
 233   $addr = $sock->sockaddr
 234     Return the local address as a binary octet string
 235
 236   ( $host, $service ) = $sock->peerhost_service( $numeric )
 237     Returns the hostname and service name of the peer address (that is, the
 238     socket address given by the `peername' method), similar to the
 239     `sockhost_service' method.
 240
 241     The following four convenience wrappers may be used to obtain one of the
 242     two values returned here. If both host and service names are required,
 243     this method is preferable to the following wrappers, because it will
 244     call `getnameinfo(3)' only once.
 245
 246   $addr = $sock->peerhost
 247     Return the numeric form of the peer address as a textual representation
 248
 249   $port = $sock->peerport
 250     Return the numeric form of the peer port number
 251
 252   $host = $sock->peerhostname
 253     Return the resolved name of the peer address
 254
 255   $service = $sock->peerservice
 256     Return the resolved name of the peer port number
 257
 258   $addr = $peer->peeraddr
 259     Return the peer address as a binary octet string
 260
 261   $inet = $sock->as_inet
 262     Returns a new IO::Socket::INET instance wrapping the same filehandle.
 263     This may be useful in cases where it is required, for
 264     backward-compatibility, to have a real object of `IO::Socket::INET' type
 265     instead of `IO::Socket::IP'. The new object will wrap the same
 266     underlying socket filehandle as the original, so care should be taken
 267     not to continue to use both objects concurrently. Ideally the original
 268     `$sock' should be discarded after this method is called.
 269
 270     This method checks that the socket domain is `PF_INET' and will throw an
 271     exception if it isn't.
 272
 273 NON-BLOCKING
 274     If the constructor is passed a defined but false value for the
 275     `Blocking' argument then the socket is put into non-blocking mode. When
 276     in non-blocking mode, the socket will not be set up by the time the
 277     constructor returns, because the underlying `connect(2)' syscall would
 278     otherwise have to block.
 279
 280     The non-blocking behaviour is an extension of the `IO::Socket::INET'
 281     API, unique to `IO::Socket::IP', because the former does not support
 282     multi-homed non-blocking connect.
 283
 284     When using non-blocking mode, the caller must repeatedly check for
 285     writeability on the filehandle (for instance using `select' or
 286     `IO::Poll'). Each time the filehandle is ready to write, the `connect'
 287     method must be called, with no arguments. Note that some operating
 288     systems, most notably `MSWin32' do not report a `connect()' failure
 289     using write-ready; so you must also `select()' for exceptional status.
 290
 291     While `connect' returns false, the value of `$!' indicates whether it
 292     should be tried again (by being set to the value `EINPROGRESS', or
 293     `EWOULDBLOCK' on MSWin32), or whether a permanent error has occurred
 294     (e.g. `ECONNREFUSED').
 295
 296     Once the socket has been connected to the peer, `connect' will return
 297     true and the socket will now be ready to use.
 298
 299     Note that calls to the platform's underlying `getaddrinfo(3)' function
 300     may block. If `IO::Socket::IP' has to perform this lookup, the
 301     constructor will block even when in non-blocking mode.
 302
 303     To avoid this blocking behaviour, the caller should pass in the result
 304     of such a lookup using the `PeerAddrInfo' or `LocalAddrInfo' arguments.
 305     This can be achieved by using Net::LibAsyncNS, or the `getaddrinfo(3)'
 306     function can be called in a child process.
 307
 308      use IO::Socket::IP;
 309      use Errno qw( EINPROGRESS EWOULDBLOCK );
 310
 311      my @peeraddrinfo = ... # Caller must obtain the getaddinfo result here
 312
 313      my $socket = IO::Socket::IP->new(
 314         PeerAddrInfo => \@peeraddrinfo,
 315         Blocking     => 0,
 316      ) or die "Cannot construct socket - $@";
 317
 318      while( !$socket->connect and ( $! == EINPROGRESS || $! == EWOULDBLOCK ) ) {
 319         my $wvec = '';
 320         vec( $wvec, fileno $socket, 1 ) = 1;
 321         my $evec = '';
 322         vec( $evec, fileno $socket, 1 ) = 1;
 323
 324         select( undef, $wvec, $evec, undef ) or die "Cannot select - $!";
 325      }
 326
 327      die "Cannot connect - $!" if $!;
 328
 329      ...
 330
 331     The example above uses `select()', but any similar mechanism should work
 332     analogously. `IO::Socket::IP' takes care when creating new socket
 333     filehandles to preserve the actual file descriptor number, so such
 334     techniques as `poll' or `epoll' should be transparent to its
 335     reallocation of a different socket underneath, perhaps in order to
 336     switch protocol family between `PF_INET' and `PF_INET6'.
 337
 338     For another example using `IO::Poll' and `Net::LibAsyncNS', see the
 339     examples/nonblocking_libasyncns.pl file in the module distribution.
 340
 341 `PeerHost' AND `LocalHost' PARSING
 342     To support the `IO::Socket::INET' API, the host and port information may
 343     be passed in a single string rather than as two separate arguments.
 344
 345     If either `LocalHost' or `PeerHost' (or their `...Addr' synonyms) have
 346     any of the following special forms then special parsing is applied.
 347
 348     The value of the `...Host' argument will be split to give both the
 349     hostname and port (or service name):
 350
 351      hostname.example.org:http    # Host name
 352      192.0.2.1:80                 # IPv4 address
 353      [2001:db8::1]:80             # IPv6 address
 354
 355     In each case, the port or service name (e.g. `80') is passed as the
 356     `LocalService' or `PeerService' argument.
 357
 358     Either of `LocalService' or `PeerService' (or their `...Port' synonyms)
 359     can be either a service name, a decimal number, or a string containing
 360     both a service name and number, in a form such as
 361
 362      http(80)
 363
 364     In this case, the name (`http') will be tried first, but if the resolver
 365     does not understand it then the port number (`80') will be used instead.
 366
 367     If the `...Host' argument is in this special form and the corresponding
 368     `...Service' or `...Port' argument is also defined, the one parsed from
 369     the `...Host' argument will take precedence and the other will be
 370     ignored.
 371
 372   ( $host, $port ) = IO::Socket::IP->split_addr( $addr )
 373     Utility method that provides the parsing functionality described above.
 374     Returns a 2-element list, containing either the split hostname and port
 375     description if it could be parsed, or the given address and `undef' if
 376     it was not recognised.
 377
 378      IO::Socket::IP->split_addr( "hostname:http" )
 379                                   # ( "hostname",  "http" )
 380
 381      IO::Socket::IP->split_addr( "192.0.2.1:80" )
 382                                   # ( "192.0.2.1", "80"   )
 383
 384      IO::Socket::IP->split_addr( "[2001:db8::1]:80" )
 385                                   # ( "2001:db8::1", "80" )
 386
 387      IO::Socket::IP->split_addr( "something.else" )
 388                                   # ( "something.else", undef )
 389
 390   $addr = IO::Socket::IP->join_addr( $host, $port )
 391     Utility method that performs the reverse of `split_addr', returning a
 392     string formed by joining the specified host address and port number. The
 393     host address will be wrapped in `[]' brackets if required (because it is
 394     a raw IPv6 numeric address).
 395
 396     This can be especially useful when combined with the `sockhost_service'
 397     or `peerhost_service' methods.
 398
 399      say "Connected to ", IO::Socket::IP->join_addr( $sock->peerhost_service );
 400
 401 `IO::Socket::INET' INCOMPATIBILITES
 402     *   The behaviour enabled by `MultiHomed' is in fact implemented by
 403         `IO::Socket::IP' as it is required to correctly support searching
 404         for a useable address from the results of the `getaddrinfo(3)' call.
 405         The constructor will ignore the value of this argument, except if it
 406         is defined but false. An exception is thrown in this case, because
 407         that would request it disable the `getaddrinfo(3)' search behaviour
 408         in the first place.
 409
 410 TODO
 411     *   Investigate whether `POSIX::dup2' upsets BSD's `kqueue' watchers,
 412         and if so, consider what possible workarounds might be applied.
 413
 414 AUTHOR
 415     Paul Evans <leonerd@leonerd.org.uk>
 416