Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 622 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/IO::Socket::IP.3perl b/upstream/debian-unstable/man3/IO::Socket::IP.3perl
new file mode 100644
index 00000000..de9af27d
--- /dev/null
+++ b/upstream/debian-unstable/man3/IO::Socket::IP.3perl
@@ -0,0 +1,622 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "IO::Socket::IP 3perl"
+.TH IO::Socket::IP 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+"IO::Socket::IP" \- Family\-neutral IP socket supporting both IPv4 and IPv6
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use IO::Socket::IP;
+\&
+\& my $sock = IO::Socket::IP\->new(
+\&    PeerHost => "www.google.com",
+\&    PeerPort => "http",
+\&    Type     => SOCK_STREAM,
+\& ) or die "Cannot construct socket \- $@";
+\&
+\& my $familyname = ( $sock\->sockdomain == PF_INET6 ) ? "IPv6" :
+\&                  ( $sock\->sockdomain == PF_INET  ) ? "IPv4" :
+\&                                                      "unknown";
+\&
+\& printf "Connected to google via %s\en", $familyname;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+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 \f(CW\*(C`IO::Socket::INET\*(C'\fR INCOMPATIBILITES section below.
+.PP
+It uses the \f(CWgetaddrinfo(3)\fR 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.
+.ie n .SH "REPLACING ""IO::Socket"" DEFAULT BEHAVIOUR"
+.el .SH "REPLACING \f(CWIO::Socket\fP DEFAULT BEHAVIOUR"
+.IX Header "REPLACING IO::Socket DEFAULT BEHAVIOUR"
+By placing \f(CW\*(C`\-register\*(C'\fR in the import list to \f(CW\*(C`IO::Socket::IP\*(C'\fR, it will
+register itself with IO::Socket as the class that handles \f(CW\*(C`PF_INET\*(C'\fR. It
+will also ask to handle \f(CW\*(C`PF_INET6\*(C'\fR as well, provided that constant is
+available.
+.PP
+Changing \f(CW\*(C`IO::Socket\*(C'\fR's default behaviour means that calling the
+\&\f(CW\*(C`IO::Socket\*(C'\fR constructor with either \f(CW\*(C`PF_INET\*(C'\fR or \f(CW\*(C`PF_INET6\*(C'\fR as the
+\&\f(CW\*(C`Domain\*(C'\fR parameter will yield an \f(CW\*(C`IO::Socket::IP\*(C'\fR object.
+.PP
+.Vb 1
+\& use IO::Socket::IP \-register;
+\&
+\& my $sock = IO::Socket\->new(
+\&    Domain    => PF_INET6,
+\&    LocalHost => "::1",
+\&    Listen    => 1,
+\& ) or die "Cannot create socket \- $@\en";
+\&
+\& print "Created a socket of type " . ref($sock) . "\en";
+.Ve
+.PP
+Note that \f(CW\*(C`\-register\*(C'\fR is a global setting that applies to the entire program;
+it cannot be applied only for certain callers, removed, or limited by lexical
+scope.
+.SH CONSTRUCTORS
+.IX Header "CONSTRUCTORS"
+.SS new
+.IX Subsection "new"
+.Vb 1
+\&   $sock = IO::Socket::IP\->new( %args )
+.Ve
+.PP
+Creates a new \f(CW\*(C`IO::Socket::IP\*(C'\fR object, containing a newly created socket
+handle according to the named arguments passed. The recognised arguments are:
+.IP "PeerHost => STRING" 8
+.IX Item "PeerHost => STRING"
+.PD 0
+.IP "PeerService => STRING" 8
+.IX Item "PeerService => STRING"
+.PD
+Hostname and service name for the peer to \f(CWconnect()\fR to. The service name
+may be given as a port number, as a decimal string.
+.IP "PeerAddr => STRING" 8
+.IX Item "PeerAddr => STRING"
+.PD 0
+.IP "PeerPort => STRING" 8
+.IX Item "PeerPort => STRING"
+.PD
+For symmetry with the accessor methods and compatibility with
+\&\f(CW\*(C`IO::Socket::INET\*(C'\fR, these are accepted as synonyms for \f(CW\*(C`PeerHost\*(C'\fR and
+\&\f(CW\*(C`PeerService\*(C'\fR respectively.
+.IP "PeerAddrInfo => ARRAY" 8
+.IX Item "PeerAddrInfo => ARRAY"
+Alternate form of specifying the peer to \f(CWconnect()\fR to. This should be an
+array of the form returned by \f(CW\*(C`Socket::getaddrinfo\*(C'\fR.
+.Sp
+This parameter takes precedence over the \f(CW\*(C`Peer*\*(C'\fR, \f(CW\*(C`Family\*(C'\fR, \f(CW\*(C`Type\*(C'\fR and
+\&\f(CW\*(C`Proto\*(C'\fR arguments.
+.IP "LocalHost => STRING" 8
+.IX Item "LocalHost => STRING"
+.PD 0
+.IP "LocalService => STRING" 8
+.IX Item "LocalService => STRING"
+.PD
+Hostname and service name for the local address to \f(CWbind()\fR to.
+.IP "LocalAddr => STRING" 8
+.IX Item "LocalAddr => STRING"
+.PD 0
+.IP "LocalPort => STRING" 8
+.IX Item "LocalPort => STRING"
+.PD
+For symmetry with the accessor methods and compatibility with
+\&\f(CW\*(C`IO::Socket::INET\*(C'\fR, these are accepted as synonyms for \f(CW\*(C`LocalHost\*(C'\fR and
+\&\f(CW\*(C`LocalService\*(C'\fR respectively.
+.IP "LocalAddrInfo => ARRAY" 8
+.IX Item "LocalAddrInfo => ARRAY"
+Alternate form of specifying the local address to \f(CWbind()\fR to. This should be
+an array of the form returned by \f(CW\*(C`Socket::getaddrinfo\*(C'\fR.
+.Sp
+This parameter takes precedence over the \f(CW\*(C`Local*\*(C'\fR, \f(CW\*(C`Family\*(C'\fR, \f(CW\*(C`Type\*(C'\fR and
+\&\f(CW\*(C`Proto\*(C'\fR arguments.
+.IP "Family => INT" 8
+.IX Item "Family => INT"
+The address family to pass to \f(CW\*(C`getaddrinfo\*(C'\fR (e.g. \f(CW\*(C`AF_INET\*(C'\fR, \f(CW\*(C`AF_INET6\*(C'\fR).
+Normally this will be left undefined, and \f(CW\*(C`getaddrinfo\*(C'\fR will search using any
+address family supported by the system.
+.IP "Type => INT" 8
+.IX Item "Type => INT"
+The socket type to pass to \f(CW\*(C`getaddrinfo\*(C'\fR (e.g. \f(CW\*(C`SOCK_STREAM\*(C'\fR,
+\&\f(CW\*(C`SOCK_DGRAM\*(C'\fR). Normally defined by the caller; if left undefined
+\&\f(CW\*(C`getaddrinfo\*(C'\fR may attempt to infer the type from the service name.
+.IP "Proto => STRING or INT" 8
+.IX Item "Proto => STRING or INT"
+The IP protocol to use for the socket (e.g. \f(CW\*(Aqtcp\*(Aq\fR, \f(CW\*(C`IPPROTO_TCP\*(C'\fR,
+\&\f(CW\*(Aqudp\*(Aq\fR,\f(CW\*(C`IPPROTO_UDP\*(C'\fR). Normally this will be left undefined, and either
+\&\f(CW\*(C`getaddrinfo\*(C'\fR or the kernel will choose an appropriate value. May be given
+either in string name or numeric form.
+.IP "GetAddrInfoFlags => INT" 8
+.IX Item "GetAddrInfoFlags => INT"
+More flags to pass to the \f(CWgetaddrinfo()\fR function. If not supplied, a
+default of \f(CW\*(C`AI_ADDRCONFIG\*(C'\fR will be used.
+.Sp
+These flags will be combined with \f(CW\*(C`AI_PASSIVE\*(C'\fR if the \f(CW\*(C`Listen\*(C'\fR argument is
+given. For more information see the documentation about \f(CWgetaddrinfo()\fR in
+the Socket module.
+.IP "Listen => INT" 8
+.IX Item "Listen => INT"
+If defined, puts the socket into listening mode where new connections can be
+accepted using the \f(CW\*(C`accept\*(C'\fR method. The value given is used as the
+\&\f(CWlisten(2)\fR queue size.
+.IP "ReuseAddr => BOOL" 8
+.IX Item "ReuseAddr => BOOL"
+If true, set the \f(CW\*(C`SO_REUSEADDR\*(C'\fR sockopt
+.IP "ReusePort => BOOL" 8
+.IX Item "ReusePort => BOOL"
+If true, set the \f(CW\*(C`SO_REUSEPORT\*(C'\fR sockopt (not all OSes implement this sockopt)
+.IP "Broadcast => BOOL" 8
+.IX Item "Broadcast => BOOL"
+If true, set the \f(CW\*(C`SO_BROADCAST\*(C'\fR sockopt
+.IP "Sockopts => ARRAY" 8
+.IX Item "Sockopts => ARRAY"
+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).
+.Sp
+For example, both options given below are equivalent to setting \f(CW\*(C`ReuseAddr\*(C'\fR.
+.Sp
+.Vb 4
+\& Sockopts => [
+\&    [ SOL_SOCKET, SO_REUSEADDR ],
+\&    [ SOL_SOCKET, SO_REUSEADDR, pack( "i", 1 ) ],
+\& ]
+.Ve
+.IP "V6Only => BOOL" 8
+.IX Item "V6Only => BOOL"
+If defined, set the \f(CW\*(C`IPV6_V6ONLY\*(C'\fR sockopt when creating \f(CW\*(C`PF_INET6\*(C'\fR sockets
+to the given value. If true, a listening-mode socket will only listen on the
+\&\f(CW\*(C`AF_INET6\*(C'\fR addresses; if false it will also accept connections from
+\&\f(CW\*(C`AF_INET\*(C'\fR addresses.
+.Sp
+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.
+.Sp
+Note that not all platforms support disabling this option. Some, at least
+OpenBSD and MirBSD, will fail with \f(CW\*(C`EINVAL\*(C'\fR if you attempt to disable it.
+To determine whether it is possible to disable, you may use the class method
+.Sp
+.Vb 6
+\& if( IO::Socket::IP\->CAN_DISABLE_V6ONLY ) {
+\&    ...
+\& }
+\& else {
+\&    ...
+\& }
+.Ve
+.Sp
+If your platform does not support disabling this option but you still want to
+listen for both \f(CW\*(C`AF_INET\*(C'\fR and \f(CW\*(C`AF_INET6\*(C'\fR connections you will have to create
+two listening sockets, one bound to each protocol.
+.IP MultiHomed 8
+.IX Item "MultiHomed"
+This \f(CW\*(C`IO::Socket::INET\*(C'\fR\-style argument is ignored, except if it is defined
+but false. See the \f(CW\*(C`IO::Socket::INET\*(C'\fR INCOMPATIBILITES section below.
+.Sp
+However, the behaviour it enables is always performed by \f(CW\*(C`IO::Socket::IP\*(C'\fR.
+.IP "Blocking => BOOL" 8
+.IX Item "Blocking => BOOL"
+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.
+.IP "Timeout => NUM" 8
+.IX Item "Timeout => NUM"
+If defined, gives a maximum time in seconds to block per \f(CWconnect()\fR 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.
+.Sp
+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.
+.Sp
+This behviour is copied inspired by \f(CW\*(C`IO::Socket::INET\*(C'\fR; for more fine grained
+control over connection timeouts, consider performing a nonblocking connect
+directly.
+.PP
+If neither \f(CW\*(C`Type\*(C'\fR nor \f(CW\*(C`Proto\*(C'\fR hints are provided, a default of
+\&\f(CW\*(C`SOCK_STREAM\*(C'\fR and \f(CW\*(C`IPPROTO_TCP\*(C'\fR respectively will be set, to maintain
+compatibility with \f(CW\*(C`IO::Socket::INET\*(C'\fR. Other named arguments that are not
+recognised are ignored.
+.PP
+If neither \f(CW\*(C`Family\*(C'\fR nor any hosts or addresses are passed, nor any
+\&\f(CW*AddrInfo\fR, then the constructor has no information on which to decide a
+socket family to create. In this case, it performs a \f(CW\*(C`getaddinfo\*(C'\fR call with
+the \f(CW\*(C`AI_ADDRCONFIG\*(C'\fR flag, no host name, and a service name of \f(CW"0"\fR, and
+uses the family of the first returned result.
+.PP
+If the constructor fails, it will set \f(CW$@\fR to an appropriate error message;
+this may be from \f(CW$!\fR or it may be some other string; not every failure
+necessarily has an associated \f(CW\*(C`errno\*(C'\fR value.
+.SS "new (one arg)"
+.IX Subsection "new (one arg)"
+.Vb 1
+\&   $sock = IO::Socket::IP\->new( $peeraddr )
+.Ve
+.PP
+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 \f(CW\*(C`PeerAddr\*(C'\fR parameter. This is parsed in the same way, according to the
+behaviour given in the \f(CW\*(C`PeerHost\*(C'\fR AND \f(CW\*(C`LocalHost\*(C'\fR PARSING section below.
+.SH METHODS
+.IX Header "METHODS"
+As well as the following methods, this class inherits all the methods in
+IO::Socket and IO::Handle.
+.SS sockhost_service
+.IX Subsection "sockhost_service"
+.Vb 1
+\&   ( $host, $service ) = $sock\->sockhost_service( $numeric )
+.Ve
+.PP
+Returns the hostname and service name of the local address (that is, the
+socket address given by the \f(CW\*(C`sockname\*(C'\fR method).
+.PP
+If \f(CW$numeric\fR is true, these will be given in numeric form rather than being
+resolved into names.
+.PP
+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
+\&\f(CWgetnameinfo(3)\fR only once.
+.SS sockhost
+.IX Subsection "sockhost"
+.Vb 1
+\&   $addr = $sock\->sockhost
+.Ve
+.PP
+Return the numeric form of the local address as a textual representation
+.SS sockport
+.IX Subsection "sockport"
+.Vb 1
+\&   $port = $sock\->sockport
+.Ve
+.PP
+Return the numeric form of the local port number
+.SS sockhostname
+.IX Subsection "sockhostname"
+.Vb 1
+\&   $host = $sock\->sockhostname
+.Ve
+.PP
+Return the resolved name of the local address
+.SS sockservice
+.IX Subsection "sockservice"
+.Vb 1
+\&   $service = $sock\->sockservice
+.Ve
+.PP
+Return the resolved name of the local port number
+.SS sockaddr
+.IX Subsection "sockaddr"
+.Vb 1
+\&   $addr = $sock\->sockaddr
+.Ve
+.PP
+Return the local address as a binary octet string
+.SS peerhost_service
+.IX Subsection "peerhost_service"
+.Vb 1
+\&   ( $host, $service ) = $sock\->peerhost_service( $numeric )
+.Ve
+.PP
+Returns the hostname and service name of the peer address (that is, the
+socket address given by the \f(CW\*(C`peername\*(C'\fR method), similar to the
+\&\f(CW\*(C`sockhost_service\*(C'\fR method.
+.PP
+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
+\&\f(CWgetnameinfo(3)\fR only once.
+.SS peerhost
+.IX Subsection "peerhost"
+.Vb 1
+\&   $addr = $sock\->peerhost
+.Ve
+.PP
+Return the numeric form of the peer address as a textual representation
+.SS peerport
+.IX Subsection "peerport"
+.Vb 1
+\&   $port = $sock\->peerport
+.Ve
+.PP
+Return the numeric form of the peer port number
+.SS peerhostname
+.IX Subsection "peerhostname"
+.Vb 1
+\&   $host = $sock\->peerhostname
+.Ve
+.PP
+Return the resolved name of the peer address
+.SS peerservice
+.IX Subsection "peerservice"
+.Vb 1
+\&   $service = $sock\->peerservice
+.Ve
+.PP
+Return the resolved name of the peer port number
+.SS peeraddr
+.IX Subsection "peeraddr"
+.Vb 1
+\&   $addr = $peer\->peeraddr
+.Ve
+.PP
+Return the peer address as a binary octet string
+.SS as_inet
+.IX Subsection "as_inet"
+.Vb 1
+\&   $inet = $sock\->as_inet
+.Ve
+.PP
+Returns a new IO::Socket::INET instance wrapping the same filehandle. This
+may be useful in cases where it is required, for backward-compatibility, to
+have a real object of \f(CW\*(C`IO::Socket::INET\*(C'\fR type instead of \f(CW\*(C`IO::Socket::IP\*(C'\fR.
+The new object will wrap the same underlying socket filehandle as the
+original, so care should be taken not to continue to use both objects
+concurrently. Ideally the original \f(CW$sock\fR should be discarded after this
+method is called.
+.PP
+This method checks that the socket domain is \f(CW\*(C`PF_INET\*(C'\fR and will throw an
+exception if it isn't.
+.SH NON-BLOCKING
+.IX Header "NON-BLOCKING"
+If the constructor is passed a defined but false value for the \f(CW\*(C`Blocking\*(C'\fR
+argument then the socket is put into non-blocking mode. When in non-blocking
+mode, the socket will not be set up by the time the constructor returns,
+because the underlying \f(CWconnect(2)\fR syscall would otherwise have to block.
+.PP
+The non-blocking behaviour is an extension of the \f(CW\*(C`IO::Socket::INET\*(C'\fR API,
+unique to \f(CW\*(C`IO::Socket::IP\*(C'\fR, because the former does not support multi-homed
+non-blocking connect.
+.PP
+When using non-blocking mode, the caller must repeatedly check for
+writeability on the filehandle (for instance using \f(CW\*(C`select\*(C'\fR or \f(CW\*(C`IO::Poll\*(C'\fR).
+Each time the filehandle is ready to write, the \f(CW\*(C`connect\*(C'\fR method must be
+called, with no arguments. Note that some operating systems, most notably
+\&\f(CW\*(C`MSWin32\*(C'\fR do not report a \f(CWconnect()\fR failure using write-ready; so you must
+also \f(CWselect()\fR for exceptional status.
+.PP
+While \f(CW\*(C`connect\*(C'\fR returns false, the value of \f(CW$!\fR indicates whether it should
+be tried again (by being set to the value \f(CW\*(C`EINPROGRESS\*(C'\fR, or \f(CW\*(C`EWOULDBLOCK\*(C'\fR on
+MSWin32), or whether a permanent error has occurred (e.g. \f(CW\*(C`ECONNREFUSED\*(C'\fR).
+.PP
+Once the socket has been connected to the peer, \f(CW\*(C`connect\*(C'\fR will return true
+and the socket will now be ready to use.
+.PP
+Note that calls to the platform's underlying \f(CWgetaddrinfo(3)\fR function may
+block. If \f(CW\*(C`IO::Socket::IP\*(C'\fR has to perform this lookup, the constructor will
+block even when in non-blocking mode.
+.PP
+To avoid this blocking behaviour, the caller should pass in the result of such
+a lookup using the \f(CW\*(C`PeerAddrInfo\*(C'\fR or \f(CW\*(C`LocalAddrInfo\*(C'\fR arguments. This can be
+achieved by using Net::LibAsyncNS, or the \f(CWgetaddrinfo(3)\fR function can be
+called in a child process.
+.PP
+.Vb 2
+\& use IO::Socket::IP;
+\& use Errno qw( EINPROGRESS EWOULDBLOCK );
+\&
+\& my @peeraddrinfo = ... # Caller must obtain the getaddinfo result here
+\&
+\& my $socket = IO::Socket::IP\->new(
+\&    PeerAddrInfo => \e@peeraddrinfo,
+\&    Blocking     => 0,
+\& ) or die "Cannot construct socket \- $@";
+\&
+\& while( !$socket\->connect and ( $! == EINPROGRESS || $! == EWOULDBLOCK ) ) {
+\&    my $wvec = \*(Aq\*(Aq;
+\&    vec( $wvec, fileno $socket, 1 ) = 1;
+\&    my $evec = \*(Aq\*(Aq;
+\&    vec( $evec, fileno $socket, 1 ) = 1;
+\&
+\&    select( undef, $wvec, $evec, undef ) or die "Cannot select \- $!";
+\& }
+\&
+\& die "Cannot connect \- $!" if $!;
+\&
+\& ...
+.Ve
+.PP
+The example above uses \f(CWselect()\fR, but any similar mechanism should work
+analogously. \f(CW\*(C`IO::Socket::IP\*(C'\fR takes care when creating new socket filehandles
+to preserve the actual file descriptor number, so such techniques as \f(CW\*(C`poll\*(C'\fR
+or \f(CW\*(C`epoll\*(C'\fR should be transparent to its reallocation of a different socket
+underneath, perhaps in order to switch protocol family between \f(CW\*(C`PF_INET\*(C'\fR and
+\&\f(CW\*(C`PF_INET6\*(C'\fR.
+.PP
+For another example using \f(CW\*(C`IO::Poll\*(C'\fR and \f(CW\*(C`Net::LibAsyncNS\*(C'\fR, see the
+\&\fIexamples/nonblocking_libasyncns.pl\fR file in the module distribution.
+.ie n .SH """PeerHost"" AND ""LocalHost"" PARSING"
+.el .SH "\f(CWPeerHost\fP AND \f(CWLocalHost\fP PARSING"
+.IX Header "PeerHost AND LocalHost PARSING"
+To support the \f(CW\*(C`IO::Socket::INET\*(C'\fR API, the host and port information may be
+passed in a single string rather than as two separate arguments.
+.PP
+If either \f(CW\*(C`LocalHost\*(C'\fR or \f(CW\*(C`PeerHost\*(C'\fR (or their \f(CW\*(C`...Addr\*(C'\fR synonyms) have any
+of the following special forms then special parsing is applied.
+.PP
+The value of the \f(CW\*(C`...Host\*(C'\fR argument will be split to give both the hostname
+and port (or service name):
+.PP
+.Vb 3
+\& hostname.example.org:http    # Host name
+\& 192.0.2.1:80                 # IPv4 address
+\& [2001:db8::1]:80             # IPv6 address
+.Ve
+.PP
+In each case, the port or service name (e.g. \f(CW80\fR) is passed as the
+\&\f(CW\*(C`LocalService\*(C'\fR or \f(CW\*(C`PeerService\*(C'\fR argument.
+.PP
+Either of \f(CW\*(C`LocalService\*(C'\fR or \f(CW\*(C`PeerService\*(C'\fR (or their \f(CW\*(C`...Port\*(C'\fR synonyms) can
+be either a service name, a decimal number, or a string containing both a
+service name and number, in a form such as
+.PP
+.Vb 1
+\& http(80)
+.Ve
+.PP
+In this case, the name (\f(CW\*(C`http\*(C'\fR) will be tried first, but if the resolver does
+not understand it then the port number (\f(CW80\fR) will be used instead.
+.PP
+If the \f(CW\*(C`...Host\*(C'\fR argument is in this special form and the corresponding
+\&\f(CW\*(C`...Service\*(C'\fR or \f(CW\*(C`...Port\*(C'\fR argument is also defined, the one parsed from
+the \f(CW\*(C`...Host\*(C'\fR argument will take precedence and the other will be ignored.
+.SS split_addr
+.IX Subsection "split_addr"
+.Vb 1
+\&   ( $host, $port ) = IO::Socket::IP\->split_addr( $addr )
+.Ve
+.PP
+Utility method that provides the parsing functionality described above.
+Returns a 2\-element list, containing either the split hostname and port
+description if it could be parsed, or the given address and \f(CW\*(C`undef\*(C'\fR if it was
+not recognised.
+.PP
+.Vb 2
+\& IO::Socket::IP\->split_addr( "hostname:http" )
+\&                              # ( "hostname",  "http" )
+\&
+\& IO::Socket::IP\->split_addr( "192.0.2.1:80" )
+\&                              # ( "192.0.2.1", "80"   )
+\&
+\& IO::Socket::IP\->split_addr( "[2001:db8::1]:80" )
+\&                              # ( "2001:db8::1", "80" )
+\&
+\& IO::Socket::IP\->split_addr( "something.else" )
+\&                              # ( "something.else", undef )
+.Ve
+.SS join_addr
+.IX Subsection "join_addr"
+.Vb 1
+\&   $addr = IO::Socket::IP\->join_addr( $host, $port )
+.Ve
+.PP
+Utility method that performs the reverse of \f(CW\*(C`split_addr\*(C'\fR, returning a string
+formed by joining the specified host address and port number. The host address
+will be wrapped in \f(CW\*(C`[]\*(C'\fR brackets if required (because it is a raw IPv6
+numeric address).
+.PP
+This can be especially useful when combined with the \f(CW\*(C`sockhost_service\*(C'\fR or
+\&\f(CW\*(C`peerhost_service\*(C'\fR methods.
+.PP
+.Vb 1
+\& say "Connected to ", IO::Socket::IP\->join_addr( $sock\->peerhost_service );
+.Ve
+.ie n .SH """IO::Socket::INET"" INCOMPATIBILITES"
+.el .SH "\f(CWIO::Socket::INET\fP INCOMPATIBILITES"
+.IX Header "IO::Socket::INET INCOMPATIBILITES"
+.IP \(bu 4
+The behaviour enabled by \f(CW\*(C`MultiHomed\*(C'\fR is in fact implemented by
+\&\f(CW\*(C`IO::Socket::IP\*(C'\fR as it is required to correctly support searching for a
+useable address from the results of the \f(CWgetaddrinfo(3)\fR call. The
+constructor will ignore the value of this argument, except if it is defined
+but false. An exception is thrown in this case, because that would request it
+disable the \f(CWgetaddrinfo(3)\fR search behaviour in the first place.
+.IP \(bu 4
+\&\f(CW\*(C`IO::Socket::IP\*(C'\fR implements both the \f(CW\*(C`Blocking\*(C'\fR and \f(CW\*(C`Timeout\*(C'\fR parameters,
+but it implements the interaction of both in a different way.
+.Sp
+In \f(CW\*(C`::INET\*(C'\fR, supplying a timeout overrides the non-blocking behaviour,
+meaning that the \f(CWconnect()\fR operation will still block despite that the
+caller asked for a non-blocking socket. This is not explicitly specified in
+its documentation, nor does this author believe that is a useful behaviour \-
+it appears to come from a quirk of implementation.
+.Sp
+In \f(CW\*(C`::IP\*(C'\fR therefore, the \f(CW\*(C`Blocking\*(C'\fR parameter takes precedence \- if a
+non-blocking socket is requested, no operation will block. The \f(CW\*(C`Timeout\*(C'\fR
+parameter here simply defines the maximum time that a blocking \f(CWconnect()\fR
+call will wait, if it blocks at all.
+.Sp
+In order to specifically obtain the "blocking connect then non-blocking send
+and receive" behaviour of specifying this combination of options to \f(CW\*(C`::INET\*(C'\fR
+when using \f(CW\*(C`::IP\*(C'\fR, perform first a blocking connect, then afterwards turn the
+socket into nonblocking mode.
+.Sp
+.Vb 4
+\& my $sock = IO::Socket::IP\->new(
+\&    PeerHost => $peer,
+\&    Timeout => 20,
+\& ) or die "Cannot connect \- $@";
+\&
+\& $sock\->blocking( 0 );
+.Ve
+.Sp
+This code will behave identically under both \f(CW\*(C`IO::Socket::INET\*(C'\fR and
+\&\f(CW\*(C`IO::Socket::IP\*(C'\fR.
+.SH TODO
+.IX Header "TODO"
+.IP \(bu 4
+Investigate whether \f(CW\*(C`POSIX::dup2\*(C'\fR upsets BSD's \f(CW\*(C`kqueue\*(C'\fR watchers, and if so,
+consider what possible workarounds might be applied.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Paul Evans <leonerd@leonerd.org.uk>