ext/Socket/Socket.pm

   1 package Socket;
   2
   3 our($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
   4 $VERSION = "1.77";
   5
   6 =head1 NAME
   7
   8 Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa - 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 =back
 175
 176 =cut
 177
 178 use Carp;
 179 use warnings::register;
 180
 181 require Exporter;
 182 use XSLoader ();
 183 @ISA = qw(Exporter);
 184 @EXPORT = qw(
 185         inet_aton inet_ntoa
 186         sockaddr_family
 187         pack_sockaddr_in unpack_sockaddr_in
 188         pack_sockaddr_un unpack_sockaddr_un
 189         sockaddr_in sockaddr_un
 190         INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
 191         AF_802
 192         AF_AAL
 193         AF_APPLETALK
 194         AF_CCITT
 195         AF_CHAOS
 196         AF_CTF
 197         AF_DATAKIT
 198         AF_DECnet
 199         AF_DLI
 200         AF_ECMA
 201         AF_GOSIP
 202         AF_HYLINK
 203         AF_IMPLINK
 204         AF_INET
 205         AF_INET6
 206         AF_ISO
 207         AF_KEY
 208         AF_LAST
 209         AF_LAT
 210         AF_LINK
 211         AF_MAX
 212         AF_NBS
 213         AF_NIT
 214         AF_NS
 215         AF_OSI
 216         AF_OSINET
 217         AF_PUP
 218         AF_ROUTE
 219         AF_SNA
 220         AF_UNIX
 221         AF_UNSPEC
 222         AF_USER
 223         AF_WAN
 224         AF_X25
 225         IOV_MAX
 226         MSG_BCAST
 227         MSG_BTAG
 228         MSG_CTLFLAGS
 229         MSG_CTLIGNORE
 230         MSG_CTRUNC
 231         MSG_DONTROUTE
 232         MSG_DONTWAIT
 233         MSG_EOF
 234         MSG_EOR
 235         MSG_ERRQUEUE
 236         MSG_ETAG
 237         MSG_FIN
 238         MSG_MAXIOVLEN
 239         MSG_MCAST
 240         MSG_NOSIGNAL
 241         MSG_OOB
 242         MSG_PEEK
 243         MSG_PROXY
 244         MSG_RST
 245         MSG_SYN
 246         MSG_TRUNC
 247         MSG_URG
 248         MSG_WAITALL
 249         MSG_WIRE
 250         PF_802
 251         PF_AAL
 252         PF_APPLETALK
 253         PF_CCITT
 254         PF_CHAOS
 255         PF_CTF
 256         PF_DATAKIT
 257         PF_DECnet
 258         PF_DLI
 259         PF_ECMA
 260         PF_GOSIP
 261         PF_HYLINK
 262         PF_IMPLINK
 263         PF_INET
 264         PF_INET6
 265         PF_ISO
 266         PF_KEY
 267         PF_LAST
 268         PF_LAT
 269         PF_LINK
 270         PF_MAX
 271         PF_NBS
 272         PF_NIT
 273         PF_NS
 274         PF_OSI
 275         PF_OSINET
 276         PF_PUP
 277         PF_ROUTE
 278         PF_SNA
 279         PF_UNIX
 280         PF_UNSPEC
 281         PF_USER
 282         PF_WAN
 283         PF_X25
 284         SCM_CONNECT
 285         SCM_CREDENTIALS
 286         SCM_CREDS
 287         SCM_RIGHTS
 288         SCM_TIMESTAMP
 289         SHUT_RD
 290         SHUT_RDWR
 291         SHUT_WR
 292         SOCK_DGRAM
 293         SOCK_RAW
 294         SOCK_RDM
 295         SOCK_SEQPACKET
 296         SOCK_STREAM
 297         SOL_SOCKET
 298         SOMAXCONN
 299         SO_ACCEPTCONN
 300         SO_ATTACH_FILTER
 301         SO_BACKLOG
 302         SO_BROADCAST
 303         SO_CHAMELEON
 304         SO_DEBUG
 305         SO_DETACH_FILTER
 306         SO_DGRAM_ERRIND
 307         SO_DONTLINGER
 308         SO_DONTROUTE
 309         SO_ERROR
 310         SO_FAMILY
 311         SO_KEEPALIVE
 312         SO_LINGER
 313         SO_OOBINLINE
 314         SO_PASSCRED
 315         SO_PASSIFNAME
 316         SO_PEERCRED
 317         SO_PROTOCOL
 318         SO_PROTOTYPE
 319         SO_RCVBUF
 320         SO_RCVLOWAT
 321         SO_RCVTIMEO
 322         SO_REUSEADDR
 323         SO_REUSEPORT
 324         SO_SECURITY_AUTHENTICATION
 325         SO_SECURITY_ENCRYPTION_NETWORK
 326         SO_SECURITY_ENCRYPTION_TRANSPORT
 327         SO_SNDBUF
 328         SO_SNDLOWAT
 329         SO_SNDTIMEO
 330         SO_STATE
 331         SO_TYPE
 332         SO_USELOOPBACK
 333         SO_XOPEN
 334         SO_XSE
 335         UIO_MAXIOV
 336 );
 337
 338 @EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
 339
 340                IPPROTO_TCP
 341                TCP_KEEPALIVE
 342                TCP_MAXRT
 343                TCP_MAXSEG
 344                TCP_NODELAY
 345                TCP_STDURG);
 346
 347 %EXPORT_TAGS = (
 348     crlf    => [qw(CR LF CRLF $CR $LF $CRLF)],
 349     all     => [@EXPORT, @EXPORT_OK],
 350 );
 351
 352 BEGIN {
 353     sub CR   () {"\015"}
 354     sub LF   () {"\012"}
 355     sub CRLF () {"\015\012"}
 356 }
 357
 358 *CR   = \CR();
 359 *LF   = \LF();
 360 *CRLF = \CRLF();
 361
 362 sub sockaddr_in {
 363     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
 364         my($af, $port, @quad) = @_;
 365         warnings::warn "6-ARG sockaddr_in call is deprecated"
 366             if warnings::enabled();
 367         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
 368     } elsif (wantarray) {
 369         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
 370         unpack_sockaddr_in(@_);
 371     } else {
 372         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
 373         pack_sockaddr_in(@_);
 374     }
 375 }
 376
 377 sub sockaddr_un {
 378     if (wantarray) {
 379         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
 380         unpack_sockaddr_un(@_);
 381     } else {
 382         croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
 383         pack_sockaddr_un(@_);
 384     }
 385 }
 386
 387 sub AUTOLOAD {
 388     my($constname);
 389     ($constname = $AUTOLOAD) =~ s/.*:://;
 390     croak "&Socket::constant not defined" if $constname eq 'constant';
 391     my ($error, $val) = constant($constname);
 392     if ($error) {
 393         croak $error;
 394     }
 395     *$AUTOLOAD = sub { $val };
 396     goto &$AUTOLOAD;
 397 }
 398
 399 XSLoader::load 'Socket', $VERSION;
 400
 401 1;