ext/Socket/Socket.pm

   1 package Socket;
   2
   3 our($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
   4 $VERSION = "1.75";
   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('/tmp/usock');
  36     $sun = sockaddr_un('/tmp/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_in PORT, ADDRESS
 116
 117 =item sockaddr_in SOCKADDR_IN
 118
 119 In a list context, unpacks its SOCKADDR_IN argument and returns an array
 120 consisting of (PORT, ADDRESS).  In a scalar context, packs its (PORT,
 121 ADDRESS) arguments as a SOCKADDR_IN and returns it.  If this is confusing,
 122 use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
 123
 124 =item pack_sockaddr_in PORT, IP_ADDRESS
 125
 126 Takes two arguments, a port number and an opaque string, IP_ADDRESS
 127 (as returned by inet_aton(), or a v-string).  Returns the sockaddr_in
 128 structure with those arguments packed in with AF_INET filled in.  For
 129 Internet domain sockets, this structure is normally what you need for
 130 the arguments in bind(), connect(), and send(), and is also returned
 131 by getpeername(), getsockname() and recv().
 132
 133 =item unpack_sockaddr_in SOCKADDR_IN
 134
 135 Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
 136 returns an array of two elements: the port and an opaque string
 137 representing the IP address (you can use inet_ntoa() to convert the
 138 address to the four-dotted numeric format).  Will croak if the
 139 structure does not have AF_INET in the right place.
 140
 141 =item sockaddr_un PATHNAME
 142
 143 =item sockaddr_un SOCKADDR_UN
 144
 145 In a list context, unpacks its SOCKADDR_UN argument and returns an array
 146 consisting of (PATHNAME).  In a scalar context, packs its PATHNAME
 147 arguments as a SOCKADDR_UN and returns it.  If this is confusing, use
 148 pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
 149 These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
 150
 151 =item pack_sockaddr_un PATH
 152
 153 Takes one argument, a pathname. Returns the sockaddr_un structure with
 154 that path packed in with AF_UNIX filled in. For unix domain sockets, this
 155 structure is normally what you need for the arguments in bind(),
 156 connect(), and send(), and is also returned by getpeername(),
 157 getsockname() and recv().
 158
 159 =item unpack_sockaddr_un SOCKADDR_UN
 160
 161 Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
 162 and returns the pathname.  Will croak if the structure does not
 163 have AF_UNIX in the right place.
 164
 165 =back
 166
 167 =cut
 168
 169 use Carp;
 170 use warnings::register;
 171
 172 require Exporter;
 173 use XSLoader ();
 174 @ISA = qw(Exporter);
 175 @EXPORT = qw(
 176         inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
 177         pack_sockaddr_un unpack_sockaddr_un
 178         sockaddr_in sockaddr_un
 179         INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
 180         AF_802
 181         AF_AAL
 182         AF_APPLETALK
 183         AF_CCITT
 184         AF_CHAOS
 185         AF_CTF
 186         AF_DATAKIT
 187         AF_DECnet
 188         AF_DLI
 189         AF_ECMA
 190         AF_GOSIP
 191         AF_HYLINK
 192         AF_IMPLINK
 193         AF_INET
 194         AF_INET6
 195         AF_ISO
 196         AF_KEY
 197         AF_LAST
 198         AF_LAT
 199         AF_LINK
 200         AF_MAX
 201         AF_NBS
 202         AF_NIT
 203         AF_NS
 204         AF_OSI
 205         AF_OSINET
 206         AF_PUP
 207         AF_ROUTE
 208         AF_SNA
 209         AF_UNIX
 210         AF_UNSPEC
 211         AF_USER
 212         AF_WAN
 213         AF_X25
 214         IOV_MAX
 215         MSG_BCAST
 216         MSG_BTAG
 217         MSG_CTLFLAGS
 218         MSG_CTLIGNORE
 219         MSG_CTRUNC
 220         MSG_DONTROUTE
 221         MSG_DONTWAIT
 222         MSG_EOF
 223         MSG_EOR
 224         MSG_ERRQUEUE
 225         MSG_ETAG
 226         MSG_FIN
 227         MSG_MAXIOVLEN
 228         MSG_MCAST
 229         MSG_NOSIGNAL
 230         MSG_OOB
 231         MSG_PEEK
 232         MSG_PROXY
 233         MSG_RST
 234         MSG_SYN
 235         MSG_TRUNC
 236         MSG_URG
 237         MSG_WAITALL
 238         MSG_WIRE
 239         PF_802
 240         PF_AAL
 241         PF_APPLETALK
 242         PF_CCITT
 243         PF_CHAOS
 244         PF_CTF
 245         PF_DATAKIT
 246         PF_DECnet
 247         PF_DLI
 248         PF_ECMA
 249         PF_GOSIP
 250         PF_HYLINK
 251         PF_IMPLINK
 252         PF_INET
 253         PF_INET6
 254         PF_ISO
 255         PF_KEY
 256         PF_LAST
 257         PF_LAT
 258         PF_LINK
 259         PF_MAX
 260         PF_NBS
 261         PF_NIT
 262         PF_NS
 263         PF_OSI
 264         PF_OSINET
 265         PF_PUP
 266         PF_ROUTE
 267         PF_SNA
 268         PF_UNIX
 269         PF_UNSPEC
 270         PF_USER
 271         PF_WAN
 272         PF_X25
 273         SCM_CONNECT
 274         SCM_CREDENTIALS
 275         SCM_CREDS
 276         SCM_RIGHTS
 277         SCM_TIMESTAMP
 278         SHUT_RD
 279         SHUT_RDWR
 280         SHUT_WR
 281         SOCK_DGRAM
 282         SOCK_RAW
 283         SOCK_RDM
 284         SOCK_SEQPACKET
 285         SOCK_STREAM
 286         SOL_SOCKET
 287         SOMAXCONN
 288         SO_ACCEPTCONN
 289         SO_ATTACH_FILTER
 290         SO_BACKLOG
 291         SO_BROADCAST
 292         SO_CHAMELEON
 293         SO_DEBUG
 294         SO_DETACH_FILTER
 295         SO_DGRAM_ERRIND
 296         SO_DONTLINGER
 297         SO_DONTROUTE
 298         SO_ERROR
 299         SO_FAMILY
 300         SO_KEEPALIVE
 301         SO_LINGER
 302         SO_OOBINLINE
 303         SO_PASSCRED
 304         SO_PASSIFNAME
 305         SO_PEERCRED
 306         SO_PROTOCOL
 307         SO_PROTOTYPE
 308         SO_RCVBUF
 309         SO_RCVLOWAT
 310         SO_RCVTIMEO
 311         SO_REUSEADDR
 312         SO_REUSEPORT
 313         SO_SECURITY_AUTHENTICATION
 314         SO_SECURITY_ENCRYPTION_NETWORK
 315         SO_SECURITY_ENCRYPTION_TRANSPORT
 316         SO_SNDBUF
 317         SO_SNDLOWAT
 318         SO_SNDTIMEO
 319         SO_STATE
 320         SO_TYPE
 321         SO_USELOOPBACK
 322         SO_XOPEN
 323         SO_XSE
 324         UIO_MAXIOV
 325 );
 326
 327 @EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
 328
 329                IPPROTO_TCP
 330                TCP_KEEPALIVE
 331                TCP_MAXRT
 332                TCP_MAXSEG
 333                TCP_NODELAY
 334                TCP_STDURG);
 335
 336 %EXPORT_TAGS = (
 337     crlf    => [qw(CR LF CRLF $CR $LF $CRLF)],
 338     all     => [@EXPORT, @EXPORT_OK],
 339 );
 340
 341 BEGIN {
 342     sub CR   () {"\015"}
 343     sub LF   () {"\012"}
 344     sub CRLF () {"\015\012"}
 345 }
 346
 347 *CR   = \CR();
 348 *LF   = \LF();
 349 *CRLF = \CRLF();
 350
 351 sub sockaddr_in {
 352     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
 353         my($af, $port, @quad) = @_;
 354         warnings::warn "6-ARG sockaddr_in call is deprecated"
 355             if warnings::enabled();
 356         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
 357     } elsif (wantarray) {
 358         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
 359         unpack_sockaddr_in(@_);
 360     } else {
 361         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
 362         pack_sockaddr_in(@_);
 363     }
 364 }
 365
 366 sub sockaddr_un {
 367     if (wantarray) {
 368         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
 369         unpack_sockaddr_un(@_);
 370     } else {
 371         croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
 372         pack_sockaddr_un(@_);
 373     }
 374 }
 375
 376 sub AUTOLOAD {
 377     my($constname);
 378     ($constname = $AUTOLOAD) =~ s/.*:://;
 379     croak "&Socket::constant not defined" if $constname eq 'constant';
 380     my ($error, $val) = constant($constname);
 381     if ($error) {
 382         croak $error;
 383     }
 384     *$AUTOLOAD = sub { $val };
 385     goto &$AUTOLOAD;
 386 }
 387
 388 XSLoader::load 'Socket', $VERSION;
 389
 390 1;