Debian Codegraph @

upstream/debian-unstable/man3/IO::Socket::IP.3perl

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