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