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