ext/Socket/Socket.pm

   1 package Socket;
   2
   3 our($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
   4 $VERSION = "1.80";
   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         IP_OPTIONS
 227         IP_HDRINCL
 228         IP_TOS
 229         IP_TTL
 230         IP_RECVOPTS
 231         IP_RECVRETOPTS
 232         IP_RETOPTS
 233         MSG_BCAST
 234         MSG_BTAG
 235         MSG_CTLFLAGS
 236         MSG_CTLIGNORE
 237         MSG_CTRUNC
 238         MSG_DONTROUTE
 239         MSG_DONTWAIT
 240         MSG_EOF
 241         MSG_EOR
 242         MSG_ERRQUEUE
 243         MSG_ETAG
 244         MSG_FIN
 245         MSG_MAXIOVLEN
 246         MSG_MCAST
 247         MSG_NOSIGNAL
 248         MSG_OOB
 249         MSG_PEEK
 250         MSG_PROXY
 251         MSG_RST
 252         MSG_SYN
 253         MSG_TRUNC
 254         MSG_URG
 255         MSG_WAITALL
 256         MSG_WIRE
 257         PF_802
 258         PF_AAL
 259         PF_APPLETALK
 260         PF_CCITT
 261         PF_CHAOS
 262         PF_CTF
 263         PF_DATAKIT
 264         PF_DECnet
 265         PF_DLI
 266         PF_ECMA
 267         PF_GOSIP
 268         PF_HYLINK
 269         PF_IMPLINK
 270         PF_INET
 271         PF_INET6
 272         PF_ISO
 273         PF_KEY
 274         PF_LAST
 275         PF_LAT
 276         PF_LINK
 277         PF_MAX
 278         PF_NBS
 279         PF_NIT
 280         PF_NS
 281         PF_OSI
 282         PF_OSINET
 283         PF_PUP
 284         PF_ROUTE
 285         PF_SNA
 286         PF_UNIX
 287         PF_UNSPEC
 288         PF_USER
 289         PF_WAN
 290         PF_X25
 291         SCM_CONNECT
 292         SCM_CREDENTIALS
 293         SCM_CREDS
 294         SCM_RIGHTS
 295         SCM_TIMESTAMP
 296         SHUT_RD
 297         SHUT_RDWR
 298         SHUT_WR
 299         SOCK_DGRAM
 300         SOCK_RAW
 301         SOCK_RDM
 302         SOCK_SEQPACKET
 303         SOCK_STREAM
 304         SOL_SOCKET
 305         SOMAXCONN
 306         SO_ACCEPTCONN
 307         SO_ATTACH_FILTER
 308         SO_BACKLOG
 309         SO_BROADCAST
 310         SO_CHAMELEON
 311         SO_DEBUG
 312         SO_DETACH_FILTER
 313         SO_DGRAM_ERRIND
 314         SO_DONTLINGER
 315         SO_DONTROUTE
 316         SO_ERROR
 317         SO_FAMILY
 318         SO_KEEPALIVE
 319         SO_LINGER
 320         SO_OOBINLINE
 321         SO_PASSCRED
 322         SO_PASSIFNAME
 323         SO_PEERCRED
 324         SO_PROTOCOL
 325         SO_PROTOTYPE
 326         SO_RCVBUF
 327         SO_RCVLOWAT
 328         SO_RCVTIMEO
 329         SO_REUSEADDR
 330         SO_REUSEPORT
 331         SO_SECURITY_AUTHENTICATION
 332         SO_SECURITY_ENCRYPTION_NETWORK
 333         SO_SECURITY_ENCRYPTION_TRANSPORT
 334         SO_SNDBUF
 335         SO_SNDLOWAT
 336         SO_SNDTIMEO
 337         SO_STATE
 338         SO_TYPE
 339         SO_USELOOPBACK
 340         SO_XOPEN
 341         SO_XSE
 342         UIO_MAXIOV
 343 );
 344
 345 @EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
 346
 347                IPPROTO_IP
 348                IPPROTO_IPV6
 349                IPPROTO_RAW
 350                IPPROTO_ICMP
 351                IPPROTO_TCP
 352                IPPROTO_UDP
 353
 354                TCP_KEEPALIVE
 355                TCP_MAXRT
 356                TCP_MAXSEG
 357                TCP_NODELAY
 358                TCP_STDURG);
 359
 360 %EXPORT_TAGS = (
 361     crlf    => [qw(CR LF CRLF $CR $LF $CRLF)],
 362     all     => [@EXPORT, @EXPORT_OK],
 363 );
 364
 365 BEGIN {
 366     sub CR   () {"\015"}
 367     sub LF   () {"\012"}
 368     sub CRLF () {"\015\012"}
 369 }
 370
 371 *CR   = \CR();
 372 *LF   = \LF();
 373 *CRLF = \CRLF();
 374
 375 sub sockaddr_in {
 376     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
 377         my($af, $port, @quad) = @_;
 378         warnings::warn "6-ARG sockaddr_in call is deprecated"
 379             if warnings::enabled();
 380         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
 381     } elsif (wantarray) {
 382         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
 383         unpack_sockaddr_in(@_);
 384     } else {
 385         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
 386         pack_sockaddr_in(@_);
 387     }
 388 }
 389
 390 sub sockaddr_un {
 391     if (wantarray) {
 392         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
 393         unpack_sockaddr_un(@_);
 394     } else {
 395         croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
 396         pack_sockaddr_un(@_);
 397     }
 398 }
 399
 400 sub AUTOLOAD {
 401     my($constname);
 402     ($constname = $AUTOLOAD) =~ s/.*:://;
 403     croak "&Socket::constant not defined" if $constname eq 'constant';
 404     my ($error, $val) = constant($constname);
 405     if ($error) {
 406         croak $error;
 407     }
 408     *$AUTOLOAD = sub { $val };
 409     goto &$AUTOLOAD;
 410 }
 411
 412 XSLoader::load 'Socket', $VERSION;
 413
 414 1;