This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Book-keeping for the previous commit (which restored the VC6 build, btw)
[perl5.git] / cpan / Socket / Socket.pm
index c6420e1..dd89450 100644 (file)
@@ -3,7 +3,7 @@ package Socket;
 use strict;
 { use 5.006001; }
 
-our $VERSION = '1.98';
+our $VERSION = '2.020_02'; # patched in perl5.git
 
 =head1 NAME
 
@@ -74,7 +74,7 @@ provided will depend on the OS and headers found at compile-time.
 =head2 PF_INET, PF_INET6, PF_UNIX, ...
 
 Protocol family constants to use as the first argument to socket() or the
-value of the C<SO_FAMILY> socket option.
+value of the C<SO_DOMAIN> or C<SO_FAMILY> socket option.
 
 =head2 AF_INET, AF_INET6, AF_UNIX, ...
 
@@ -87,6 +87,13 @@ functions as sockaddr_family().
 Socket type constants to use as the second argument to socket(), or the value
 of the C<SO_TYPE> socket option.
 
+=head2 SOCK_NONBLOCK. SOCK_CLOEXEC
+
+Linux-specific shortcuts to specify the C<O_NONBLOCK> and C<FD_CLOEXEC> flags
+during a C<socket(2)> call.
+
+ socket( my $sockh, PF_INET, SOCK_DGRAM|SOCK_NONBLOCK, 0 )
+
 =head2 SOL_SOCKET
 
 Socket option level constant for setsockopt() and getsockopt().
@@ -101,6 +108,10 @@ C<SOL_SOCKET> level.
 Socket option name constants for IPv4 socket options at the C<IPPROTO_IP>
 level.
 
+=head2 IPTOS_LOWDELAY, IPTOS_THROUGHPUT, IPTOS_RELIABILITY, ...
+
+Socket option value constants for C<IP_TOS> socket option.
+
 =head2 MSG_BCAST, MSG_OOB, MSG_TRUNC, ...
 
 Message flag constants for send() and recv().
@@ -177,6 +188,8 @@ opaque string representing the IP address (you can use inet_ntoa() to convert
 the address to the four-dotted numeric format). Will croak if the structure
 does not represent an C<AF_INET> address.
 
+In scalar context will return just the IP address.
+
 =head2 $sockaddr = sockaddr_in $port, $ip_address
 
 =head2 ($port, $ip_address) = sockaddr_in $sockaddr
@@ -204,6 +217,8 @@ flow label. (You can use inet_ntop() to convert the address to the usual
 string format). Will croak if the structure does not represent an C<AF_INET6>
 address.
 
+In scalar context will return just the IP address.
+
 =head2 $sockaddr = sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]
 
 =head2 ($port, $ip6_address, $scope_id, $flowinfo) = sockaddr_in6 $sockaddr
@@ -241,13 +256,37 @@ pack_sockaddr_un() or unpack_sockaddr_un() explicitly.
 
 These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
 
-=head2 $ipv6_mreq = pack_ipv6_mreq $ip6_address, $ifindex
+=head2 $ip_mreq = pack_ip_mreq $multiaddr, $interface
+
+Takes an IPv4 multicast address and optionally an interface address (or
+C<INADDR_ANY>). Returns the C<ip_mreq> structure with those arguments packed
+in. Suitable for use with the C<IP_ADD_MEMBERSHIP> and C<IP_DROP_MEMBERSHIP>
+sockopts.
+
+=head2 ($multiaddr, $interface) = unpack_ip_mreq $ip_mreq
+
+Takes an C<ip_mreq> structure. Returns a list of two elements; the IPv4
+multicast address and interface address.
 
-Takes an IPv6 address and an interface number. Returns the C<ipv6_mreq>
-structure with those arguments packed in. Suitable for use with the
-C<IPV6_ADD_MEMBERSHIP> and C<IPV6_DROP_MEMBERSHIP> sockopts.
+=head2 $ip_mreq_source = pack_ip_mreq_source $multiaddr, $source, $interface
 
