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