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