ext/Socket/Socket.pm

   1 package Socket;
   2 $VERSION = 1.3;
   3
   4 =head1 NAME
   5
   6 Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa - load the C
   7     socket.h defines and structure manipulators
   8
   9 =head1 SYNOPSIS
  10
  11     use Socket;
  12
  13     $proto = getprotobyname('udp');
  14     socket(Socket_Handle, PF_INET, SOCK_DGRAM, $proto);
  15     $iaddr = gethostbyname('hishost.com');
  16     $port = getservbyname('time', 'udp');
  17     $sin = sockaddr_in($port, $iaddr);
  18     send(Socket_Handle, 0, 0, $sin);
  19
  20     $proto = getprotobyname('tcp');
  21     socket(Socket_Handle, PF_INET, SOCK_STREAM, $proto);
  22     $port = getservbyname('smtp');
  23     $sin = sockaddr_in($port,inet_aton("127.1"));
  24     $sin = sockaddr_in(7,inet_aton("localhost"));
  25     $sin = sockaddr_in(7,INADDR_LOOPBACK);
  26     connect(Socket_Handle,$sin);
  27
  28     ($port, $iaddr) = sockaddr_in(getpeername(Socket_Handle));
  29     $peer_host = gethostbyaddr($iaddr, AF_INET);
  30     $peer_addr = inet_ntoa($iaddr);
  31
  32     $proto = getprotobyname('tcp');
  33     socket(Socket_Handle, PF_UNIX, SOCK_STREAM, $proto);
  34     unlink('/tmp/usock');
  35     $sun = sockaddr_un('/tmp/usock');
  36     connect(Socket_Handle,$sun);
  37
  38 =head1 DESCRIPTION
  39
  40 This module is just a translation of the C F<socket.h> file.
  41 Unlike the old mechanism of requiring a translated F<socket.ph>
  42 file, this uses the B<h2xs> program (see the Perl source distribution)
  43 and your native C compiler.  This means that it has a
  44 far more likely chance of getting the numbers right.  This includes
  45 all of the commonly used pound-defines like AF_INET, SOCK_STREAM, etc.
  46
  47 In addition, some structure manipulation functions are available:
  48
  49 =item inet_aton HOSTNAME
  50
  51 Takes a string giving the name of a host, and translates that
  52 to the 4-byte string (structure). Takes arguments of both
  53 the 'rtfm.mit.edu' type and '18.181.0.24'. If the host name
  54 cannot be resolved, returns undef.
  55
  56 =item inet_ntoa IP_ADDRESS
  57
  58 Takes a four byte ip address (as returned by inet_aton())
  59 and translates it into a string of the form 'd.d.d.d'
  60 where the 'd's are numbers less than 256 (the normal
  61 readable four dotted number notation for internet addresses).
  62
  63 =item INADDR_ANY
  64
  65 Note: does not return a number, but a packed string.
  66
  67 Returns the 4-byte wildcard ip address which specifies any
  68 of the hosts ip addresses. (A particular machine can have
  69 more than one ip address, each address corresponding to
  70 a particular network interface. This wildcard address
  71 allows you to bind to all of them simultaneously.)
  72 Normally equivalent to inet_aton('0.0.0.0').
  73
  74 =item INADDR_LOOPBACK
  75
  76 Note - does not return a number.
  77
  78 Returns the 4-byte loopback address. Normally equivalent
  79 to inet_aton('localhost').
  80
  81 =item INADDR_NONE
  82
  83 Note - does not return a number.
  84
  85 Returns the 4-byte invalid ip address. Normally equivalent
  86 to inet_aton('255.255.255.255').
  87
  88 =item sockaddr_in PORT, ADDRESS
  89
  90 =item sockaddr_in SOCKADDR_IN
  91
  92 In an array context, unpacks its SOCKADDR_IN argument and returns an array
  93 consisting of (PORT, ADDRESS).  In a scalar context, packs its (PORT,
  94 ADDRESS) arguments as a SOCKADDR_IN and returns it.  If this is confusing,
  95 use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
  96
  97 =item pack_sockaddr_in PORT, IP_ADDRESS
  98
  99 Takes two arguments, a port number and a 4 byte IP_ADDRESS (as returned by
 100 inet_aton()). Returns the sockaddr_in structure with those arguments
 101 packed in with AF_INET filled in.  For internet domain sockets, this
 102 structure is normally what you need for the arguments in bind(),
 103 connect(), and send(), and is also returned by getpeername(),
 104 getsockname() and recv().
 105
 106 =item unpack_sockaddr_in SOCKADDR_IN
 107
 108 Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
 109 returns an array of two elements: the port and the 4-byte ip-address.
 110 Will croak if the structure does not have AF_INET in the right place.
 111
 112 =item sockaddr_un PATHNAME
 113
 114 =item sockaddr_un SOCKADDR_UN
 115
 116 In an array context, unpacks its SOCKADDR_UN argument and returns an array
 117 consisting of (PATHNAME).  In a scalar context, packs its PATHANE
 118 arguments as a SOCKADDR_UN and returns it.  If this is confusing, use
 119 pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
 120
 121 =item pack_sockaddr_un PATH
 122
 123 Takes one argument, a pathname. Returns the sockaddr_un structure with
 124 that path packed in with AF_UNIX filled in. For unix domain sockets, this
 125 structure is normally what you need for the arguments in bind(),
 126 connect(), and send(), and is also returned by getpeername(),
 127 getsockname() and recv().
 128
 129 =item unpack_sockaddr_un SOCKADDR_UN
 130
 131 Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
 132 and returns the pathname.  Will croak if the structure does not
 133 have AF_UNIX in the right place.
 134
 135 =cut
 136
 137 use Carp;
 138
 139 require Exporter;
 140 use AutoLoader;
 141 require DynaLoader;
 142 @ISA = qw(Exporter DynaLoader);
 143 @EXPORT = qw(
 144         inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
 145         pack_sockaddr_un unpack_sockaddr_un
 146         sockaddr_in sockaddr_un
 147         INADDR_ANY INADDR_LOOPBACK INADDR_NONE
 148         AF_802
 149         AF_APPLETALK
 150         AF_CCITT
 151         AF_CHAOS
 152         AF_DATAKIT
 153         AF_DECnet
 154         AF_DLI
 155         AF_ECMA
 156         AF_GOSIP
 157         AF_HYLINK
 158         AF_IMPLINK
 159         AF_INET
 160         AF_LAT
 161         AF_MAX
 162         AF_NBS
 163         AF_NIT
 164         AF_NS
 165         AF_OSI
 166         AF_OSINET
 167         AF_PUP
 168         AF_SNA
 169         AF_UNIX
 170         AF_UNSPEC
 171         AF_X25
 172         MSG_DONTROUTE
 173         MSG_MAXIOVLEN
 174         MSG_OOB
 175         MSG_PEEK
 176         PF_802
 177         PF_APPLETALK
 178         PF_CCITT
 179         PF_CHAOS
 180         PF_DATAKIT
 181         PF_DECnet
 182         PF_DLI
 183         PF_ECMA
 184         PF_GOSIP
 185         PF_HYLINK
 186         PF_IMPLINK
 187         PF_INET
 188         PF_LAT
 189         PF_MAX
 190         PF_NBS
 191         PF_NIT
 192         PF_NS
 193         PF_OSI
 194         PF_OSINET
 195         PF_PUP
 196         PF_SNA
 197         PF_UNIX
 198         PF_UNSPEC
 199         PF_X25
 200         SOCK_DGRAM
 201         SOCK_RAW
 202         SOCK_RDM
 203         SOCK_SEQPACKET
 204         SOCK_STREAM
 205         SOL_SOCKET
 206         SOMAXCONN
 207         SO_ACCEPTCONN
 208         SO_BROADCAST
 209         SO_DEBUG
 210         SO_DONTLINGER
 211         SO_DONTROUTE
 212         SO_ERROR
 213         SO_KEEPALIVE
 214         SO_LINGER
 215         SO_OOBINLINE
 216         SO_RCVBUF
 217         SO_RCVLOWAT
 218         SO_RCVTIMEO
 219         SO_REUSEADDR
 220         SO_SNDBUF
 221         SO_SNDLOWAT
 222         SO_SNDTIMEO
 223         SO_TYPE
 224         SO_USELOOPBACK
 225 );
 226
 227 sub sockaddr_in {
 228     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
 229         my($af, $port, @quad) = @_;
 230         carp "6-ARG sockaddr_in call is deprecated" if $^W;
 231         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
 232     } elsif (wantarray) {
 233         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
 234         unpack_sockaddr_in(@_);
 235     } else {
 236         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
 237         pack_sockaddr_in(@_);
 238     }
 239 }
 240
 241 sub sockaddr_un {
 242     if (wantarray) {
 243         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
 244         unpack_sockaddr_un(@_);
 245     } else {
 246         croak "usage:   sun_sv = sockaddr_un(filename))" unless @_ == 1;
 247         pack_sockaddr_in(@_);
 248     }
 249 }
 250
 251
 252 sub AUTOLOAD {
 253     local($constname);
 254     ($constname = $AUTOLOAD) =~ s/.*:://;
 255     $val = constant($constname, @_ ? $_[0] : 0);
 256     if ($! != 0) {
 257         if ($! =~ /Invalid/) {
 258             $AutoLoader::AUTOLOAD = $AUTOLOAD;
 259             goto &AutoLoader::AUTOLOAD;
 260         }
 261         else {
 262             ($pack,$file,$line) = caller;
 263             croak "Your vendor has not defined Socket macro $constname, used";
 264         }
 265     }
 266     eval "sub $AUTOLOAD { $val }";
 267     goto &$AUTOLOAD;
 268 }
 269
 270 bootstrap Socket;
 271
 272 # Preloaded methods go here.  Autoload methods go after __END__, and are
 273 # processed by the autosplit program.
 274
 275 1;
 276 __END__