ext/Socket/Socket.pm

   1 package Socket;
   2
   3 use vars qw($VERSION @ISA @EXPORT);
   4 $VERSION = "1.5";
   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.
  56
  57 =item inet_ntoa IP_ADDRESS
  58
  59 Takes a four byte ip address (as returned by inet_aton())
  60 and translates it into a string of the form 'd.d.d.d'
  61 where the 'd's are numbers less than 256 (the normal
  62 readable four dotted number notation for internet addresses).
  63
  64 =item INADDR_ANY
  65
  66 Note: does not return a number, but a packed string.
  67
  68 Returns the 4-byte wildcard ip address which specifies any
  69 of the hosts ip addresses. (A particular machine can have
  70 more than one ip address, each address corresponding to
  71 a particular network interface. This wildcard address
  72 allows you to bind to all of them simultaneously.)
  73 Normally equivalent to inet_aton('0.0.0.0').
  74
  75 =item INADDR_LOOPBACK
  76
  77 Note - does not return a number.
  78
  79 Returns the 4-byte loopback address. Normally equivalent
  80 to inet_aton('localhost').
  81
  82 =item INADDR_NONE
  83
  84 Note - does not return a number.
  85
  86 Returns the 4-byte invalid ip address. Normally equivalent
  87 to inet_aton('255.255.255.255').
  88
  89 =item sockaddr_in PORT, ADDRESS
  90
  91 =item sockaddr_in SOCKADDR_IN
  92
  93 In an array context, unpacks its SOCKADDR_IN argument and returns an array
  94 consisting of (PORT, ADDRESS).  In a scalar context, packs its (PORT,
  95 ADDRESS) arguments as a SOCKADDR_IN and returns it.  If this is confusing,
  96 use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
  97
  98 =item pack_sockaddr_in PORT, IP_ADDRESS
  99
 100 Takes two arguments, a port number and a 4 byte IP_ADDRESS (as returned by
 101 inet_aton()). Returns the sockaddr_in structure with those arguments
 102 packed in with AF_INET filled in.  For internet domain sockets, this
 103 structure is normally what you need for the arguments in bind(),
 104 connect(), and send(), and is also returned by getpeername(),
 105 getsockname() and recv().
 106
 107 =item unpack_sockaddr_in SOCKADDR_IN
 108
 109 Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
 110 returns an array of two elements: the port and the 4-byte ip-address.
 111 Will croak if the structure does not have AF_INET in the right place.
 112
 113 =item sockaddr_un PATHNAME
 114
 115 =item sockaddr_un SOCKADDR_UN
 116
 117 In an array context, unpacks its SOCKADDR_UN argument and returns an array
 118 consisting of (PATHNAME).  In a scalar context, packs its PATHANE
 119 arguments as a SOCKADDR_UN and returns it.  If this is confusing, use
 120 pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
 121 These are only supported if your system has <sys/un.h>.
 122
 123 =item pack_sockaddr_un PATH
 124
 125 Takes one argument, a pathname. Returns the sockaddr_un structure with
 126 that path packed in with AF_UNIX filled in. For unix domain sockets, this
 127 structure is normally what you need for the arguments in bind(),
 128 connect(), and send(), and is also returned by getpeername(),
 129 getsockname() and recv().
 130
 131 =item unpack_sockaddr_un SOCKADDR_UN
 132
 133 Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
 134 and returns the pathname.  Will croak if the structure does not
 135 have AF_UNIX in the right place.
 136
 137 =cut
 138
 139 use Carp;
 140
 141 require Exporter;
 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_un(@_);
 249     }
 250 }
 251
 252
 253 sub AUTOLOAD {
 254     my($constname);
 255     ($constname = $AUTOLOAD) =~ s/.*:://;
 256     my $val = constant($constname, @_ ? $_[0] : 0);
 257     if ($! != 0) {
 258         my ($pack,$file,$line) = caller;
 259         croak "Your vendor has not defined Socket macro $constname, used";
 260     }
 261     eval "sub $AUTOLOAD { $val }";
 262     goto &$AUTOLOAD;
 263 }
 264
 265 bootstrap Socket $VERSION;
 266
 267 1;