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