ext/Socket/Socket.pm

   1 package Socket;
   2
   3 our($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
   4 $VERSION = "1.84";
   5
   6 =head1 NAME
   7
   8 Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa, inet_pton, inet_ntop - load the C socket.h defines and structure manipulators
   9
  10 =head1 SYNOPSIS
  11
  12     use Socket;
  13
  14     $proto = getprotobyname('udp');
  15     socket(Socket_Handle, PF_INET, SOCK_DGRAM, $proto);
  16     $iaddr = gethostbyname('hishost.com');
  17     $port = getservbyname('time', 'udp');
  18     $sin = sockaddr_in($port, $iaddr);
  19     send(Socket_Handle, 0, 0, $sin);
  20
  21     $proto = getprotobyname('tcp');
  22     socket(Socket_Handle, PF_INET, SOCK_STREAM, $proto);
  23     $port = getservbyname('smtp', 'tcp');
  24     $sin = sockaddr_in($port,inet_aton("127.1"));
  25     $sin = sockaddr_in(7,inet_aton("localhost"));
  26     $sin = sockaddr_in(7,INADDR_LOOPBACK);
  27     connect(Socket_Handle,$sin);
  28
  29     ($port, $iaddr) = sockaddr_in(getpeername(Socket_Handle));
  30     $peer_host = gethostbyaddr($iaddr, AF_INET);
  31     $peer_addr = inet_ntoa($iaddr);
  32
  33     $proto = getprotobyname('tcp');
  34     socket(Socket_Handle, PF_UNIX, SOCK_STREAM, $proto);
  35     unlink('/var/run/usock');
  36     $sun = sockaddr_un('/var/run/usock');
  37     connect(Socket_Handle,$sun);
  38
  39 =head1 DESCRIPTION
  40
  41 This module is just a translation of the C F<socket.h> file.
  42 Unlike the old mechanism of requiring a translated F<socket.ph>
  43 file, this uses the B<h2xs> program (see the Perl source distribution)
  44 and your native C compiler.  This means that it has a
  45 far more likely chance of getting the numbers right.  This includes
  46 all of the commonly used pound-defines like AF_INET, SOCK_STREAM, etc.
  47
  48 Also, some common socket "newline" constants are provided: the
  49 constants C<CR>, C<LF>, and C<CRLF>, as well as C<$CR>, C<$LF>, and
  50 C<$CRLF>, which map to C<\015>, C<\012>, and C<\015\012>.  If you do
  51 not want to use the literal characters in your programs, then use
  52 the constants provided here.  They are not exported by default, but can
  53 be imported individually, and with the C<:crlf> export tag:
  54
  55     use Socket qw(:DEFAULT :crlf);
  56
  57 In addition, some structure manipulation functions are available:
  58
  59 =over 4
  60
  61 =item inet_aton HOSTNAME
  62
  63 Takes a string giving the name of a host, and translates that to an
  64 opaque string (if programming in C, struct in_addr). Takes arguments
  65 of both the 'rtfm.mit.edu' type and '18.181.0.24'. If the host name
  66 cannot be resolved, returns undef.  For multi-homed hosts (hosts with
  67 more than one address), the first address found is returned.
  68
  69 For portability do not assume that the result of inet_aton() is 32
  70 bits wide, in other words, that it would contain only the IPv4 address
  71 in network order.
  72
  73 =item inet_ntoa IP_ADDRESS
  74
  75 Takes a string (an opaque string as returned by inet_aton(),
  76 or a v-string representing the four octets of the IPv4 address in
  77 network order) and translates it into a string of the form 'd.d.d.d'
  78 where the 'd's are numbers less than 256 (the normal human-readable
  79 four dotted number notation for Internet addresses).
  80
  81 =item INADDR_ANY
  82
  83 Note: does not return a number, but a packed string.
  84
  85 Returns the 4-byte wildcard ip address which specifies any
  86 of the hosts ip addresses.  (A particular machine can have
  87 more than one ip address, each address corresponding to
  88 a particular network interface. This wildcard address
  89 allows you to bind to all of them simultaneously.)
  90 Normally equivalent to inet_aton('0.0.0.0').
  91
  92 =item INADDR_BROADCAST
  93
  94 Note: does not return a number, but a packed string.
  95
  96 Returns the 4-byte 'this-lan' ip broadcast address.
  97 This can be useful for some protocols to solicit information
  98 from all servers on the same LAN cable.
  99 Normally equivalent to inet_aton('255.255.255.255').
 100
 101 =item INADDR_LOOPBACK
 102
 103 Note - does not return a number.
 104
 105 Returns the 4-byte loopback address.  Normally equivalent
 106 to inet_aton('localhost').
 107
 108 =item INADDR_NONE
 109
 110 Note - does not return a number.
 111
 112 Returns the 4-byte 'invalid' ip address.  Normally equivalent
 113 to inet_aton('255.255.255.255').
 114
 115 =item sockaddr_family SOCKADDR
 116
 117 Takes a sockaddr structure (as returned by pack_sockaddr_in(),
 118 pack_sockaddr_un() or the perl builtin functions getsockname() and
 119 getpeername()) and returns the address family tag.  It will match the
 120 constant AF_INET for a sockaddr_in and AF_UNIX for a sockaddr_un.  It
 121 can be used to figure out what unpacker to use for a sockaddr of
 122 unknown type.
 123
 124 =item sockaddr_in PORT, ADDRESS
 125
 126 =item sockaddr_in SOCKADDR_IN
 127
 128 In a list context, unpacks its SOCKADDR_IN argument and returns an array
 129 consisting of (PORT, ADDRESS).  In a scalar context, packs its (PORT,
 130 ADDRESS) arguments as a SOCKADDR_IN and returns it.  If this is confusing,
 131 use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
 132
 133 =item pack_sockaddr_in PORT, IP_ADDRESS
 134
 135 Takes two arguments, a port number and an opaque string, IP_ADDRESS
 136 (as returned by inet_aton(), or a v-string).  Returns the sockaddr_in
 137 structure with those arguments packed in with AF_INET filled in.  For
 138 Internet domain sockets, this structure is normally what you need for
 139 the arguments in bind(), connect(), and send(), and is also returned
 140 by getpeername(), getsockname() and recv().
 141
 142 =item unpack_sockaddr_in SOCKADDR_IN
 143
 144 Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
 145 returns an array of two elements: the port and an opaque string
 146 representing the IP address (you can use inet_ntoa() to convert the
 147 address to the four-dotted numeric format).  Will croak if the
 148 structure does not have AF_INET in the right place.
 149
 150 =item sockaddr_un PATHNAME
 151
 152 =item sockaddr_un SOCKADDR_UN
 153
 154 In a list context, unpacks its SOCKADDR_UN argument and returns an array
 155 consisting of (PATHNAME).  In a scalar context, packs its PATHNAME
 156 arguments as a SOCKADDR_UN and returns it.  If this is confusing, use
 157 pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
 158 These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
 159
 160 =item pack_sockaddr_un PATH
 161
 162 Takes one argument, a pathname. Returns the sockaddr_un structure with
 163 that path packed in with AF_UNIX filled in. For unix domain sockets, this
 164 structure is normally what you need for the arguments in bind(),
 165 connect(), and send(), and is also returned by getpeername(),
 166 getsockname() and recv().
 167
 168 =item unpack_sockaddr_un SOCKADDR_UN
 169
 170 Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
 171 and returns the pathname.  Will croak if the structure does not
 172 have AF_UNIX in the right place.
 173
 174 =item inet_pton ADDRESS_FAMILY, HOSTNAME
 175
 176 Takes an address family, either AF_INET or AF_INET6, and a string giving
 177 the name of a host, and translates that to an opaque string
 178 (if programming in C, struct in_addr or struct in6_addr depending on the
 179 address family passed in).  The host string may be a string hostname, such
 180 as 'www.perl.org', or an IP address.  If using an IP address, the type of
 181 IP address must be consistant with the address family passed into the function.
 182
 183 =item inet_ntop ADDRESS_FAMILY, IP_ADDRESS
 184
 185 Takes an address family, either AF_INET or AF_INET6, and a string
 186 (an opaque string as returned by inet_aton() or inet_pton()) and
 187 translates it to an IPv4 or IPv6 address string.
 188
 189 =back
 190
 191 =cut
 192
 193 use Carp;
 194 use warnings::register;
 195
 196 require Exporter;
 197 use XSLoader ();
 198 @ISA = qw(Exporter);
 199 @EXPORT = qw(
 200         inet_aton inet_ntoa
 201         inet_pton inet_ntop
 202         sockaddr_family
 203         pack_sockaddr_in unpack_sockaddr_in
 204         pack_sockaddr_un unpack_sockaddr_un
 205         sockaddr_in sockaddr_un
 206         INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
 207         AF_802
 208         AF_AAL
 209         AF_APPLETALK
 210         AF_CCITT
 211         AF_CHAOS
 212         AF_CTF
 213         AF_DATAKIT
 214         AF_DECnet
 215         AF_DLI
 216         AF_ECMA
 217         AF_GOSIP
 218         AF_HYLINK
 219         AF_IMPLINK
 220         AF_INET
 221         AF_INET6
 222         AF_ISO
 223         AF_KEY
 224         AF_LAST
 225         AF_LAT
 226         AF_LINK
 227         AF_MAX
 228         AF_NBS
 229         AF_NIT
 230         AF_NS
 231         AF_OSI
 232         AF_OSINET
 233         AF_PUP
 234         AF_ROUTE
 235         AF_SNA
 236         AF_UNIX
 237         AF_UNSPEC
 238         AF_USER
 239         AF_WAN
 240         AF_X25
 241         IOV_MAX
 242         IP_OPTIONS
 243         IP_HDRINCL
 244         IP_TOS
 245         IP_TTL
 246         IP_RECVOPTS
 247         IP_RECVRETOPTS
 248         IP_RETOPTS
 249         MSG_BCAST
 250         MSG_BTAG
 251         MSG_CTLFLAGS
 252         MSG_CTLIGNORE
 253         MSG_CTRUNC
 254         MSG_DONTROUTE
 255         MSG_DONTWAIT
 256         MSG_EOF
 257         MSG_EOR
 258         MSG_ERRQUEUE
 259         MSG_ETAG
 260         MSG_FIN
 261         MSG_MAXIOVLEN
 262         MSG_MCAST
 263         MSG_NOSIGNAL
 264         MSG_OOB
 265         MSG_PEEK
 266         MSG_PROXY
 267         MSG_RST
 268         MSG_SYN
 269         MSG_TRUNC
 270         MSG_URG
 271         MSG_WAITALL
 272         MSG_WIRE
 273         PF_802
 274         PF_AAL
 275         PF_APPLETALK
 276         PF_CCITT
 277         PF_CHAOS
 278         PF_CTF
 279         PF_DATAKIT
 280         PF_DECnet
 281         PF_DLI
 282         PF_ECMA
 283         PF_GOSIP
 284         PF_HYLINK
 285         PF_IMPLINK
 286         PF_INET
 287         PF_INET6
 288         PF_ISO
 289         PF_KEY
 290         PF_LAST
 291         PF_LAT
 292         PF_LINK
 293         PF_MAX
 294         PF_NBS
 295         PF_NIT
 296         PF_NS
 297         PF_OSI
 298         PF_OSINET
 299         PF_PUP
 300         PF_ROUTE
 301         PF_SNA
 302         PF_UNIX
 303         PF_UNSPEC
 304         PF_USER
 305         PF_WAN
 306         PF_X25
 307         SCM_CONNECT
 308         SCM_CREDENTIALS
 309         SCM_CREDS
 310         SCM_RIGHTS
 311         SCM_TIMESTAMP
 312         SHUT_RD
 313         SHUT_RDWR
 314         SHUT_WR
 315         SOCK_DGRAM
 316         SOCK_RAW
 317         SOCK_RDM
 318         SOCK_SEQPACKET
 319         SOCK_STREAM
 320         SOL_SOCKET
 321         SOMAXCONN
 322         SO_ACCEPTCONN
 323         SO_ATTACH_FILTER
 324         SO_BACKLOG
 325         SO_BROADCAST
 326         SO_CHAMELEON
 327         SO_DEBUG
 328         SO_DETACH_FILTER
 329         SO_DGRAM_ERRIND
 330         SO_DONTLINGER
 331         SO_DONTROUTE
 332         SO_ERROR
 333         SO_FAMILY
 334         SO_KEEPALIVE
 335         SO_LINGER
 336         SO_OOBINLINE
 337         SO_PASSCRED
 338         SO_PASSIFNAME
 339         SO_PEERCRED
 340         SO_PROTOCOL
 341         SO_PROTOTYPE
 342         SO_RCVBUF
 343         SO_RCVLOWAT
 344         SO_RCVTIMEO
 345         SO_REUSEADDR
 346         SO_REUSEPORT
 347         SO_SECURITY_AUTHENTICATION
 348         SO_SECURITY_ENCRYPTION_NETWORK
 349         SO_SECURITY_ENCRYPTION_TRANSPORT
 350         SO_SNDBUF
 351         SO_SNDLOWAT
 352         SO_SNDTIMEO
 353         SO_STATE
 354         SO_TYPE
 355         SO_USELOOPBACK
 356         SO_XOPEN
 357         SO_XSE
 358         UIO_MAXIOV
 359 );
 360
 361 @EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
 362
 363                IPPROTO_IP
 364                IPPROTO_IPV6
 365                IPPROTO_RAW
 366                IPPROTO_ICMP
 367                IPPROTO_TCP
 368                IPPROTO_UDP
 369
 370                TCP_KEEPALIVE
 371                TCP_MAXRT
 372                TCP_MAXSEG
 373                TCP_NODELAY
 374                TCP_STDURG);
 375
 376 %EXPORT_TAGS = (
 377     crlf    => [qw(CR LF CRLF $CR $LF $CRLF)],
 378     all     => [@EXPORT, @EXPORT_OK],
 379 );
 380
 381 BEGIN {
 382     sub CR   () {"\015"}
 383     sub LF   () {"\012"}
 384     sub CRLF () {"\015\012"}
 385 }
 386
 387 *CR   = \CR();
 388 *LF   = \LF();
 389 *CRLF = \CRLF();
 390
 391 sub sockaddr_in {
 392     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
 393         my($af, $port, @quad) = @_;
 394         warnings::warn "6-ARG sockaddr_in call is deprecated"
 395             if warnings::enabled();
 396         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
 397     } elsif (wantarray) {
 398         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
 399         unpack_sockaddr_in(@_);
 400     } else {
 401         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
 402         pack_sockaddr_in(@_);
 403     }
 404 }
 405
 406 sub sockaddr_un {
 407     if (wantarray) {
 408         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
 409         unpack_sockaddr_un(@_);
 410     } else {
 411         croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
 412         pack_sockaddr_un(@_);
 413     }
 414 }
 415
 416 sub AUTOLOAD {
 417     my($constname);
 418     ($constname = $AUTOLOAD) =~ s/.*:://;
 419     croak "&Socket::constant not defined" if $constname eq 'constant';
 420     my ($error, $val) = constant($constname);
 421     if ($error) {
 422         croak $error;
 423     }
 424     *$AUTOLOAD = sub { $val };
 425     goto &$AUTOLOAD;
 426 }
 427
 428 XSLoader::load 'Socket', $VERSION;
 429
 430 1;