-=head2 ($ip6_address, $ifindex) = unpack_ipv6_mreq $ipv6_mreq
+Takes an IPv4 multicast address, source address, and optionally an interface
+address (or C<INADDR_ANY>). Returns the C<ip_mreq_source> structure with those
+arguments packed in. Suitable for use with the C<IP_ADD_SOURCE_MEMBERSHIP>
+and C<IP_DROP_SOURCE_MEMBERSHIP> sockopts.
+
+=head2 ($multiaddr, $source, $interface) = unpack_ip_mreq_source $ip_mreq
+
+Takes an C<ip_mreq_source> structure. Returns a list of three elements; the
+IPv4 multicast address, source address and interface address.
+
+=head2 $ipv6_mreq = pack_ipv6_mreq $multiaddr6, $ifindex
+
+Takes an IPv6 multicast address and an interface number. Returns the
+C<ipv6_mreq> structure with those arguments packed in. Suitable for use with
+the C<IPV6_ADD_MEMBERSHIP> and C<IPV6_DROP_MEMBERSHIP> sockopts.
+
+=head2 ($multiaddr6, $ifindex) = unpack_ipv6_mreq $ipv6_mreq
 
 Takes an C<ipv6_mreq> structure. Returns a list of two elements; the IPv6
 address and an interface number.
@@ -286,7 +325,7 @@ code should use getnameinfo() or inet_ntop() instead for IPv6 support.
 =head2 $address = inet_pton $family, $string
 
 Takes an address family (such as C<AF_INET> or C<AF_INET6>) and a string
-giving the name of a host, or a textual representation of an IP address and
+containing a textual representation of an address in that family and
 translates that to an packed binary address structure.
 
 See also getaddrinfo() for a more powerful and flexible function to look up
@@ -543,8 +582,8 @@ service on the named host.
  print <$sock>;
 
 Because a list of potential candidates is returned, the C<while> loop tries
-each in turn until it it finds one that succeeds both the socket() and
-connect() calls.
+each in turn until it finds one that succeeds both the socket() and connect()
+calls.
 
 This function performs the work of the legacy functions gethostbyname(),
 getservbyname(), inet_aton() and pack_sockaddr_in().
