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_APPLETALK
 182         AF_CCITT
 183         AF_CHAOS
 184         AF_DATAKIT
 185         AF_DECnet
 186         AF_DLI
 187         AF_ECMA
 188         AF_GOSIP
 189         AF_HYLINK
 190         AF_IMPLINK
 191         AF_INET
 192         AF_LAT
 193         AF_MAX
 194         AF_NBS
 195         AF_NIT
 196         AF_NS
 197         AF_OSI
 198         AF_OSINET
 199         AF_PUP
 200         AF_SNA
 201         AF_UNIX
 202         AF_UNSPEC
 203         AF_X25
 204         IOV_MAX
 205         MSG_BCAST
 206         MSG_CTLFLAGS
 207         MSG_CTLIGNORE
 208         MSG_CTRUNC
 209         MSG_DONTROUTE
 210         MSG_DONTWAIT
 211         MSG_EOF
 212         MSG_EOR
 213         MSG_ERRQUEUE
 214         MSG_FIN
 215         MSG_MAXIOVLEN
 216         MSG_MCAST
 217         MSG_NOSIGNAL
 218         MSG_OOB
 219         MSG_PEEK
 220         MSG_PROXY
 221         MSG_RST
 222         MSG_SYN
 223         MSG_TRUNC
 224         MSG_URG
 225         MSG_WAITALL
 226         PF_802
 227         PF_APPLETALK
 228         PF_CCITT
 229         PF_CHAOS
 230         PF_DATAKIT
 231         PF_DECnet
 232         PF_DLI
 233         PF_ECMA
 234         PF_GOSIP
 235         PF_HYLINK
 236         PF_IMPLINK
 237         PF_INET
 238         PF_LAT
 239         PF_MAX
 240         PF_NBS
 241         PF_NIT
 242         PF_NS
 243         PF_OSI
 244         PF_OSINET
 245         PF_PUP
 246         PF_SNA
 247         PF_UNIX
 248         PF_UNSPEC
 249         PF_X25
 250         SCM_CONNECT
 251         SCM_CREDENTIALS
 252         SCM_CREDS
 253         SCM_RIGHTS
 254         SCM_TIMESTAMP
 255         SHUT_RD
 256         SHUT_RDWR
 257         SHUT_WR
 258         SOCK_DGRAM
 259         SOCK_RAW
 260         SOCK_RDM
 261         SOCK_SEQPACKET
 262         SOCK_STREAM
 263         SOL_SOCKET
 264         SOMAXCONN
 265         SO_ACCEPTCONN
 266         SO_BROADCAST
 267         SO_DEBUG
 268         SO_DONTLINGER
 269         SO_DONTROUTE
 270         SO_ERROR
 271         SO_KEEPALIVE
 272         SO_LINGER
 273         SO_OOBINLINE
 274         SO_RCVBUF
 275         SO_RCVLOWAT
 276         SO_RCVTIMEO
 277         SO_REUSEADDR
 278         SO_REUSEPORT
 279         SO_SNDBUF
 280         SO_SNDLOWAT
 281         SO_SNDTIMEO
 282         SO_TYPE
 283         SO_USELOOPBACK
 284         UIO_MAXIOV
 285 );
 286
 287 @EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
 288
 289                IPPROTO_TCP
 290                TCP_KEEPALIVE
 291                TCP_MAXRT
 292                TCP_MAXSEG
 293                TCP_NODELAY
 294                TCP_STDURG);
 295
 296 %EXPORT_TAGS = (
 297     crlf    => [qw(CR LF CRLF $CR $LF $CRLF)],
 298     all     => [@EXPORT, @EXPORT_OK],
 299 );
 300
 301 BEGIN {
 302     sub CR   () {"\015"}
 303     sub LF   () {"\012"}
 304     sub CRLF () {"\015\012"}
 305 }
 306
 307 *CR   = \CR();
 308 *LF   = \LF();
 309 *CRLF = \CRLF();
 310
 311 sub sockaddr_in {
 312     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
 313         my($af, $port, @quad) = @_;
 314         warnings::warn "6-ARG sockaddr_in call is deprecated"
 315             if warnings::enabled();
 316         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
 317     } elsif (wantarray) {
 318         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
 319         unpack_sockaddr_in(@_);
 320     } else {
 321         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
 322         pack_sockaddr_in(@_);
 323     }
 324 }
 325
 326 sub sockaddr_un {
 327     if (wantarray) {
 328         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
 329         unpack_sockaddr_un(@_);
 330     } else {
 331         croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
 332         pack_sockaddr_un(@_);
 333     }
 334 }
 335
 336 sub AUTOLOAD {
 337     my($constname);
 338     ($constname = $AUTOLOAD) =~ s/.*:://;
 339     croak "&Socket::constant not defined" if $constname eq 'constant';
 340     my ($error, $val) = constant($constname);
 341     if ($error) {
 342         croak $error;
 343     }
 344     *$AUTOLOAD = sub { $val };
 345     goto &$AUTOLOAD;
 346 }
 347
 348 XSLoader::load 'Socket', $VERSION;
 349
 350 1;