ext/Socket/Socket.pm

   1 package Socket;
   2
   3 use vars qw($VERSION @ISA @EXPORT);
   4 $VERSION = "1.6";
   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');
  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 In addition, some structure manipulation functions are available:
  49
  50 =over
  51
  52 =item inet_aton HOSTNAME
  53
  54 Takes a string giving the name of a host, and translates that
  55 to the 4-byte string (structure). Takes arguments of both
  56 the 'rtfm.mit.edu' type and '18.181.0.24'. If the host name
  57 cannot be resolved, returns undef. For multi-homed hosts (hosts
  58 with more than one address), the first address found is returned.
  59
  60 =item inet_ntoa IP_ADDRESS
  61
  62 Takes a four byte ip address (as returned by inet_aton())
  63 and translates it into a string of the form 'd.d.d.d'
  64 where the 'd's are numbers less than 256 (the normal
  65 readable four dotted number notation for internet addresses).
  66
  67 =item INADDR_ANY
  68
  69 Note: does not return a number, but a packed string.
  70
  71 Returns the 4-byte wildcard ip address which specifies any
  72 of the hosts ip addresses. (A particular machine can have
  73 more than one ip address, each address corresponding to
  74 a particular network interface. This wildcard address
  75 allows you to bind to all of them simultaneously.)
  76 Normally equivalent to inet_aton('0.0.0.0').
  77
  78 =item INADDR_BROADCAST
  79
  80 Note: does not return a number, but a packed string.
  81
  82 Returns the 4-byte 'this-lan' ip broadcast address.
  83 This can be useful for some protocols to solicit information
  84 from all servers on the same LAN cable.
  85 Normally equivalent to inet_aton('255.255.255.255').
  86
  87 =item INADDR_LOOPBACK
  88
  89 Note - does not return a number.
  90
  91 Returns the 4-byte loopback address. Normally equivalent
  92 to inet_aton('localhost').
  93
  94 =item INADDR_NONE
  95
  96 Note - does not return a number.
  97
  98 Returns the 4-byte 'invalid' ip address. Normally equivalent
  99 to inet_aton('255.255.255.255').
 100
 101 =item sockaddr_in PORT, ADDRESS
 102
 103 =item sockaddr_in SOCKADDR_IN
 104
 105 In an array context, unpacks its SOCKADDR_IN argument and returns an array
 106 consisting of (PORT, ADDRESS).  In a scalar context, packs its (PORT,
 107 ADDRESS) arguments as a SOCKADDR_IN and returns it.  If this is confusing,
 108 use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
 109
 110 =item pack_sockaddr_in PORT, IP_ADDRESS
 111
 112 Takes two arguments, a port number and a 4 byte IP_ADDRESS (as returned by
 113 inet_aton()). Returns the sockaddr_in structure with those arguments
 114 packed in with AF_INET filled in.  For internet domain sockets, this
 115 structure is normally what you need for the arguments in bind(),
 116 connect(), and send(), and is also returned by getpeername(),
 117 getsockname() and recv().
 118
 119 =item unpack_sockaddr_in SOCKADDR_IN
 120
 121 Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
 122 returns an array of two elements: the port and the 4-byte ip-address.
 123 Will croak if the structure does not have AF_INET in the right place.
 124
 125 =item sockaddr_un PATHNAME
 126
 127 =item sockaddr_un SOCKADDR_UN
 128
 129 In an array context, unpacks its SOCKADDR_UN argument and returns an array
 130 consisting of (PATHNAME).  In a scalar context, packs its PATHNAME
 131 arguments as a SOCKADDR_UN and returns it.  If this is confusing, use
 132 pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
 133 These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
 134
 135 =item pack_sockaddr_un PATH
 136
 137 Takes one argument, a pathname. Returns the sockaddr_un structure with
 138 that path packed in with AF_UNIX filled in. For unix domain sockets, this
 139 structure is normally what you need for the arguments in bind(),
 140 connect(), and send(), and is also returned by getpeername(),
 141 getsockname() and recv().
 142
 143 =item unpack_sockaddr_un SOCKADDR_UN
 144
 145 Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
 146 and returns the pathname.  Will croak if the structure does not
 147 have AF_UNIX in the right place.
 148
 149 =back
 150
 151 =cut
 152
 153 use Carp;
 154
 155 require Exporter;
 156 require DynaLoader;
 157 @ISA = qw(Exporter DynaLoader);
 158 @EXPORT = qw(
 159         inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
 160         pack_sockaddr_un unpack_sockaddr_un
 161         sockaddr_in sockaddr_un
 162         INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
 163         AF_802
 164         AF_APPLETALK
 165         AF_CCITT
 166         AF_CHAOS
 167         AF_DATAKIT
 168         AF_DECnet
 169         AF_DLI
 170         AF_ECMA
 171         AF_GOSIP
 172         AF_HYLINK
 173         AF_IMPLINK
 174         AF_INET
 175         AF_LAT
 176         AF_MAX
 177         AF_NBS
 178         AF_NIT
 179         AF_NS
 180         AF_OSI
 181         AF_OSINET
 182         AF_PUP
 183         AF_SNA
 184         AF_UNIX
 185         AF_UNSPEC
 186         AF_X25
 187         MSG_DONTROUTE
 188         MSG_MAXIOVLEN
 189         MSG_OOB
 190         MSG_PEEK
 191         PF_802
 192         PF_APPLETALK
 193         PF_CCITT
 194         PF_CHAOS
 195         PF_DATAKIT
 196         PF_DECnet
 197         PF_DLI
 198         PF_ECMA
 199         PF_GOSIP
 200         PF_HYLINK
 201         PF_IMPLINK
 202         PF_INET
 203         PF_LAT
 204         PF_MAX
 205         PF_NBS
 206         PF_NIT
 207         PF_NS
 208         PF_OSI
 209         PF_OSINET
 210         PF_PUP
 211         PF_SNA
 212         PF_UNIX
 213         PF_UNSPEC
 214         PF_X25
 215         SOCK_DGRAM
 216         SOCK_RAW
 217         SOCK_RDM
 218         SOCK_SEQPACKET
 219         SOCK_STREAM
 220         SOL_SOCKET
 221         SOMAXCONN
 222         SO_ACCEPTCONN
 223         SO_BROADCAST
 224         SO_DEBUG
 225         SO_DONTLINGER
 226         SO_DONTROUTE
 227         SO_ERROR
 228         SO_KEEPALIVE
 229         SO_LINGER
 230         SO_OOBINLINE
 231         SO_RCVBUF
 232         SO_RCVLOWAT
 233         SO_RCVTIMEO
 234         SO_REUSEADDR
 235         SO_SNDBUF
 236         SO_SNDLOWAT
 237         SO_SNDTIMEO
 238         SO_TYPE
 239         SO_USELOOPBACK
 240 );
 241
 242 sub sockaddr_in {
 243     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
 244         my($af, $port, @quad) = @_;
 245         carp "6-ARG sockaddr_in call is deprecated" if $^W;
 246         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
 247     } elsif (wantarray) {
 248         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
 249         unpack_sockaddr_in(@_);
 250     } else {
 251         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
 252         pack_sockaddr_in(@_);
 253     }
 254 }
 255
 256 sub sockaddr_un {
 257     if (wantarray) {
 258         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
 259         unpack_sockaddr_un(@_);
 260     } else {
 261         croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
 262         pack_sockaddr_un(@_);
 263     }
 264 }
 265
 266
 267 sub AUTOLOAD {
 268     my($constname);
 269     ($constname = $AUTOLOAD) =~ s/.*:://;
 270     my $val = constant($constname, @_ ? $_[0] : 0);
 271     if ($! != 0) {
 272         my ($pack,$file,$line) = caller;
 273         croak "Your vendor has not defined Socket macro $constname, used";
 274     }
 275     eval "sub $AUTOLOAD { $val }";
 276     goto &$AUTOLOAD;
 277 }
 278
 279 bootstrap Socket $VERSION;
 280
 281 1;