@@ -675,10 +714,10 @@ our @EXPORT = qw(
        SOL_SOCKET
 
        SO_ACCEPTCONN SO_ATTACH_FILTER SO_BACKLOG SO_BROADCAST SO_CHAMELEON
-       SO_DEBUG SO_DETACH_FILTER SO_DGRAM_ERRIND SO_DONTLINGER SO_DONTROUTE
-       SO_ERROR SO_FAMILY SO_KEEPALIVE SO_LINGER SO_OOBINLINE SO_PASSCRED
-       SO_PASSIFNAME SO_PEERCRED SO_PROTOCOL SO_PROTOTYPE SO_RCVBUF
-       SO_RCVLOWAT SO_RCVTIMEO SO_REUSEADDR SO_REUSEPORT
+       SO_DEBUG SO_DETACH_FILTER SO_DGRAM_ERRIND SO_DOMAIN SO_DONTLINGER
+       SO_DONTROUTE SO_ERROR SO_FAMILY SO_KEEPALIVE SO_LINGER SO_OOBINLINE
+       SO_PASSCRED SO_PASSIFNAME SO_PEERCRED SO_PROTOCOL SO_PROTOTYPE
+       SO_RCVBUF SO_RCVLOWAT SO_RCVTIMEO SO_REUSEADDR SO_REUSEPORT
        SO_SECURITY_AUTHENTICATION SO_SECURITY_ENCRYPTION_NETWORK
        SO_SECURITY_ENCRYPTION_TRANSPORT SO_SNDBUF SO_SNDLOWAT SO_SNDTIMEO
        SO_STATE SO_TYPE SO_USELOOPBACK SO_XOPEN SO_XSE
@@ -715,19 +754,31 @@ our @EXPORT = qw(
 our @EXPORT_OK = qw(
        CR LF CRLF $CR $LF $CRLF
 
-       IPPROTO_IP IPPROTO_IPV6 IPPROTO_RAW IPPROTO_ICMP IPPROTO_TCP
-       IPPROTO_UDP
+       SOCK_NONBLOCK SOCK_CLOEXEC
 
-       TCP_CONGESTION TCP_CORK TCP_DEFER_ACCEPT TCP_INFO TCP_KEEPALIVE
-       TCP_KEEPCNT TCP_KEEPIDLE TCP_KEEPINTVL TCP_LINGER2 TCP_MAXRT TCP_MAXSEG
-       TCP_MD5SIG TCP_NODELAY TCP_QUICKACK TCP_STDURG TCP_SYNCNT
-       TCP_WINDOW_CLAMP 
+       IP_ADD_MEMBERSHIP IP_ADD_SOURCE_MEMBERSHIP IP_DROP_MEMBERSHIP
+       IP_DROP_SOURCE_MEMBERSHIP IP_MULTICAST_IF IP_MULTICAST_LOOP
+       IP_MULTICAST_TTL
+
+       IPPROTO_IP IPPROTO_IPV6 IPPROTO_RAW IPPROTO_ICMP IPPROTO_IGMP
+       IPPROTO_TCP IPPROTO_UDP IPPROTO_GRE IPPROTO_ESP IPPROTO_AH
+       IPPROTO_SCTP
+
+       IPTOS_LOWDELAY IPTOS_THROUGHPUT IPTOS_RELIABILITY IPTOS_MINCOST
+
+       TCP_CONGESTION TCP_CONNECTIONTIMEOUT TCP_CORK TCP_DEFER_ACCEPT TCP_INFO
+       TCP_INIT_CWND TCP_KEEPALIVE TCP_KEEPCNT TCP_KEEPIDLE TCP_KEEPINTVL
+       TCP_LINGER2 TCP_MAXRT TCP_MAXSEG TCP_MD5SIG TCP_NODELAY TCP_NOOPT
+       TCP_NOPUSH TCP_QUICKACK TCP_SACK_ENABLE TCP_STDURG TCP_SYNCNT
+       TCP_WINDOW_CLAMP
 
        IN6ADDR_ANY IN6ADDR_LOOPBACK
 
-       IPV6_ADD_MEMBERSHIP IPV6_DROP_MEMBERSHIP IPV6_MTU IPV6_MTU_DISCOVER
-       IPV6_MULTICAST_HOPS IPV6_MULTICAST_IF IPV6_MULTICAST_LOOP
-       IPV6_UNICAST_HOPS IPV6_V6ONLY
+       IPV6_ADD_MEMBERSHIP IPV6_DROP_MEMBERSHIP IPV6_JOIN_GROUP
+       IPV6_LEAVE_GROUP IPV6_MTU IPV6_MTU_DISCOVER IPV6_MULTICAST_HOPS
+       IPV6_MULTICAST_IF IPV6_MULTICAST_LOOP IPV6_UNICAST_HOPS IPV6_V6ONLY
+
+       pack_ip_mreq unpack_ip_mreq pack_ip_mreq_source unpack_ip_mreq_source
 
        pack_ipv6_mreq unpack_ipv6_mreq
 
@@ -885,7 +936,7 @@ if( defined &getaddrinfo ) {
 # family
 
 # Borrowed from Regexp::Common::net
-my $REGEXP_IPv4_DECIMAL = qr/25[0-5]|2[0-4][0-9]|1?[0-9][0-9]{1,2}/;
+my $REGEXP_IPv4_DECIMAL = qr/25[0-5]|2[0-4][0-9]|[0-1]?[0-9]{1,2}/;
 my $REGEXP_IPv4_DOTTEDQUAD = qr/$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL/;
 
 sub fake_makeerr
@@ -948,7 +999,7 @@ sub fake_getaddrinfo
     my @ports; # Actually ARRAYrefs of [ socktype, protocol, port ]
     my $protname = "";
     if( $protocol ) {
-       $protname = getprotobynumber( $protocol );
+       $protname = eval { getprotobynumber( $protocol ) };
     }
 
     if( $service ne "" and $service !~ m/^\d+$/ ) {
@@ -979,7 +1030,7 @@ sub fake_getaddrinfo
            $port = 0;
        }
 
-       push @ports, [ $this_socktype, scalar getprotobyname( $this_protname ) || 0, $port ];
+       push @ports, [ $this_socktype, eval { scalar getprotobyname( $this_protname ) } || 0, $port ];
     }
 
     my @ret;