Debian Codegraph @

upstream/mageia-cauldron/man3pm/IO::Socket::IP.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "IO::Socket::IP 3pm"
61 .TH IO::Socket::IP 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 "IO::Socket::IP" \- Family\-neutral IP socket supporting both IPv4 and IPv6
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use IO::Socket::IP;
72 \&
73 \& my $sock = IO::Socket::IP\->new(
74 \& PeerHost => "www.google.com",
75 \& PeerPort => "http",
76 \& Type => SOCK_STREAM,
77 \& ) or die "Cannot construct socket \- $IO::Socket::errstr";
78 \&
79 \& my $familyname = ( $sock\->sockdomain == PF_INET6 ) ? "IPv6" :
80 \& ( $sock\->sockdomain == PF_INET ) ? "IPv4" :
81 \& "unknown";
82 \&
83 \& printf "Connected to google via %s\en", $familyname;
84 .Ve
85 .SH DESCRIPTION
86 .IX Header "DESCRIPTION"
87 This module provides a protocol\-independent way to use IPv4 and IPv6 sockets,
88 intended as a replacement for IO::Socket::INET. Most constructor arguments
89 and methods are provided in a backward\-compatible way. For a list of known
90 differences, see the \f(CW\*(C`IO::Socket::INET\*(C'\fR INCOMPATIBILITIES section below.
91 .PP
92 It uses the \f(CWgetaddrinfo(3)\fR function to convert hostnames and service names
93 or port numbers into sets of possible addresses to connect to or listen on.
94 This allows it to work for IPv6 where the system supports it, while still
95 falling back to IPv4\-only on systems which don\*(Aqt.
96 .ie n .SH "REPLACING ""IO::Socket"" DEFAULT BEHAVIOUR"
97 .el .SH "REPLACING \f(CWIO::Socket\fP DEFAULT BEHAVIOUR"
98 .IX Header "REPLACING IO::Socket DEFAULT BEHAVIOUR"
99 By placing \f(CW\*(C`\-register\*(C'\fR in the import list to \f(CW\*(C`IO::Socket::IP\*(C'\fR, it will
100 register itself with IO::Socket as the class that handles \f(CW\*(C`PF_INET\*(C'\fR. It
101 will also ask to handle \f(CW\*(C`PF_INET6\*(C'\fR as well, provided that constant is
102 available.
103 .PP
104 Changing \f(CW\*(C`IO::Socket\*(C'\fR\*(Aqs default behaviour means that calling the
105 \&\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
106 \&\f(CW\*(C`Domain\*(C'\fR parameter will yield an \f(CW\*(C`IO::Socket::IP\*(C'\fR object.
107 .PP
108 .Vb 1
109 \& use IO::Socket::IP \-register;
110 \&
111 \& my $sock = IO::Socket\->new(
112 \& Domain => PF_INET6,
113 \& LocalHost => "::1",
114 \& Listen => 1,
115 \& ) or die "Cannot create socket \- $IO::Socket::errstr\en";
116 \&
117 \& print "Created a socket of type " . ref($sock) . "\en";
118 .Ve
119 .PP
120 Note that \f(CW\*(C`\-register\*(C'\fR is a global setting that applies to the entire program;
121 it cannot be applied only for certain callers, removed, or limited by lexical
122 scope.
123 .SH CONSTRUCTORS
124 .IX Header "CONSTRUCTORS"
125 .SS new
126 .IX Subsection "new"
127 .Vb 1
128 \& $sock = IO::Socket::IP\->new( %args )
129 .Ve
130 .PP
131 Creates a new \f(CW\*(C`IO::Socket::IP\*(C'\fR object, containing a newly created socket
132 handle according to the named arguments passed. The recognised arguments are:
133 .IP "PeerHost => STRING" 8
134 .IX Item "PeerHost => STRING"
135 .PD 0
136 .IP "PeerService => STRING" 8
137 .IX Item "PeerService => STRING"
138 .PD
139 Hostname and service name for the peer to \f(CWconnect()\fR to. The service name
140 may be given as a port number, as a decimal string.
141 .IP "PeerAddr => STRING" 8
142 .IX Item "PeerAddr => STRING"
143 .PD 0
144 .IP "PeerPort => STRING" 8
145 .IX Item "PeerPort => STRING"
146 .PD
147 For symmetry with the accessor methods and compatibility with
148 \&\f(CW\*(C`IO::Socket::INET\*(C'\fR, these are accepted as synonyms for \f(CW\*(C`PeerHost\*(C'\fR and
149 \&\f(CW\*(C`PeerService\*(C'\fR respectively.
150 .IP "PeerAddrInfo => ARRAY" 8
151 .IX Item "PeerAddrInfo => ARRAY"
152 Alternate form of specifying the peer to \f(CWconnect()\fR to. This should be an
153 array of the form returned by \f(CW\*(C`Socket::getaddrinfo\*(C'\fR.
154 .Sp
155 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
156 \&\f(CW\*(C`Proto\*(C'\fR arguments.
157 .IP "LocalHost => STRING" 8
158 .IX Item "LocalHost => STRING"
159 .PD 0
160 .IP "LocalService => STRING" 8
161 .IX Item "LocalService => STRING"
162 .PD
163 Hostname and service name for the local address to \f(CWbind()\fR to.
164 .IP "LocalAddr => STRING" 8
165 .IX Item "LocalAddr => STRING"
166 .PD 0
167 .IP "LocalPort => STRING" 8
168 .IX Item "LocalPort => STRING"
169 .PD
170 For symmetry with the accessor methods and compatibility with
171 \&\f(CW\*(C`IO::Socket::INET\*(C'\fR, these are accepted as synonyms for \f(CW\*(C`LocalHost\*(C'\fR and
172 \&\f(CW\*(C`LocalService\*(C'\fR respectively.
173 .IP "LocalAddrInfo => ARRAY" 8
174 .IX Item "LocalAddrInfo => ARRAY"
175 Alternate form of specifying the local address to \f(CWbind()\fR to. This should be
176 an array of the form returned by \f(CW\*(C`Socket::getaddrinfo\*(C'\fR.
177 .Sp
178 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
179 \&\f(CW\*(C`Proto\*(C'\fR arguments.
180 .IP "Family => INT" 8
181 .IX Item "Family => INT"
182 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).
183 Normally this will be left undefined, and \f(CW\*(C`getaddrinfo\*(C'\fR will search using any
184 address family supported by the system.
185 .IP "Type => INT" 8
186 .IX Item "Type => INT"
187 The socket type to pass to \f(CW\*(C`getaddrinfo\*(C'\fR (e.g. \f(CW\*(C`SOCK_STREAM\*(C'\fR,
188 \&\f(CW\*(C`SOCK_DGRAM\*(C'\fR). Normally defined by the caller; if left undefined
189 \&\f(CW\*(C`getaddrinfo\*(C'\fR may attempt to infer the type from the service name.
190 .IP "Proto => STRING or INT" 8
191 .IX Item "Proto => STRING or INT"
192 The IP protocol to use for the socket (e.g. \f(CW\*(Aqtcp\*(Aq\fR, \f(CW\*(C`IPPROTO_TCP\*(C'\fR,
193 \&\f(CW\*(Aqudp\*(Aq\fR,\f(CW\*(C`IPPROTO_UDP\*(C'\fR). Normally this will be left undefined, and either
194 \&\f(CW\*(C`getaddrinfo\*(C'\fR or the kernel will choose an appropriate value. May be given
195 either in string name or numeric form.
196 .IP "GetAddrInfoFlags => INT" 8
197 .IX Item "GetAddrInfoFlags => INT"
198 More flags to pass to the \f(CWgetaddrinfo()\fR function. If not supplied, a
199 default of \f(CW\*(C`AI_ADDRCONFIG\*(C'\fR will be used.
200 .Sp
201 These flags will be combined with \f(CW\*(C`AI_PASSIVE\*(C'\fR if the \f(CW\*(C`Listen\*(C'\fR argument is
202 given. For more information see the documentation about \f(CWgetaddrinfo()\fR in
203 the Socket module.
204 .IP "Listen => INT" 8
205 .IX Item "Listen => INT"
206 If defined, puts the socket into listening mode where new connections can be
207 accepted using the \f(CW\*(C`accept\*(C'\fR method. The value given is used as the
208 \&\f(CWlisten(2)\fR queue size.
209 .IP "ReuseAddr => BOOL" 8
210 .IX Item "ReuseAddr => BOOL"
211 If true, set the \f(CW\*(C`SO_REUSEADDR\*(C'\fR sockopt
212 .IP "ReusePort => BOOL" 8
213 .IX Item "ReusePort => BOOL"
214 If true, set the \f(CW\*(C`SO_REUSEPORT\*(C'\fR sockopt (not all OSes implement this sockopt)
215 .IP "Broadcast => BOOL" 8
216 .IX Item "Broadcast => BOOL"
217 If true, set the \f(CW\*(C`SO_BROADCAST\*(C'\fR sockopt
218 .IP "Sockopts => ARRAY" 8
219 .IX Item "Sockopts => ARRAY"
220 An optional array of other socket options to apply after the three listed
221 above. The value is an ARRAY containing 2\- or 3\-element ARRAYrefs. Each inner
222 array relates to a single option, giving the level and option name, and an
223 optional value. If the value element is missing, it will be given the value of
224 a platform\-sized integer 1 constant (i.e. suitable to enable most of the
225 common boolean options).
226 .Sp
227 For example, both options given below are equivalent to setting \f(CW\*(C`ReuseAddr\*(C'\fR.
228 .Sp
229 .Vb 4
230 \& Sockopts => [
231 \& [ SOL_SOCKET, SO_REUSEADDR ],
232 \& [ SOL_SOCKET, SO_REUSEADDR, pack( "i", 1 ) ],
233 \& ]
234 .Ve
235 .IP "V6Only => BOOL" 8
236 .IX Item "V6Only => BOOL"
237 If defined, set the \f(CW\*(C`IPV6_V6ONLY\*(C'\fR sockopt when creating \f(CW\*(C`PF_INET6\*(C'\fR sockets
238 to the given value. If true, a listening\-mode socket will only listen on the
239 \&\f(CW\*(C`AF_INET6\*(C'\fR addresses; if false it will also accept connections from
240 \&\f(CW\*(C`AF_INET\*(C'\fR addresses.
241 .Sp
242 If not defined, the socket option will not be changed, and default value set
243 by the operating system will apply. For repeatable behaviour across platforms
244 it is recommended this value always be defined for listening\-mode sockets.
245 .Sp
246 Note that not all platforms support disabling this option. Some, at least
247 OpenBSD and MirBSD, will fail with \f(CW\*(C`EINVAL\*(C'\fR if you attempt to disable it.
248 To determine whether it is possible to disable, you may use the class method
249 .Sp
250 .Vb 6
251 \& if( IO::Socket::IP\->CAN_DISABLE_V6ONLY ) {
252 \& ...
253 \& }
254 \& else {
255 \& ...
256 \& }
257 .Ve
258 .Sp
259 If your platform does not support disabling this option but you still want to
260 listen for both \f(CW\*(C`AF_INET\*(C'\fR and \f(CW\*(C`AF_INET6\*(C'\fR connections you will have to create
261 two listening sockets, one bound to each protocol.
262 .IP MultiHomed 8
263 .IX Item "MultiHomed"
264 This \f(CW\*(C`IO::Socket::INET\*(C'\fR\-style argument is ignored, except if it is defined
265 but false. See the \f(CW\*(C`IO::Socket::INET\*(C'\fR INCOMPATIBILITIES section below.
266 .Sp
267 However, the behaviour it enables is always performed by \f(CW\*(C`IO::Socket::IP\*(C'\fR.
268 .IP "Blocking => BOOL" 8
269 .IX Item "Blocking => BOOL"
270 If defined but false, the socket will be set to non\-blocking mode. Otherwise
271 it will default to blocking mode. See the NON\-BLOCKING section below for more
272 detail.
273 .IP "Timeout => NUM" 8
274 .IX Item "Timeout => NUM"
275 If defined, gives a maximum time in seconds to block per \f(CWconnect()\fR call
276 when in blocking mode. If missing, no timeout is applied other than that
277 provided by the underlying operating system. When in non\-blocking mode this
278 parameter is ignored.
279 .Sp
280 Note that if the hostname resolves to multiple address candidates, the same
281 timeout will apply to each connection attempt individually, rather than to the
282 operation as a whole. Further note that the timeout does not apply to the
283 initial hostname resolve operation, if connecting by hostname.
284 .Sp
285 This behaviour is copied inspired by \f(CW\*(C`IO::Socket::INET\*(C'\fR; for more fine
286 grained control over connection timeouts, consider performing a nonblocking
287 connect directly.
288 .PP
289 If neither \f(CW\*(C`Type\*(C'\fR nor \f(CW\*(C`Proto\*(C'\fR hints are provided, a default of
290 \&\f(CW\*(C`SOCK_STREAM\*(C'\fR and \f(CW\*(C`IPPROTO_TCP\*(C'\fR respectively will be set, to maintain
291 compatibility with \f(CW\*(C`IO::Socket::INET\*(C'\fR. Other named arguments that are not
292 recognised are ignored.
293 .PP
294 If neither \f(CW\*(C`Family\*(C'\fR nor any hosts or addresses are passed, nor any
295 \&\f(CW*AddrInfo\fR, then the constructor has no information on which to decide a
296 socket family to create. In this case, it performs a \f(CW\*(C`getaddrinfo\*(C'\fR call with
297 the \f(CW\*(C`AI_ADDRCONFIG\*(C'\fR flag, no host name, and a service name of \f(CW"0"\fR, and
298 uses the family of the first returned result.
299 .PP
300 If the constructor fails, it will set \f(CW$IO::Socket::errstr\fR and \f(CW$@\fR to
301 an appropriate error message; this may be from \f(CW$!\fR or it may be some other
302 string; not every failure necessarily has an associated \f(CW\*(C`errno\*(C'\fR value.
303 .SS "new (one arg)"
304 .IX Subsection "new (one arg)"
305 .Vb 1
306 \& $sock = IO::Socket::IP\->new( $peeraddr )
307 .Ve
308 .PP
309 As a special case, if the constructor is passed a single argument (as
310 opposed to an even\-sized list of key/value pairs), it is taken to be the value
311 of the \f(CW\*(C`PeerAddr\*(C'\fR parameter. This is parsed in the same way, according to the
312 behaviour given in the \f(CW\*(C`PeerHost\*(C'\fR AND \f(CW\*(C`LocalHost\*(C'\fR PARSING section below.
313 .SH METHODS
314 .IX Header "METHODS"
315 As well as the following methods, this class inherits all the methods in
316 IO::Socket and IO::Handle.
317 .SS sockhost_service
318 .IX Subsection "sockhost_service"
319 .Vb 1
320 \& ( $host, $service ) = $sock\->sockhost_service( $numeric );
321 .Ve
322 .PP
323 Returns the hostname and service name of the local address (that is, the
324 socket address given by the \f(CW\*(C`sockname\*(C'\fR method).
325 .PP
326 If \f(CW$numeric\fR is true, these will be given in numeric form rather than being
327 resolved into names.
328 .PP
329 The following four convenience wrappers may be used to obtain one of the two
330 values returned here. If both host and service names are required, this method
331 is preferable to the following wrappers, because it will call
332 \&\f(CWgetnameinfo(3)\fR only once.
333 .SS sockhost
334 .IX Subsection "sockhost"
335 .Vb 1
336 \& $addr = $sock\->sockhost;
337 .Ve
338 .PP
339 Return the numeric form of the local address as a textual representation
340 .SS sockport
341 .IX Subsection "sockport"
342 .Vb 1
343 \& $port = $sock\->sockport;
344 .Ve
345 .PP
346 Return the numeric form of the local port number
347 .SS sockhostname
348 .IX Subsection "sockhostname"
349 .Vb 1
350 \& $host = $sock\->sockhostname;
351 .Ve
352 .PP
353 Return the resolved name of the local address
354 .SS sockservice
355 .IX Subsection "sockservice"
356 .Vb 1
357 \& $service = $sock\->sockservice;
358 .Ve
359 .PP
360 Return the resolved name of the local port number
361 .SS sockaddr
362 .IX Subsection "sockaddr"
363 .Vb 1
364 \& $addr = $sock\->sockaddr;
365 .Ve
366 .PP
367 Return the local address as a binary octet string
368 .SS peerhost_service
369 .IX Subsection "peerhost_service"
370 .Vb 1
371 \& ( $host, $service ) = $sock\->peerhost_service( $numeric );
372 .Ve
373 .PP
374 Returns the hostname and service name of the peer address (that is, the
375 socket address given by the \f(CW\*(C`peername\*(C'\fR method), similar to the
376 \&\f(CW\*(C`sockhost_service\*(C'\fR method.
377 .PP
378 The following four convenience wrappers may be used to obtain one of the two
379 values returned here. If both host and service names are required, this method
380 is preferable to the following wrappers, because it will call
381 \&\f(CWgetnameinfo(3)\fR only once.
382 .SS peerhost
383 .IX Subsection "peerhost"
384 .Vb 1
385 \& $addr = $sock\->peerhost;
386 .Ve
387 .PP
388 Return the numeric form of the peer address as a textual representation
389 .SS peerport
390 .IX Subsection "peerport"
391 .Vb 1
392 \& $port = $sock\->peerport;
393 .Ve
394 .PP
395 Return the numeric form of the peer port number
396 .SS peerhostname
397 .IX Subsection "peerhostname"
398 .Vb 1
399 \& $host = $sock\->peerhostname;
400 .Ve
401 .PP
402 Return the resolved name of the peer address
403 .SS peerservice
404 .IX Subsection "peerservice"
405 .Vb 1
406 \& $service = $sock\->peerservice;
407 .Ve
408 .PP
409 Return the resolved name of the peer port number
410 .SS peeraddr
411 .IX Subsection "peeraddr"
412 .Vb 1
413 \& $addr = $peer\->peeraddr;
414 .Ve
415 .PP
416 Return the peer address as a binary octet string
417 .SS as_inet
418 .IX Subsection "as_inet"
419 .Vb 1
420 \& $inet = $sock\->as_inet;
421 .Ve
422 .PP
423 Returns a new IO::Socket::INET instance wrapping the same filehandle. This
424 may be useful in cases where it is required, for backward\-compatibility, to
425 have a real object of \f(CW\*(C`IO::Socket::INET\*(C'\fR type instead of \f(CW\*(C`IO::Socket::IP\*(C'\fR.
426 The new object will wrap the same underlying socket filehandle as the
427 original, so care should be taken not to continue to use both objects
428 concurrently. Ideally the original \f(CW$sock\fR should be discarded after this
429 method is called.
430 .PP
431 This method checks that the socket domain is \f(CW\*(C`PF_INET\*(C'\fR and will throw an
432 exception if it isn\*(Aqt.
433 .SH NON\-BLOCKING
434 .IX Header "NON-BLOCKING"
435 If the constructor is passed a defined but false value for the \f(CW\*(C`Blocking\*(C'\fR
436 argument then the socket is put into non\-blocking mode. When in non\-blocking
437 mode, the socket will not be set up by the time the constructor returns,
438 because the underlying \f(CWconnect(2)\fR syscall would otherwise have to block.
439 .PP
440 The non\-blocking behaviour is an extension of the \f(CW\*(C`IO::Socket::INET\*(C'\fR API,
441 unique to \f(CW\*(C`IO::Socket::IP\*(C'\fR, because the former does not support multi\-homed
442 non\-blocking connect.
443 .PP
444 When using non\-blocking mode, the caller must repeatedly check for
445 writeability on the filehandle (for instance using \f(CW\*(C`select\*(C'\fR or \f(CW\*(C`IO::Poll\*(C'\fR).
446 Each time the filehandle is ready to write, the \f(CW\*(C`connect\*(C'\fR method must be
447 called, with no arguments. Note that some operating systems, most notably
448 \&\f(CW\*(C`MSWin32\*(C'\fR do not report a \f(CWconnect()\fR failure using write\-ready; so you must
449 also \f(CWselect()\fR for exceptional status.
450 .PP
451 While \f(CW\*(C`connect\*(C'\fR returns false, the value of \f(CW$!\fR indicates whether it should
452 be tried again (by being set to the value \f(CW\*(C`EINPROGRESS\*(C'\fR, or \f(CW\*(C`EWOULDBLOCK\*(C'\fR on
453 MSWin32), or whether a permanent error has occurred (e.g. \f(CW\*(C`ECONNREFUSED\*(C'\fR).
454 .PP
455 Once the socket has been connected to the peer, \f(CW\*(C`connect\*(C'\fR will return true
456 and the socket will now be ready to use.
457 .PP
458 Note that calls to the platform\*(Aqs underlying \f(CWgetaddrinfo(3)\fR function may
459 block. If \f(CW\*(C`IO::Socket::IP\*(C'\fR has to perform this lookup, the constructor will
460 block even when in non\-blocking mode.
461 .PP
462 To avoid this blocking behaviour, the caller should pass in the result of such
463 a lookup using the \f(CW\*(C`PeerAddrInfo\*(C'\fR or \f(CW\*(C`LocalAddrInfo\*(C'\fR arguments. This can be
464 achieved by using Net::LibAsyncNS, or the \f(CWgetaddrinfo(3)\fR function can be
465 called in a child process.
466 .PP
467 .Vb 2
468 \& use IO::Socket::IP;
469 \& use Errno qw( EINPROGRESS EWOULDBLOCK );
470 \&
471 \& my @peeraddrinfo = ... # Caller must obtain the getaddrinfo result here
472 \&
473 \& my $socket = IO::Socket::IP\->new(
474 \& PeerAddrInfo => \e@peeraddrinfo,
475 \& Blocking => 0,
476 \& ) or die "Cannot construct socket \- $@";
477 \&
478 \& while( !$socket\->connect and ( $! == EINPROGRESS || $! == EWOULDBLOCK ) ) {
479 \& my $wvec = \*(Aq\*(Aq;
480 \& vec( $wvec, fileno $socket, 1 ) = 1;
481 \& my $evec = \*(Aq\*(Aq;
482 \& vec( $evec, fileno $socket, 1 ) = 1;
483 \&
484 \& select( undef, $wvec, $evec, undef ) or die "Cannot select \- $!";
485 \& }
486 \&
487 \& die "Cannot connect \- $!" if $!;
488 \&
489 \& ...
490 .Ve
491 .PP
492 The example above uses \f(CWselect()\fR, but any similar mechanism should work
493 analogously. \f(CW\*(C`IO::Socket::IP\*(C'\fR takes care when creating new socket filehandles
494 to preserve the actual file descriptor number, so such techniques as \f(CW\*(C`poll\*(C'\fR
495 or \f(CW\*(C`epoll\*(C'\fR should be transparent to its reallocation of a different socket
496 underneath, perhaps in order to switch protocol family between \f(CW\*(C`PF_INET\*(C'\fR and
497 \&\f(CW\*(C`PF_INET6\*(C'\fR.
498 .PP
499 For another example using \f(CW\*(C`IO::Poll\*(C'\fR and \f(CW\*(C`Net::LibAsyncNS\*(C'\fR, see the
500 \&\fIexamples/nonblocking_libasyncns.pl\fR file in the module distribution.
501 .ie n .SH """PeerHost"" AND ""LocalHost"" PARSING"
502 .el .SH "\f(CWPeerHost\fP AND \f(CWLocalHost\fP PARSING"
503 .IX Header "PeerHost AND LocalHost PARSING"
504 To support the \f(CW\*(C`IO::Socket::INET\*(C'\fR API, the host and port information may be
505 passed in a single string rather than as two separate arguments.
506 .PP
507 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
508 of the following special forms then special parsing is applied.
509 .PP
510 The value of the \f(CW\*(C`...Host\*(C'\fR argument will be split to give both the hostname
511 and port (or service name):
512 .PP
513 .Vb 3
514 \& hostname.example.org:http # Host name
515 \& 192.0.2.1:80 # IPv4 address
516 \& [2001:db8::1]:80 # IPv6 address
517 .Ve
518 .PP
519 In each case, the port or service name (e.g. \f(CW80\fR) is passed as the
520 \&\f(CW\*(C`LocalService\*(C'\fR or \f(CW\*(C`PeerService\*(C'\fR argument.
521 .PP
522 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
523 be either a service name, a decimal number, or a string containing both a
524 service name and number, in a form such as
525 .PP
526 .Vb 1
527 \& http(80)
528 .Ve
529 .PP
530 In this case, the name (\f(CW\*(C`http\*(C'\fR) will be tried first, but if the resolver does
531 not understand it then the port number (\f(CW80\fR) will be used instead.
532 .PP
533 If the \f(CW\*(C`...Host\*(C'\fR argument is in this special form and the corresponding
534 \&\f(CW\*(C`...Service\*(C'\fR or \f(CW\*(C`...Port\*(C'\fR argument is also defined, the one parsed from
535 the \f(CW\*(C`...Host\*(C'\fR argument will take precedence and the other will be ignored.
536 .SS split_addr
537 .IX Subsection "split_addr"
538 .Vb 1
539 \& ( $host, $port ) = IO::Socket::IP\->split_addr( $addr )
540 .Ve
541 .PP
542 Utility method that provides the parsing functionality described above.
543 Returns a 2\-element list, containing either the split hostname and port
544 description if it could be parsed, or the given address and \f(CW\*(C`undef\*(C'\fR if it was
545 not recognised.
546 .PP
547 .Vb 2
548 \& IO::Socket::IP\->split_addr( "hostname:http" );
549 \& # ( "hostname", "http" )
550 \&
551 \& IO::Socket::IP\->split_addr( "192.0.2.1:80" );
552 \& # ( "192.0.2.1", "80" )
553 \&
554 \& IO::Socket::IP\->split_addr( "[2001:db8::1]:80" );
555 \& # ( "2001:db8::1", "80" )
556 \&
557 \& IO::Socket::IP\->split_addr( "something.else" );
558 \& # ( "something.else", undef )
559 .Ve
560 .SS join_addr
561 .IX Subsection "join_addr"
562 .Vb 1
563 \& $addr = IO::Socket::IP\->join_addr( $host, $port )
564 .Ve
565 .PP
566 Utility method that performs the reverse of \f(CW\*(C`split_addr\*(C'\fR, returning a string
567 formed by joining the specified host address and port number. The host address
568 will be wrapped in \f(CW\*(C`[]\*(C'\fR brackets if required (because it is a raw IPv6
569 numeric address).
570 .PP
571 This can be especially useful when combined with the \f(CW\*(C`sockhost_service\*(C'\fR or
572 \&\f(CW\*(C`peerhost_service\*(C'\fR methods.
573 .PP
574 .Vb 1
575 \& say "Connected to ", IO::Socket::IP\->join_addr( $sock\->peerhost_service );
576 .Ve
577 .ie n .SH """IO::Socket::INET"" INCOMPATIBILITIES"
578 .el .SH "\f(CWIO::Socket::INET\fP INCOMPATIBILITIES"
579 .IX Header "IO::Socket::INET INCOMPATIBILITIES"
580 .IP \(bu 4
581 The behaviour enabled by \f(CW\*(C`MultiHomed\*(C'\fR is in fact implemented by
582 \&\f(CW\*(C`IO::Socket::IP\*(C'\fR as it is required to correctly support searching for a
583 useable address from the results of the \f(CWgetaddrinfo(3)\fR call. The
584 constructor will ignore the value of this argument, except if it is defined
585 but false. An exception is thrown in this case, because that would request it
586 disable the \f(CWgetaddrinfo(3)\fR search behaviour in the first place.
587 .IP \(bu 4
588 \&\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,
589 but it implements the interaction of both in a different way.
590 .Sp
591 In \f(CW\*(C`::INET\*(C'\fR, supplying a timeout overrides the non\-blocking behaviour,
592 meaning that the \f(CWconnect()\fR operation will still block despite that the
593 caller asked for a non\-blocking socket. This is not explicitly specified in
594 its documentation, nor does this author believe that is a useful behaviour \-
595 it appears to come from a quirk of implementation.
596 .Sp
597 In \f(CW\*(C`::IP\*(C'\fR therefore, the \f(CW\*(C`Blocking\*(C'\fR parameter takes precedence \- if a
598 non\-blocking socket is requested, no operation will block. The \f(CW\*(C`Timeout\*(C'\fR
599 parameter here simply defines the maximum time that a blocking \f(CWconnect()\fR
600 call will wait, if it blocks at all.
601 .Sp
602 In order to specifically obtain the "blocking connect then non\-blocking send
603 and receive" behaviour of specifying this combination of options to \f(CW\*(C`::INET\*(C'\fR
604 when using \f(CW\*(C`::IP\*(C'\fR, perform first a blocking connect, then afterwards turn the
605 socket into nonblocking mode.
606 .Sp
607 .Vb 4
608 \& my $sock = IO::Socket::IP\->new(
609 \& PeerHost => $peer,
610 \& Timeout => 20,
611 \& ) or die "Cannot connect \- $@";
612 \&
613 \& $sock\->blocking( 0 );
614 .Ve
615 .Sp
616 This code will behave identically under both \f(CW\*(C`IO::Socket::INET\*(C'\fR and
617 \&\f(CW\*(C`IO::Socket::IP\*(C'\fR.
618 .SH TODO
619 .IX Header "TODO"
620 .IP \(bu 4
621 Investigate whether \f(CW\*(C`POSIX::dup2\*(C'\fR upsets BSD\*(Aqs \f(CW\*(C`kqueue\*(C'\fR watchers, and if so,
622 consider what possible workarounds might be applied.
623 .SH AUTHOR
624 .IX Header "AUTHOR"
625 Paul Evans <[email protected]>