ext/Socket/Socket.pm

   1 package Socket;
   2 $VERSION = 1.5;
   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 These are only supported if your system has <sys/un.h>.
 121
 122 =item pack_sockaddr_un PATH
 123
 124 Takes one argument, a pathname. Returns the sockaddr_un structure with
 125 that path packed in with AF_UNIX filled in. For unix domain sockets, this
 126 structure is normally what you need for the arguments in bind(),
 127 connect(), and send(), and is also returned by getpeername(),
 128 getsockname() and recv().
 129
 130 =item unpack_sockaddr_un SOCKADDR_UN
 131
 132 Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
 133 and returns the pathname.  Will croak if the structure does not
 134 have AF_UNIX in the right place.
 135
 136 =cut
 137
 138 use Carp;
 139
 140 require Exporter;
 141 use AutoLoader;
 142 require DynaLoader;
 143 @ISA = qw(Exporter DynaLoader);
 144 @EXPORT = qw(
 145         inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
 146         pack_sockaddr_un unpack_sockaddr_un
 147         sockaddr_in sockaddr_un
 148         INADDR_ANY INADDR_LOOPBACK INADDR_NONE
 149         AF_802
 150         AF_APPLETALK
 151         AF_CCITT
 152         AF_CHAOS
 153         AF_DATAKIT
 154         AF_DECnet
 155         AF_DLI
 156         AF_ECMA
 157         AF_GOSIP
 158         AF_HYLINK
 159         AF_IMPLINK
 160         AF_INET
 161         AF_LAT
 162         AF_MAX
 163         AF_NBS
 164         AF_NIT
 165         AF_NS
 166         AF_OSI
 167         AF_OSINET
 168         AF_PUP
 169         AF_SNA
 170         AF_UNIX
 171         AF_UNSPEC
 172         AF_X25
 173         MSG_DONTROUTE
 174         MSG_MAXIOVLEN
 175         MSG_OOB
 176         MSG_PEEK
 177         PF_802
 178         PF_APPLETALK
 179         PF_CCITT
 180         PF_CHAOS
 181         PF_DATAKIT
 182         PF_DECnet
 183         PF_DLI
 184         PF_ECMA
 185         PF_GOSIP
 186         PF_HYLINK
 187         PF_IMPLINK
 188         PF_INET
 189         PF_LAT
 190         PF_MAX
 191         PF_NBS
 192         PF_NIT
 193         PF_NS
 194         PF_OSI
 195         PF_OSINET
 196         PF_PUP
 197         PF_SNA
 198         PF_UNIX
 199         PF_UNSPEC
 200         PF_X25
 201         SOCK_DGRAM
 202         SOCK_RAW
 203         SOCK_RDM
 204         SOCK_SEQPACKET
 205         SOCK_STREAM
 206         SOL_SOCKET
 207         SOMAXCONN
 208         SO_ACCEPTCONN
 209         SO_BROADCAST
 210         SO_DEBUG
 211         SO_DONTLINGER
 212         SO_DONTROUTE
 213         SO_ERROR
 214         SO_KEEPALIVE
 215         SO_LINGER
 216         SO_OOBINLINE
 217         SO_RCVBUF
 218         SO_RCVLOWAT
 219         SO_RCVTIMEO
 220         SO_REUSEADDR
 221         SO_SNDBUF
 222         SO_SNDLOWAT
 223         SO_SNDTIMEO
 224         SO_TYPE
 225         SO_USELOOPBACK
 226 );
 227
 228 sub sockaddr_in {
 229     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
 230         my($af, $port, @quad) = @_;
 231         carp "6-ARG sockaddr_in call is deprecated" if $^W;
 232         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
 233     } elsif (wantarray) {
 234         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
 235         unpack_sockaddr_in(@_);
 236     } else {
 237         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
 238         pack_sockaddr_in(@_);
 239     }
 240 }
 241
 242 sub sockaddr_un {
 243     if (wantarray) {
 244         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
 245         unpack_sockaddr_un(@_);
 246     } else {
 247         croak "usage:   sun_sv = sockaddr_un(filename))" unless @_ == 1;
 248         pack_sockaddr_in(@_);
 249     }
 250 }
 251
 252
 253 sub AUTOLOAD {
 254     local($constname);
 255     ($constname = $AUTOLOAD) =~ s/.*:://;
 256     $val = constant($constname, @_ ? $_[0] : 0);
 257     if ($! != 0) {
 258         if ($! =~ /Invalid/) {
 259             $AutoLoader::AUTOLOAD = $AUTOLOAD;
 260             goto &AutoLoader::AUTOLOAD;
 261         }
 262         else {
 263             ($pack,$file,$line) = caller;
 264             croak "Your vendor has not defined Socket macro $constname, used";
 265         }
 266     }
 267     eval "sub $AUTOLOAD { $val }";
 268     goto &$AUTOLOAD;
 269 }
 270
 271 bootstrap Socket;
 272
 273 # Preloaded methods go here.  Autoload methods go after __END__, and are
 274 # processed by the autosplit program.
 275
 276 1;
 277 __END__