Update Socket to CPAN version 2.025
[perl.git] / cpan / Socket / Socket.pm
1 package Socket;
2
3 use strict;
4 { use 5.006001; }
5
6 our $VERSION = '2.025';
7
8 =head1 NAME
9
10 C<Socket> - networking constants and support functions
11
12 =head1 SYNOPSIS
13
14 C<Socket> a low-level module used by, among other things, the L<IO::Socket>
15 family of modules. The following examples demonstrate some low-level uses but
16 a practical program would likely use the higher-level API provided by
17 C<IO::Socket> or similar instead.
18
19  use Socket qw(PF_INET SOCK_STREAM pack_sockaddr_in inet_aton);
20
21  socket(my $socket, PF_INET, SOCK_STREAM, 0)
22      or die "socket: $!";
23
24  my $port = getservbyname "echo", "tcp";
25  connect($socket, pack_sockaddr_in($port, inet_aton("localhost")))
26      or die "connect: $!";
27
28  print $socket "Hello, world!\n";
29  print <$socket>;
30
31 See also the L</EXAMPLES> section.
32
33 =head1 DESCRIPTION
34
35 This module provides a variety of constants, structure manipulators and other
36 functions related to socket-based networking. The values and functions
37 provided are useful when used in conjunction with Perl core functions such as
38 socket(), setsockopt() and bind(). It also provides several other support
39 functions, mostly for dealing with conversions of network addresses between
40 human-readable and native binary forms, and for hostname resolver operations.
41
42 Some constants and functions are exported by default by this module; but for
43 backward-compatibility any recently-added symbols are not exported by default
44 and must be requested explicitly. When an import list is provided to the
45 C<use Socket> line, the default exports are not automatically imported. It is
46 therefore best practice to always to explicitly list all the symbols required.
47
48 Also, some common socket "newline" constants are provided: the constants
49 C<CR>, C<LF>, and C<CRLF>, as well as C<$CR>, C<$LF>, and C<$CRLF>, which map
50 to C<\015>, C<\012>, and C<\015\012>. If you do not want to use the literal
51 characters in your programs, then use the constants provided here. They are
52 not exported by default, but can be imported individually, and with the
53 C<:crlf> export tag:
54
55  use Socket qw(:DEFAULT :crlf);
56
57  $sock->print("GET / HTTP/1.0$CRLF");
58
59 The entire getaddrinfo() subsystem can be exported using the tag C<:addrinfo>;
60 this exports the getaddrinfo() and getnameinfo() functions, and all the
61 C<AI_*>, C<NI_*>, C<NIx_*> and C<EAI_*> constants.
62
63 =cut
64
65 =head1 CONSTANTS
66
67 In each of the following groups, there may be many more constants provided
68 than just the ones given as examples in the section heading. If the heading
69 ends C<...> then this means there are likely more; the exact constants
70 provided will depend on the OS and headers found at compile-time.
71
72 =cut
73
74 =head2 PF_INET, PF_INET6, PF_UNIX, ...
75
76 Protocol family constants to use as the first argument to socket() or the
77 value of the C<SO_DOMAIN> or C<SO_FAMILY> socket option.
78
79 =head2 AF_INET, AF_INET6, AF_UNIX, ...
80
81 Address family constants used by the socket address structures, to pass to
82 such functions as inet_pton() or getaddrinfo(), or are returned by such
83 functions as sockaddr_family().
84
85 =head2 SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, ...
86
87 Socket type constants to use as the second argument to socket(), or the value
88 of the C<SO_TYPE> socket option.
89
90 =head2 SOCK_NONBLOCK. SOCK_CLOEXEC
91
92 Linux-specific shortcuts to specify the C<O_NONBLOCK> and C<FD_CLOEXEC> flags
93 during a C<socket(2)> call.
94
95  socket( my $sockh, PF_INET, SOCK_DGRAM|SOCK_NONBLOCK, 0 )
96
97 =head2 SOL_SOCKET
98
99 Socket option level constant for setsockopt() and getsockopt().
100
101 =head2 SO_ACCEPTCONN, SO_BROADCAST, SO_ERROR, ...
102
103 Socket option name constants for setsockopt() and getsockopt() at the
104 C<SOL_SOCKET> level.
105
106 =head2 IP_OPTIONS, IP_TOS, IP_TTL, ...
107
108 Socket option name constants for IPv4 socket options at the C<IPPROTO_IP>
109 level.
110
111 =head2 IP_PMTUDISC_WANT, IP_PMTUDISC_DONT, ...
112
113 Socket option value contants for C<IP_MTU_DISCOVER> socket option.
114
115 =head2 IPTOS_LOWDELAY, IPTOS_THROUGHPUT, IPTOS_RELIABILITY, ...
116
117 Socket option value constants for C<IP_TOS> socket option.
118
119 =head2 MSG_BCAST, MSG_OOB, MSG_TRUNC, ...
120
121 Message flag constants for send() and recv().
122
123 =head2 SHUT_RD, SHUT_RDWR, SHUT_WR
124
125 Direction constants for shutdown().
126
127 =head2 INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_NONE
128
129 Constants giving the special C<AF_INET> addresses for wildcard, broadcast,
130 local loopback, and invalid addresses.
131
132 Normally equivalent to inet_aton('0.0.0.0'), inet_aton('255.255.255.255'),
133 inet_aton('localhost') and inet_aton('255.255.255.255') respectively.
134
135 =head2 IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP, ...
136
137 IP protocol constants to use as the third argument to socket(), the level
138 argument to getsockopt() or setsockopt(), or the value of the C<SO_PROTOCOL>
139 socket option.
140
141 =head2 TCP_CORK, TCP_KEEPALIVE, TCP_NODELAY, ...
142
143 Socket option name constants for TCP socket options at the C<IPPROTO_TCP>
144 level.
145
146 =head2 IN6ADDR_ANY, IN6ADDR_LOOPBACK
147
148 Constants giving the special C<AF_INET6> addresses for wildcard and local
149 loopback.
150
151 Normally equivalent to inet_pton(AF_INET6, "::") and
152 inet_pton(AF_INET6, "::1") respectively.
153
154 =head2 IPV6_ADD_MEMBERSHIP, IPV6_MTU, IPV6_V6ONLY, ...
155
156 Socket option name constants for IPv6 socket options at the C<IPPROTO_IPV6>
157 level.
158
159 =cut
160
161 # Still undocumented: SCM_*, SOMAXCONN, IOV_MAX, UIO_MAXIOV
162
163 =head1 STRUCTURE MANIPULATORS
164
165 The following functions convert between lists of Perl values and packed binary
166 strings representing structures.
167
168 =cut
169
170 =head2 $family = sockaddr_family $sockaddr
171
172 Takes a packed socket address (as returned by pack_sockaddr_in(),
173 pack_sockaddr_un() or the perl builtin functions getsockname() and
174 getpeername()). Returns the address family tag. This will be one of the
175 C<AF_*> constants, such as C<AF_INET> for a C<sockaddr_in> addresses or
176 C<AF_UNIX> for a C<sockaddr_un>. It can be used to figure out what unpack to
177 use for a sockaddr of unknown type.
178
179 =head2 $sockaddr = pack_sockaddr_in $port, $ip_address
180
181 Takes two arguments, a port number and an opaque string (as returned by
182 inet_aton(), or a v-string). Returns the C<sockaddr_in> structure with those
183 arguments packed in and C<AF_INET> filled in. For Internet domain sockets,
184 this structure is normally what you need for the arguments in bind(),
185 connect(), and send().
186
187 An undefined $port argument is taken as zero; an undefined $ip_address is
188 considered a fatal error.
189
190 =head2 ($port, $ip_address) = unpack_sockaddr_in $sockaddr
191
192 Takes a C<sockaddr_in> structure (as returned by pack_sockaddr_in(),
193 getpeername() or recv()). Returns a list of two elements: the port and an
194 opaque string representing the IP address (you can use inet_ntoa() to convert
195 the address to the four-dotted numeric format). Will croak if the structure
196 does not represent an C<AF_INET> address.
197
198 In scalar context will return just the IP address.
199
200 =head2 $sockaddr = sockaddr_in $port, $ip_address
201
202 =head2 ($port, $ip_address) = sockaddr_in $sockaddr
203
204 A wrapper of pack_sockaddr_in() or unpack_sockaddr_in(). In list context,
205 unpacks its argument and returns a list consisting of the port and IP address.
206 In scalar context, packs its port and IP address arguments as a C<sockaddr_in>
207 and returns it.
208
209 Provided largely for legacy compatibility; it is better to use
210 pack_sockaddr_in() or unpack_sockaddr_in() explicitly.
211
212 =head2 $sockaddr = pack_sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]
213
214 Takes two to four arguments, a port number, an opaque string (as returned by
215 inet_pton()), optionally a scope ID number, and optionally a flow label
216 number. Returns the C<sockaddr_in6> structure with those arguments packed in
217 and C<AF_INET6> filled in. IPv6 equivalent of pack_sockaddr_in().
218
219 An undefined $port argument is taken as zero; an undefined $ip6_address is
220 considered a fatal error.
221
222 =head2 ($port, $ip6_address, $scope_id, $flowinfo) = unpack_sockaddr_in6 $sockaddr
223
224 Takes a C<sockaddr_in6> structure. Returns a list of four elements: the port
225 number, an opaque string representing the IPv6 address, the scope ID, and the
226 flow label. (You can use inet_ntop() to convert the address to the usual
227 string format). Will croak if the structure does not represent an C<AF_INET6>
228 address.
229
230 In scalar context will return just the IP address.
231
232 =head2 $sockaddr = sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]
233
234 =head2 ($port, $ip6_address, $scope_id, $flowinfo) = sockaddr_in6 $sockaddr
235
236 A wrapper of pack_sockaddr_in6() or unpack_sockaddr_in6(). In list context,
237 unpacks its argument according to unpack_sockaddr_in6(). In scalar context,
238 packs its arguments according to pack_sockaddr_in6().
239
240 Provided largely for legacy compatibility; it is better to use
241 pack_sockaddr_in6() or unpack_sockaddr_in6() explicitly.
242
243 =head2 $sockaddr = pack_sockaddr_un $path
244
245 Takes one argument, a pathname. Returns the C<sockaddr_un> structure with that
246 path packed in with C<AF_UNIX> filled in. For C<PF_UNIX> sockets, this
247 structure is normally what you need for the arguments in bind(), connect(),
248 and send().
249
250 =head2 ($path) = unpack_sockaddr_un $sockaddr
251
252 Takes a C<sockaddr_un> structure (as returned by pack_sockaddr_un(),
253 getpeername() or recv()). Returns a list of one element: the pathname. Will
254 croak if the structure does not represent an C<AF_UNIX> address.
255
256 =head2 $sockaddr = sockaddr_un $path
257
258 =head2 ($path) = sockaddr_un $sockaddr
259
260 A wrapper of pack_sockaddr_un() or unpack_sockaddr_un(). In a list context,
261 unpacks its argument and returns a list consisting of the pathname. In a
262 scalar context, packs its pathname as a C<sockaddr_un> and returns it.
263
264 Provided largely for legacy compatibility; it is better to use
265 pack_sockaddr_un() or unpack_sockaddr_un() explicitly.
266
267 These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
268
269 =head2 $ip_mreq = pack_ip_mreq $multiaddr, $interface
270
271 Takes an IPv4 multicast address and optionally an interface address (or
272 C<INADDR_ANY>). Returns the C<ip_mreq> structure with those arguments packed
273 in. Suitable for use with the C<IP_ADD_MEMBERSHIP> and C<IP_DROP_MEMBERSHIP>
274 sockopts.
275
276 =head2 ($multiaddr, $interface) = unpack_ip_mreq $ip_mreq
277
278 Takes an C<ip_mreq> structure. Returns a list of two elements; the IPv4
279 multicast address and interface address.
280
281 =head2 $ip_mreq_source = pack_ip_mreq_source $multiaddr, $source, $interface
282
283 Takes an IPv4 multicast address, source address, and optionally an interface
284 address (or C<INADDR_ANY>). Returns the C<ip_mreq_source> structure with those
285 arguments packed in. Suitable for use with the C<IP_ADD_SOURCE_MEMBERSHIP>
286 and C<IP_DROP_SOURCE_MEMBERSHIP> sockopts.
287
288 =head2 ($multiaddr, $source, $interface) = unpack_ip_mreq_source $ip_mreq
289
290 Takes an C<ip_mreq_source> structure. Returns a list of three elements; the
291 IPv4 multicast address, source address and interface address.
292
293 =head2 $ipv6_mreq = pack_ipv6_mreq $multiaddr6, $ifindex
294
295 Takes an IPv6 multicast address and an interface number. Returns the
296 C<ipv6_mreq> structure with those arguments packed in. Suitable for use with
297 the C<IPV6_ADD_MEMBERSHIP> and C<IPV6_DROP_MEMBERSHIP> sockopts.
298
299 =head2 ($multiaddr6, $ifindex) = unpack_ipv6_mreq $ipv6_mreq
300
301 Takes an C<ipv6_mreq> structure. Returns a list of two elements; the IPv6
302 address and an interface number.
303
304 =cut
305
306 =head1 FUNCTIONS
307
308 =cut
309
310 =head2 $ip_address = inet_aton $string
311
312 Takes a string giving the name of a host, or a textual representation of an IP
313 address and translates that to an packed binary address structure suitable to
314 pass to pack_sockaddr_in(). If passed a hostname that cannot be resolved,
315 returns C<undef>. For multi-homed hosts (hosts with more than one address),
316 the first address found is returned.
317
318 For portability do not assume that the result of inet_aton() is 32 bits wide,
319 in other words, that it would contain only the IPv4 address in network order.
320
321 This IPv4-only function is provided largely for legacy reasons. Newly-written
322 code should use getaddrinfo() or inet_pton() instead for IPv6 support.
323
324 =head2 $string = inet_ntoa $ip_address
325
326 Takes a packed binary address structure such as returned by
327 unpack_sockaddr_in() (or a v-string representing the four octets of the IPv4
328 address in network order) and translates it into a string of the form
329 C<d.d.d.d> where the C<d>s are numbers less than 256 (the normal
330 human-readable four dotted number notation for Internet addresses).
331
332 This IPv4-only function is provided largely for legacy reasons. Newly-written
333 code should use getnameinfo() or inet_ntop() instead for IPv6 support.
334
335 =head2 $address = inet_pton $family, $string
336
337 Takes an address family (such as C<AF_INET> or C<AF_INET6>) and a string
338 containing a textual representation of an address in that family and
339 translates that to an packed binary address structure.
340
341 See also getaddrinfo() for a more powerful and flexible function to look up
342 socket addresses given hostnames or textual addresses.
343
344 =head2 $string = inet_ntop $family, $address
345
346 Takes an address family and a packed binary address structure and translates
347 it into a human-readable textual representation of the address; typically in
348 C<d.d.d.d> form for C<AF_INET> or C<hhhh:hhhh::hhhh> form for C<AF_INET6>.
349
350 See also getnameinfo() for a more powerful and flexible function to turn
351 socket addresses into human-readable textual representations.
352
353 =head2 ($err, @result) = getaddrinfo $host, $service, [$hints]
354
355 Given both a hostname and service name, this function attempts to resolve the
356 host name into a list of network addresses, and the service name into a
357 protocol and port number, and then returns a list of address structures
358 suitable to connect() to it.
359
360 Given just a host name, this function attempts to resolve it to a list of
361 network addresses, and then returns a list of address structures giving these
362 addresses.
363
364 Given just a service name, this function attempts to resolve it to a protocol
365 and port number, and then returns a list of address structures that represent
366 it suitable to bind() to. This use should be combined with the C<AI_PASSIVE>
367 flag; see below.
368
369 Given neither name, it generates an error.
370
371 If present, $hints should be a reference to a hash, where the following keys
372 are recognised:
373
374 =over 4
375
376 =item flags => INT
377
378 A bitfield containing C<AI_*> constants; see below.
379
380 =item family => INT
381
382 Restrict to only generating addresses in this address family
383
384 =item socktype => INT
385
386 Restrict to only generating addresses of this socket type
387
388 =item protocol => INT
389
390 Restrict to only generating addresses for this protocol
391
392 =back
393
394 The return value will be a list; the first value being an error indication,
395 followed by a list of address structures (if no error occurred).
396
397 The error value will be a dualvar; comparable to the C<EAI_*> error constants,
398 or printable as a human-readable error message string. If no error occurred it
399 will be zero numerically and an empty string.
400
401 Each value in the results list will be a hash reference containing the following
402 fields:
403
404 =over 4
405
406 =item family => INT
407
408 The address family (e.g. C<AF_INET>)
409
410 =item socktype => INT
411
412 The socket type (e.g. C<SOCK_STREAM>)
413
414 =item protocol => INT
415
416 The protocol (e.g. C<IPPROTO_TCP>)
417
418 =item addr => STRING
419
420 The address in a packed string (such as would be returned by
421 pack_sockaddr_in())
422
423 =item canonname => STRING
424
425 The canonical name for the host if the C<AI_CANONNAME> flag was provided, or
426 C<undef> otherwise. This field will only be present on the first returned
427 address.
428
429 =back
430
431 The following flag constants are recognised in the $hints hash. Other flag
432 constants may exist as provided by the OS.
433
434 =over 4
435
436 =item AI_PASSIVE
437
438 Indicates that this resolution is for a local bind() for a passive (i.e.
439 listening) socket, rather than an active (i.e. connecting) socket.
440
441 =item AI_CANONNAME
442
443 Indicates that the caller wishes the canonical hostname (C<canonname>) field
444 of the result to be filled in.
445
446 =item AI_NUMERICHOST
447
448 Indicates that the caller will pass a numeric address, rather than a hostname,
449 and that getaddrinfo() must not perform a resolve operation on this name. This
450 flag will prevent a possibly-slow network lookup operation, and instead return
451 an error if a hostname is passed.
452
453 =back
454
455 =head2 ($err, $hostname, $servicename) = getnameinfo $sockaddr, [$flags, [$xflags]]
456
457 Given a packed socket address (such as from getsockname(), getpeername(), or
458 returned by getaddrinfo() in a C<addr> field), returns the hostname and
459 symbolic service name it represents. $flags may be a bitmask of C<NI_*>
460 constants, or defaults to 0 if unspecified.
461
462 The return value will be a list; the first value being an error condition,
463 followed by the hostname and service name.
464
465 The error value will be a dualvar; comparable to the C<EAI_*> error constants,
466 or printable as a human-readable error message string. The host and service
467 names will be plain strings.
468
469 The following flag constants are recognised as $flags. Other flag constants may
470 exist as provided by the OS.
471
472 =over 4
473
474 =item NI_NUMERICHOST
475
476 Requests that a human-readable string representation of the numeric address be
477 returned directly, rather than performing a name resolve operation that may
478 convert it into a hostname. This will also avoid potentially-blocking network
479 IO.
480
481 =item NI_NUMERICSERV
482
483 Requests that the port number be returned directly as a number representation
484 rather than performing a name resolve operation that may convert it into a
485 service name.
486
487 =item NI_NAMEREQD
488
489 If a name resolve operation fails to provide a name, then this flag will cause
490 getnameinfo() to indicate an error, rather than returning the numeric
491 representation as a human-readable string.
492
493 =item NI_DGRAM
494
495 Indicates that the socket address relates to a C<SOCK_DGRAM> socket, for the
496 services whose name differs between TCP and UDP protocols.
497
498 =back
499
500 The following constants may be supplied as $xflags.
501
502 =over 4
503
504 =item NIx_NOHOST
505
506 Indicates that the caller is not interested in the hostname of the result, so
507 it does not have to be converted. C<undef> will be returned as the hostname.
508
509 =item NIx_NOSERV
510
511 Indicates that the caller is not interested in the service name of the result,
512 so it does not have to be converted. C<undef> will be returned as the service
513 name.
514
515 =back
516
517 =head1 getaddrinfo() / getnameinfo() ERROR CONSTANTS
518
519 The following constants may be returned by getaddrinfo() or getnameinfo().
520 Others may be provided by the OS.
521
522 =over 4
523
524 =item EAI_AGAIN
525
526 A temporary failure occurred during name resolution. The operation may be
527 successful if it is retried later.
528
529 =item EAI_BADFLAGS
530
531 The value of the C<flags> hint to getaddrinfo(), or the $flags parameter to
532 getnameinfo() contains unrecognised flags.
533
534 =item EAI_FAMILY
535
536 The C<family> hint to getaddrinfo(), or the family of the socket address
537 passed to getnameinfo() is not supported.
538
539 =item EAI_NODATA
540
541 The host name supplied to getaddrinfo() did not provide any usable address
542 data.
543
544 =item EAI_NONAME
545
546 The host name supplied to getaddrinfo() does not exist, or the address
547 supplied to getnameinfo() is not associated with a host name and the
548 C<NI_NAMEREQD> flag was supplied.
549
550 =item EAI_SERVICE
551
552 The service name supplied to getaddrinfo() is not available for the socket
553 type given in the $hints.
554
555 =back
556
557 =cut
558
559 =head1 EXAMPLES
560
561 =head2 Lookup for connect()
562
563 The getaddrinfo() function converts a hostname and a service name into a list
564 of structures, each containing a potential way to connect() to the named
565 service on the named host.
566
567  use IO::Socket;
568  use Socket qw(SOCK_STREAM getaddrinfo);
569
570  my %hints = (socktype => SOCK_STREAM);
571  my ($err, @res) = getaddrinfo("localhost", "echo", \%hints);
572  die "Cannot getaddrinfo - $err" if $err;
573
574  my $sock;
575
576  foreach my $ai (@res) {
577      my $candidate = IO::Socket->new();
578
579      $candidate->socket($ai->{family}, $ai->{socktype}, $ai->{protocol})
580          or next;
581
582      $candidate->connect($ai->{addr})
583          or next;
584
585      $sock = $candidate;
586      last;
587  }
588
589  die "Cannot connect to localhost:echo" unless $sock;
590
591  $sock->print("Hello, world!\n");
592  print <$sock>;
593
594 Because a list of potential candidates is returned, the C<while> loop tries
595 each in turn until it finds one that succeeds both the socket() and connect()
596 calls.
597
598 This function performs the work of the legacy functions gethostbyname(),
599 getservbyname(), inet_aton() and pack_sockaddr_in().
600
601 In practice this logic is better performed by L<IO::Socket::IP>.
602
603 =head2 Making a human-readable string out of an address
604
605 The getnameinfo() function converts a socket address, such as returned by
606 getsockname() or getpeername(), into a pair of human-readable strings
607 representing the address and service name.
608
609  use IO::Socket::IP;
610  use Socket qw(getnameinfo);
611
612  my $server = IO::Socket::IP->new(LocalPort => 12345, Listen => 1) or
613      die "Cannot listen - $@";
614
615  my $socket = $server->accept or die "accept: $!";
616
617  my ($err, $hostname, $servicename) = getnameinfo($socket->peername);
618  die "Cannot getnameinfo - $err" if $err;
619
620  print "The peer is connected from $hostname\n";
621
622 Since in this example only the hostname was used, the redundant conversion of
623 the port number into a service name may be omitted by passing the
624 C<NIx_NOSERV> flag.
625
626  use Socket qw(getnameinfo NIx_NOSERV);
627
628  my ($err, $hostname) = getnameinfo($socket->peername, 0, NIx_NOSERV);
629
630 This function performs the work of the legacy functions unpack_sockaddr_in(),
631 inet_ntoa(), gethostbyaddr() and getservbyport().
632
633 In practice this logic is better performed by L<IO::Socket::IP>.
634
635 =head2 Resolving hostnames into IP addresses
636
637 To turn a hostname into a human-readable plain IP address use getaddrinfo()
638 to turn the hostname into a list of socket structures, then getnameinfo() on
639 each one to make it a readable IP address again.
640
641  use Socket qw(:addrinfo SOCK_RAW);
642
643  my ($err, @res) = getaddrinfo($hostname, "", {socktype => SOCK_RAW});
644  die "Cannot getaddrinfo - $err" if $err;
645
646  while( my $ai = shift @res ) {
647      my ($err, $ipaddr) = getnameinfo($ai->{addr}, NI_NUMERICHOST, NIx_NOSERV);
648      die "Cannot getnameinfo - $err" if $err;
649
650      print "$ipaddr\n";
651  }
652
653 The C<socktype> hint to getaddrinfo() filters the results to only include one
654 socket type and protocol. Without this most OSes return three combinations,
655 for C<SOCK_STREAM>, C<SOCK_DGRAM> and C<SOCK_RAW>, resulting in triplicate
656 output of addresses. The C<NI_NUMERICHOST> flag to getnameinfo() causes it to
657 return a string-formatted plain IP address, rather than reverse resolving it
658 back into a hostname.
659
660 This combination performs the work of the legacy functions gethostbyname()
661 and inet_ntoa().
662
663 =head2 Accessing socket options
664
665 The many C<SO_*> and other constants provide the socket option names for
666 getsockopt() and setsockopt().
667
668  use IO::Socket::INET;
669  use Socket qw(SOL_SOCKET SO_RCVBUF IPPROTO_IP IP_TTL);
670
671  my $socket = IO::Socket::INET->new(LocalPort => 0, Proto => 'udp')
672      or die "Cannot create socket: $@";
673
674  $socket->setsockopt(SOL_SOCKET, SO_RCVBUF, 64*1024) or
675      die "setsockopt: $!";
676
677  print "Receive buffer is ", $socket->getsockopt(SOL_SOCKET, SO_RCVBUF),
678      " bytes\n";
679
680  print "IP TTL is ", $socket->getsockopt(IPPROTO_IP, IP_TTL), "\n";
681
682 As a convenience, L<IO::Socket>'s setsockopt() method will convert a number
683 into a packed byte buffer, and getsockopt() will unpack a byte buffer of the
684 correct size back into a number.
685
686 =cut
687
688 =head1 AUTHOR
689
690 This module was originally maintained in Perl core by the Perl 5 Porters.
691
692 It was extracted to dual-life on CPAN at version 1.95 by
693 Paul Evans <leonerd@leonerd.org.uk>
694
695 =cut
696
697 use Carp;
698 use warnings::register;
699
700 require Exporter;
701 require XSLoader;
702 our @ISA = qw(Exporter);
703
704 # <@Nicholas> you can't change @EXPORT without breaking the implicit API
705 # Please put any new constants in @EXPORT_OK!
706
707 # List re-ordered to match documentation above. Try to keep the ordering
708 # consistent so it's easier to see which ones are or aren't documented.
709 our @EXPORT = qw(
710         PF_802 PF_AAL PF_APPLETALK PF_CCITT PF_CHAOS PF_CTF PF_DATAKIT
711         PF_DECnet PF_DLI PF_ECMA PF_GOSIP PF_HYLINK PF_IMPLINK PF_INET PF_INET6
712         PF_ISO PF_KEY PF_LAST PF_LAT PF_LINK PF_MAX PF_NBS PF_NIT PF_NS PF_OSI
713         PF_OSINET PF_PUP PF_ROUTE PF_SNA PF_UNIX PF_UNSPEC PF_USER PF_WAN
714         PF_X25
715
716         AF_802 AF_AAL AF_APPLETALK AF_CCITT AF_CHAOS AF_CTF AF_DATAKIT
717         AF_DECnet AF_DLI AF_ECMA AF_GOSIP AF_HYLINK AF_IMPLINK AF_INET AF_INET6
718         AF_ISO AF_KEY AF_LAST AF_LAT AF_LINK AF_MAX AF_NBS AF_NIT AF_NS AF_OSI
719         AF_OSINET AF_PUP AF_ROUTE AF_SNA AF_UNIX AF_UNSPEC AF_USER AF_WAN
720         AF_X25
721
722         SOCK_DGRAM SOCK_RAW SOCK_RDM SOCK_SEQPACKET SOCK_STREAM
723
724         SOL_SOCKET
725
726         SO_ACCEPTCONN SO_ATTACH_FILTER SO_BACKLOG SO_BROADCAST SO_CHAMELEON
727         SO_DEBUG SO_DETACH_FILTER SO_DGRAM_ERRIND SO_DOMAIN SO_DONTLINGER
728         SO_DONTROUTE SO_ERROR SO_FAMILY SO_KEEPALIVE SO_LINGER SO_OOBINLINE
729         SO_PASSCRED SO_PASSIFNAME SO_PEERCRED SO_PROTOCOL SO_PROTOTYPE
730         SO_RCVBUF SO_RCVLOWAT SO_RCVTIMEO SO_REUSEADDR SO_REUSEPORT
731         SO_SECURITY_AUTHENTICATION SO_SECURITY_ENCRYPTION_NETWORK
732         SO_SECURITY_ENCRYPTION_TRANSPORT SO_SNDBUF SO_SNDLOWAT SO_SNDTIMEO
733         SO_STATE SO_TYPE SO_USELOOPBACK SO_XOPEN SO_XSE
734
735         IP_HDRINCL IP_OPTIONS IP_RECVOPTS IP_RECVRETOPTS IP_RETOPTS IP_TOS
736         IP_TTL
737
738         MSG_BCAST MSG_BTAG MSG_CTLFLAGS MSG_CTLIGNORE MSG_CTRUNC MSG_DONTROUTE
739         MSG_DONTWAIT MSG_EOF MSG_EOR MSG_ERRQUEUE MSG_ETAG MSG_FASTOPEN MSG_FIN
740         MSG_MAXIOVLEN MSG_MCAST MSG_NOSIGNAL MSG_OOB MSG_PEEK MSG_PROXY MSG_RST
741         MSG_SYN MSG_TRUNC MSG_URG MSG_WAITALL MSG_WIRE
742
743         SHUT_RD SHUT_RDWR SHUT_WR
744
745         INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
746
747         SCM_CONNECT SCM_CREDENTIALS SCM_CREDS SCM_RIGHTS SCM_TIMESTAMP
748
749         SOMAXCONN
750
751         IOV_MAX
752         UIO_MAXIOV
753
754         sockaddr_family
755         pack_sockaddr_in  unpack_sockaddr_in  sockaddr_in
756         pack_sockaddr_in6 unpack_sockaddr_in6 sockaddr_in6
757         pack_sockaddr_un  unpack_sockaddr_un  sockaddr_un 
758
759         inet_aton inet_ntoa
760 );
761
762 # List re-ordered to match documentation above. Try to keep the ordering
763 # consistent so it's easier to see which ones are or aren't documented.
764 our @EXPORT_OK = qw(
765         CR LF CRLF $CR $LF $CRLF
766
767         SOCK_NONBLOCK SOCK_CLOEXEC
768
769         IP_ADD_MEMBERSHIP IP_ADD_SOURCE_MEMBERSHIP IP_BIND_ADDRESS_NO_PORT
770         IP_DROP_MEMBERSHIP IP_DROP_SOURCE_MEMBERSHIP IP_FREEBIND
771         IP_MULTICAST_ALL IP_MULTICAST_IF IP_MULTICAST_LOOP IP_MULTICAST_TTL
772         IP_MTU IP_MTU_DISCOVER IP_NODEFRAG IP_RECVERR IP_TRANSPARENT
773
774         IPPROTO_IP IPPROTO_IPV6 IPPROTO_RAW IPPROTO_ICMP IPPROTO_IGMP
775         IPPROTO_TCP IPPROTO_UDP IPPROTO_GRE IPPROTO_ESP IPPROTO_AH
776         IPPROTO_ICMPV6 IPPROTO_SCTP
777
778         IP_PMTUDISC_DO IP_PMTUDISC_DONT IP_PMTUDISC_PROBE IP_PMTUDISC_WANT
779
780         IPTOS_LOWDELAY IPTOS_THROUGHPUT IPTOS_RELIABILITY IPTOS_MINCOST
781
782         TCP_CONGESTION TCP_CONNECTIONTIMEOUT TCP_CORK TCP_DEFER_ACCEPT
783         TCP_FASTOPEN TCP_INFO TCP_INIT_CWND TCP_KEEPALIVE TCP_KEEPCNT
784         TCP_KEEPIDLE TCP_KEEPINTVL TCP_LINGER2 TCP_MAXRT TCP_MAXSEG
785         TCP_MD5SIG TCP_NODELAY TCP_NOOPT TCP_NOPUSH TCP_QUICKACK
786         TCP_SACK_ENABLE TCP_STDURG TCP_SYNCNT TCP_WINDOW_CLAMP
787
788         IN6ADDR_ANY IN6ADDR_LOOPBACK
789
790         IPV6_ADDRFROM IPV6_ADD_MEMBERSHIP IPV6_DROP_MEMBERSHIP IPV6_JOIN_GROUP
791         IPV6_LEAVE_GROUP IPV6_MTU IPV6_MTU_DISCOVER IPV6_MULTICAST_HOPS
792         IPV6_MULTICAST_IF IPV6_MULTICAST_LOOP IPV6_RECVERR IPV6_ROUTER_ALERT
793         IPV6_UNICAST_HOPS IPV6_V6ONLY
794
795         SO_LOCK_FILTER SO_RCVBUFFORCE SO_SNDBUFFORCE
796
797         pack_ip_mreq unpack_ip_mreq pack_ip_mreq_source unpack_ip_mreq_source
798
799         pack_ipv6_mreq unpack_ipv6_mreq
800
801         inet_pton inet_ntop
802
803         getaddrinfo getnameinfo
804
805         AI_ADDRCONFIG AI_ALL AI_CANONIDN AI_CANONNAME AI_IDN
806         AI_IDN_ALLOW_UNASSIGNED AI_IDN_USE_STD3_ASCII_RULES AI_NUMERICHOST
807         AI_NUMERICSERV AI_PASSIVE AI_V4MAPPED
808
809         NI_DGRAM NI_IDN NI_IDN_ALLOW_UNASSIGNED NI_IDN_USE_STD3_ASCII_RULES
810         NI_NAMEREQD NI_NOFQDN NI_NUMERICHOST NI_NUMERICSERV
811
812         NIx_NOHOST NIx_NOSERV
813
814         EAI_ADDRFAMILY EAI_AGAIN EAI_BADFLAGS EAI_BADHINTS EAI_FAIL EAI_FAMILY
815         EAI_NODATA EAI_NONAME EAI_PROTOCOL EAI_SERVICE EAI_SOCKTYPE EAI_SYSTEM
816 );
817
818 our %EXPORT_TAGS = (
819     crlf     => [qw(CR LF CRLF $CR $LF $CRLF)],
820     addrinfo => [qw(getaddrinfo getnameinfo), grep m/^(?:AI|NI|NIx|EAI)_/, @EXPORT_OK],
821     all      => [@EXPORT, @EXPORT_OK],
822 );
823
824 BEGIN {
825     sub CR   () {"\015"}
826     sub LF   () {"\012"}
827     sub CRLF () {"\015\012"}
828
829     # These are not gni() constants; they're extensions for the perl API
830     # The definitions in Socket.pm and Socket.xs must match
831     sub NIx_NOHOST() {1 << 0}
832     sub NIx_NOSERV() {1 << 1}
833 }
834
835 *CR   = \CR();
836 *LF   = \LF();
837 *CRLF = \CRLF();
838
839 sub sockaddr_in {
840     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
841         my($af, $port, @quad) = @_;
842         warnings::warn "6-ARG sockaddr_in call is deprecated" 
843             if warnings::enabled();
844         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
845     } elsif (wantarray) {
846         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
847         unpack_sockaddr_in(@_);
848     } else {
849         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
850         pack_sockaddr_in(@_);
851     }
852 }
853
854 sub sockaddr_in6 {
855     if (wantarray) {
856         croak "usage:   (port,in6addr,scope_id,flowinfo) = sockaddr_in6(sin6_sv)" unless @_ == 1;
857         unpack_sockaddr_in6(@_);
858     }
859     else {
860         croak "usage:   sin6_sv = sockaddr_in6(port,in6addr,[scope_id,[flowinfo]])" unless @_ >= 2 and @_ <= 4;
861         pack_sockaddr_in6(@_);
862     }
863 }
864
865 sub sockaddr_un {
866     if (wantarray) {
867         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
868         unpack_sockaddr_un(@_);
869     } else {
870         croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
871         pack_sockaddr_un(@_);
872     }
873 }
874
875 XSLoader::load(__PACKAGE__, $VERSION);
876
877 my %errstr;
878
879 if( defined &getaddrinfo ) {
880     # These are not part of the API, nothing uses them, and deleting them
881     # reduces the size of %Socket:: by about 12K
882     delete $Socket::{fake_getaddrinfo};
883     delete $Socket::{fake_getnameinfo};
884 } else {
885     require Scalar::Util;
886
887     *getaddrinfo = \&fake_getaddrinfo;
888     *getnameinfo = \&fake_getnameinfo;
889
890     # These numbers borrowed from GNU libc's implementation, but since
891     # they're only used by our emulation, it doesn't matter if the real
892     # platform's values differ
893     my %constants = (
894         AI_PASSIVE     => 1,
895         AI_CANONNAME   => 2,
896         AI_NUMERICHOST => 4,
897         AI_V4MAPPED    => 8,
898         AI_ALL         => 16,
899         AI_ADDRCONFIG  => 32,
900         # RFC 2553 doesn't define this but Linux does - lets be nice and
901         # provide it since we can
902         AI_NUMERICSERV => 1024,
903
904         EAI_BADFLAGS   => -1,
905         EAI_NONAME     => -2,
906         EAI_NODATA     => -5,
907         EAI_FAMILY     => -6,
908         EAI_SERVICE    => -8,
909
910         NI_NUMERICHOST => 1,
911         NI_NUMERICSERV => 2,
912         NI_NOFQDN      => 4,
913         NI_NAMEREQD    => 8,
914         NI_DGRAM       => 16,
915
916         # Constants we don't support. Export them, but croak if anyone tries to
917         # use them
918         AI_IDN                      => 64,
919         AI_CANONIDN                 => 128,
920         AI_IDN_ALLOW_UNASSIGNED     => 256,
921         AI_IDN_USE_STD3_ASCII_RULES => 512,
922         NI_IDN                      => 32,
923         NI_IDN_ALLOW_UNASSIGNED     => 64,
924         NI_IDN_USE_STD3_ASCII_RULES => 128,
925
926         # Error constants we'll never return, so it doesn't matter what value
927         # these have, nor that we don't provide strings for them
928         EAI_SYSTEM   => -11,
929         EAI_BADHINTS => -1000,
930         EAI_PROTOCOL => -1001
931     );
932
933     foreach my $name ( keys %constants ) {
934         my $value = $constants{$name};
935
936         no strict 'refs';
937         defined &$name or *$name = sub () { $value };
938     }
939
940     %errstr = (
941         # These strings from RFC 2553
942         EAI_BADFLAGS()   => "invalid value for ai_flags",
943         EAI_NONAME()     => "nodename nor servname provided, or not known",
944         EAI_NODATA()     => "no address associated with nodename",
945         EAI_FAMILY()     => "ai_family not supported",
946         EAI_SERVICE()    => "servname not supported for ai_socktype",
947     );
948 }
949
950 # The following functions are used if the system does not have a
951 # getaddrinfo(3) function in libc; and are used to emulate it for the AF_INET
952 # family
953
954 # Borrowed from Regexp::Common::net
955 my $REGEXP_IPv4_DECIMAL = qr/25[0-5]|2[0-4][0-9]|[0-1]?[0-9]{1,2}/;
956 my $REGEXP_IPv4_DOTTEDQUAD = qr/$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL/;
957
958 sub fake_makeerr
959 {
960     my ( $errno ) = @_;
961     my $errstr = $errno == 0 ? "" : ( $errstr{$errno} || $errno );
962     return Scalar::Util::dualvar( $errno, $errstr );
963 }
964
965 sub fake_getaddrinfo
966 {
967     my ( $node, $service, $hints ) = @_;
968
969     $node = "" unless defined $node;
970
971     $service = "" unless defined $service;
972
973     my ( $family, $socktype, $protocol, $flags ) = @$hints{qw( family socktype protocol flags )};
974
975     $family ||= Socket::AF_INET(); # 0 == AF_UNSPEC, which we want too
976     $family == Socket::AF_INET() or return fake_makeerr( EAI_FAMILY() );
977
978     $socktype ||= 0;
979
980     $protocol ||= 0;
981
982     $flags ||= 0;
983
984     my $flag_passive     = $flags & AI_PASSIVE();     $flags &= ~AI_PASSIVE();
985     my $flag_canonname   = $flags & AI_CANONNAME();   $flags &= ~AI_CANONNAME();
986     my $flag_numerichost = $flags & AI_NUMERICHOST(); $flags &= ~AI_NUMERICHOST();
987     my $flag_numericserv = $flags & AI_NUMERICSERV(); $flags &= ~AI_NUMERICSERV();
988
989     # These constants don't apply to AF_INET-only lookups, so we might as well
990     # just ignore them. For AI_ADDRCONFIG we just presume the host has ability
991     # to talk AF_INET. If not we'd have to return no addresses at all. :)
992     $flags &= ~(AI_V4MAPPED()|AI_ALL()|AI_ADDRCONFIG());
993
994     $flags & (AI_IDN()|AI_CANONIDN()|AI_IDN_ALLOW_UNASSIGNED()|AI_IDN_USE_STD3_ASCII_RULES()) and
995         croak "Socket::getaddrinfo() does not support IDN";
996
997     $flags == 0 or return fake_makeerr( EAI_BADFLAGS() );
998
999     $node eq "" and $service eq "" and return fake_makeerr( EAI_NONAME() );
1000
1001     my $canonname;
1002     my @addrs;
1003     if( $node ne "" ) {
1004         return fake_makeerr( EAI_NONAME() ) if( $flag_numerichost and $node !~ m/^$REGEXP_IPv4_DOTTEDQUAD$/ );
1005         ( $canonname, undef, undef, undef, @addrs ) = gethostbyname( $node );
1006         defined $canonname or return fake_makeerr( EAI_NONAME() );
1007
1008         undef $canonname unless $flag_canonname;
1009     }
1010     else {
1011         $addrs[0] = $flag_passive ? Socket::inet_aton( "0.0.0.0" )
1012                                   : Socket::inet_aton( "127.0.0.1" );
1013     }
1014
1015     my @ports; # Actually ARRAYrefs of [ socktype, protocol, port ]
1016     my $protname = "";
1017     if( $protocol ) {
1018         $protname = eval { getprotobynumber( $protocol ) };
1019     }
1020
1021     if( $service ne "" and $service !~ m/^\d+$/ ) {
1022         return fake_makeerr( EAI_NONAME() ) if( $flag_numericserv );
1023         getservbyname( $service, $protname ) or return fake_makeerr( EAI_SERVICE() );
1024     }
1025
1026     foreach my $this_socktype ( Socket::SOCK_STREAM(), Socket::SOCK_DGRAM(), Socket::SOCK_RAW() ) {
1027         next if $socktype and $this_socktype != $socktype;
1028
1029         my $this_protname = "raw";
1030         $this_socktype == Socket::SOCK_STREAM() and $this_protname = "tcp";
1031         $this_socktype == Socket::SOCK_DGRAM()  and $this_protname = "udp";
1032
1033         next if $protname and $this_protname ne $protname;
1034
1035         my $port;
1036         if( $service ne "" ) {
1037             if( $service =~ m/^\d+$/ ) {
1038                 $port = "$service";
1039             }
1040             else {
1041                 ( undef, undef, $port, $this_protname ) = getservbyname( $service, $this_protname );
1042                 next unless defined $port;
1043             }
1044         }
1045         else {
1046             $port = 0;
1047         }
1048
1049         push @ports, [ $this_socktype, eval { scalar getprotobyname( $this_protname ) } || 0, $port ];
1050     }
1051
1052     my @ret;
1053     foreach my $addr ( @addrs ) {
1054         foreach my $portspec ( @ports ) {
1055             my ( $socktype, $protocol, $port ) = @$portspec;
1056             push @ret, {
1057                 family    => $family,
1058                 socktype  => $socktype,
1059                 protocol  => $protocol,
1060                 addr      => Socket::pack_sockaddr_in( $port, $addr ),
1061                 canonname => undef,
1062             };
1063         }
1064     }
1065
1066     # Only supply canonname for the first result
1067     if( defined $canonname ) {
1068         $ret[0]->{canonname} = $canonname;
1069     }
1070
1071     return ( fake_makeerr( 0 ), @ret );
1072 }
1073
1074 sub fake_getnameinfo
1075 {
1076     my ( $addr, $flags, $xflags ) = @_;
1077
1078     my ( $port, $inetaddr );
1079     eval { ( $port, $inetaddr ) = Socket::unpack_sockaddr_in( $addr ) }
1080         or return fake_makeerr( EAI_FAMILY() );
1081
1082     my $family = Socket::AF_INET();
1083
1084     $flags ||= 0;
1085
1086     my $flag_numerichost = $flags & NI_NUMERICHOST(); $flags &= ~NI_NUMERICHOST();
1087     my $flag_numericserv = $flags & NI_NUMERICSERV(); $flags &= ~NI_NUMERICSERV();
1088     my $flag_nofqdn      = $flags & NI_NOFQDN();      $flags &= ~NI_NOFQDN();
1089     my $flag_namereqd    = $flags & NI_NAMEREQD();    $flags &= ~NI_NAMEREQD();
1090     my $flag_dgram       = $flags & NI_DGRAM()   ;    $flags &= ~NI_DGRAM();
1091
1092     $flags & (NI_IDN()|NI_IDN_ALLOW_UNASSIGNED()|NI_IDN_USE_STD3_ASCII_RULES()) and
1093         croak "Socket::getnameinfo() does not support IDN";
1094
1095     $flags == 0 or return fake_makeerr( EAI_BADFLAGS() );
1096
1097     $xflags ||= 0;
1098
1099     my $node;
1100     if( $xflags & NIx_NOHOST ) {
1101         $node = undef;
1102     }
1103     elsif( $flag_numerichost ) {
1104         $node = Socket::inet_ntoa( $inetaddr );
1105     }
1106     else {
1107         $node = gethostbyaddr( $inetaddr, $family );
1108         if( !defined $node ) {
1109             return fake_makeerr( EAI_NONAME() ) if $flag_namereqd;
1110             $node = Socket::inet_ntoa( $inetaddr );
1111         }
1112         elsif( $flag_nofqdn ) {
1113             my ( $shortname ) = split m/\./, $node;
1114             my ( $fqdn ) = gethostbyname $shortname;
1115             $node = $shortname if defined $fqdn and $fqdn eq $node;
1116         }
1117     }
1118
1119     my $service;
1120     if( $xflags & NIx_NOSERV ) {
1121         $service = undef;
1122     }
1123     elsif( $flag_numericserv ) {
1124         $service = "$port";
1125     }
1126     else {
1127         my $protname = $flag_dgram ? "udp" : "";
1128         $service = getservbyport( $port, $protname );
1129         if( !defined $service ) {
1130             $service = "$port";
1131         }
1132     }
1133
1134     return ( fake_makeerr( 0 ), $node, $service );
1135 }
1136
1137 1;