[Summary view] [Print] [Text view]

   1  package Socket;
   2  
   3  our($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
   4  $VERSION = "1.80";
   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', 'tcp');
  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('/var/run/usock');
  36      $sun = sockaddr_un('/var/run/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  Also, some common socket "newline" constants are provided: the
  49  constants C<CR>, C<LF>, and C<CRLF>, as well as C<$CR>, C<$LF>, and
  50  C<$CRLF>, which map to C<\015>, C<\012>, and C<\015\012>.  If you do
  51  not want to use the literal characters in your programs, then use
  52  the constants provided here.  They are not exported by default, but can
  53  be imported individually, and with the C<:crlf> export tag:
  54  
  55      use Socket qw(:DEFAULT :crlf);
  56  
  57  In addition, some structure manipulation functions are available:
  58  
  59  =over 4
  60  
  61  =item inet_aton HOSTNAME
  62  
  63  Takes a string giving the name of a host, and translates that to an
  64  opaque string (if programming in C, struct in_addr). Takes arguments
  65  of both the 'rtfm.mit.edu' type and '18.181.0.24'. If the host name
  66  cannot be resolved, returns undef.  For multi-homed hosts (hosts with
  67  more than one address), the first address found is returned.
  68  
  69  For portability do not assume that the result of inet_aton() is 32
  70  bits wide, in other words, that it would contain only the IPv4 address
  71  in network order.
  72  
  73  =item inet_ntoa IP_ADDRESS
  74  
  75  Takes a string (an opaque string as returned by inet_aton(),
  76  or a v-string representing the four octets of the IPv4 address in
  77  network order) and translates it into a string of the form 'd.d.d.d'
  78  where the 'd's are numbers less than 256 (the normal human-readable
  79  four dotted number notation for Internet addresses).
  80  
  81  =item INADDR_ANY
  82  
  83  Note: does not return a number, but a packed string.
  84  
  85  Returns the 4-byte wildcard ip address which specifies any
  86  of the hosts ip addresses.  (A particular machine can have
  87  more than one ip address, each address corresponding to
  88  a particular network interface. This wildcard address
  89  allows you to bind to all of them simultaneously.)
  90  Normally equivalent to inet_aton('0.0.0.0').
  91  
  92  =item INADDR_BROADCAST
  93  
  94  Note: does not return a number, but a packed string.
  95  
  96  Returns the 4-byte 'this-lan' ip broadcast address.
  97  This can be useful for some protocols to solicit information
  98  from all servers on the same LAN cable.
  99  Normally equivalent to inet_aton('255.255.255.255').
 100  
 101  =item INADDR_LOOPBACK
 102  
 103  Note - does not return a number.
 104  
 105  Returns the 4-byte loopback address.  Normally equivalent
 106  to inet_aton('localhost').
 107  
 108  =item INADDR_NONE
 109  
 110  Note - does not return a number.
 111  
 112  Returns the 4-byte 'invalid' ip address.  Normally equivalent
 113  to inet_aton('255.255.255.255').
 114  
 115  =item sockaddr_family SOCKADDR
 116  
 117  Takes a sockaddr structure (as returned by pack_sockaddr_in(),
 118  pack_sockaddr_un() or the perl builtin functions getsockname() and
 119  getpeername()) and returns the address family tag.  It will match the
 120  constant AF_INET for a sockaddr_in and AF_UNIX for a sockaddr_un.  It
 121  can be used to figure out what unpacker to use for a sockaddr of
 122  unknown type.
 123  
 124  =item sockaddr_in PORT, ADDRESS
 125  
 126  =item sockaddr_in SOCKADDR_IN
 127  
 128  In a list context, unpacks its SOCKADDR_IN argument and returns an array
 129  consisting of (PORT, ADDRESS).  In a scalar context, packs its (PORT,
 130  ADDRESS) arguments as a SOCKADDR_IN and returns it.  If this is confusing,
 131  use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
 132  
 133  =item pack_sockaddr_in PORT, IP_ADDRESS
 134  
 135  Takes two arguments, a port number and an opaque string, IP_ADDRESS
 136  (as returned by inet_aton(), or a v-string).  Returns the sockaddr_in
 137  structure with those arguments packed in with AF_INET filled in.  For
 138  Internet domain sockets, this structure is normally what you need for
 139  the arguments in bind(), connect(), and send(), and is also returned
 140  by getpeername(), getsockname() and recv().
 141  
 142  =item unpack_sockaddr_in SOCKADDR_IN
 143  
 144  Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
 145  returns an array of two elements: the port and an opaque string
 146  representing the IP address (you can use inet_ntoa() to convert the
 147  address to the four-dotted numeric format).  Will croak if the
 148  structure does not have AF_INET in the right place.
 149  
 150  =item sockaddr_un PATHNAME
 151  
 152  =item sockaddr_un SOCKADDR_UN
 153  
 154  In a list context, unpacks its SOCKADDR_UN argument and returns an array
 155  consisting of (PATHNAME).  In a scalar context, packs its PATHNAME
 156  arguments as a SOCKADDR_UN and returns it.  If this is confusing, use
 157  pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
 158  These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
 159  
 160  =item pack_sockaddr_un PATH
 161  
 162  Takes one argument, a pathname. Returns the sockaddr_un structure with
 163  that path packed in with AF_UNIX filled in. For unix domain sockets, this
 164  structure is normally what you need for the arguments in bind(),
 165  connect(), and send(), and is also returned by getpeername(),
 166  getsockname() and recv().
 167  
 168  =item unpack_sockaddr_un SOCKADDR_UN
 169  
 170  Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
 171  and returns the pathname.  Will croak if the structure does not
 172  have AF_UNIX in the right place.
 173  
 174  =back
 175  
 176  =cut
 177  
 178  use Carp;
 179  use warnings::register;
 180  
 181  require Exporter;
 182  use XSLoader ();
 183  @ISA = qw(Exporter);
 184  @EXPORT = qw(
 185      inet_aton inet_ntoa
 186      sockaddr_family
 187      pack_sockaddr_in unpack_sockaddr_in
 188      pack_sockaddr_un unpack_sockaddr_un
 189      sockaddr_in sockaddr_un
 190      INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
 191      AF_802
 192      AF_AAL
 193      AF_APPLETALK
 194      AF_CCITT
 195      AF_CHAOS
 196      AF_CTF
 197      AF_DATAKIT
 198      AF_DECnet
 199      AF_DLI
 200      AF_ECMA
 201      AF_GOSIP
 202      AF_HYLINK
 203      AF_IMPLINK
 204      AF_INET
 205      AF_INET6
 206      AF_ISO
 207      AF_KEY
 208      AF_LAST
 209      AF_LAT
 210      AF_LINK
 211      AF_MAX
 212      AF_NBS
 213      AF_NIT
 214      AF_NS
 215      AF_OSI
 216      AF_OSINET
 217      AF_PUP
 218      AF_ROUTE
 219      AF_SNA
 220      AF_UNIX
 221      AF_UNSPEC
 222      AF_USER
 223      AF_WAN
 224      AF_X25
 225      IOV_MAX
 226      IP_OPTIONS
 227      IP_HDRINCL
 228      IP_TOS
 229      IP_TTL
 230      IP_RECVOPTS
 231      IP_RECVRETOPTS
 232      IP_RETOPTS
 233      MSG_BCAST
 234      MSG_BTAG
 235      MSG_CTLFLAGS
 236      MSG_CTLIGNORE
 237      MSG_CTRUNC
 238      MSG_DONTROUTE
 239      MSG_DONTWAIT
 240      MSG_EOF
 241      MSG_EOR
 242      MSG_ERRQUEUE
 243      MSG_ETAG
 244      MSG_FIN
 245      MSG_MAXIOVLEN
 246      MSG_MCAST
 247      MSG_NOSIGNAL
 248      MSG_OOB
 249      MSG_PEEK
 250      MSG_PROXY
 251      MSG_RST
 252      MSG_SYN
 253      MSG_TRUNC
 254      MSG_URG
 255      MSG_WAITALL
 256      MSG_WIRE
 257      PF_802
 258      PF_AAL
 259      PF_APPLETALK
 260      PF_CCITT
 261      PF_CHAOS
 262      PF_CTF
 263      PF_DATAKIT
 264      PF_DECnet
 265      PF_DLI
 266      PF_ECMA
 267      PF_GOSIP
 268      PF_HYLINK
 269      PF_IMPLINK
 270      PF_INET
 271      PF_INET6
 272      PF_ISO
 273      PF_KEY
 274      PF_LAST
 275      PF_LAT
 276      PF_LINK
 277      PF_MAX
 278      PF_NBS
 279      PF_NIT
 280      PF_NS
 281      PF_OSI
 282      PF_OSINET
 283      PF_PUP
 284      PF_ROUTE
 285      PF_SNA
 286      PF_UNIX
 287      PF_UNSPEC
 288      PF_USER
 289      PF_WAN
 290      PF_X25
 291      SCM_CONNECT
 292      SCM_CREDENTIALS
 293      SCM_CREDS
 294      SCM_RIGHTS
 295      SCM_TIMESTAMP
 296      SHUT_RD
 297      SHUT_RDWR
 298      SHUT_WR
 299      SOCK_DGRAM
 300      SOCK_RAW
 301      SOCK_RDM
 302      SOCK_SEQPACKET
 303      SOCK_STREAM
 304      SOL_SOCKET
 305      SOMAXCONN
 306      SO_ACCEPTCONN
 307      SO_ATTACH_FILTER
 308      SO_BACKLOG
 309      SO_BROADCAST
 310      SO_CHAMELEON
 311      SO_DEBUG
 312      SO_DETACH_FILTER
 313      SO_DGRAM_ERRIND
 314      SO_DONTLINGER
 315      SO_DONTROUTE
 316      SO_ERROR
 317      SO_FAMILY
 318      SO_KEEPALIVE
 319      SO_LINGER
 320      SO_OOBINLINE
 321      SO_PASSCRED
 322      SO_PASSIFNAME
 323      SO_PEERCRED
 324      SO_PROTOCOL
 325      SO_PROTOTYPE
 326      SO_RCVBUF
 327      SO_RCVLOWAT
 328      SO_RCVTIMEO
 329      SO_REUSEADDR
 330      SO_REUSEPORT
 331      SO_SECURITY_AUTHENTICATION
 332      SO_SECURITY_ENCRYPTION_NETWORK
 333      SO_SECURITY_ENCRYPTION_TRANSPORT
 334      SO_SNDBUF
 335      SO_SNDLOWAT
 336      SO_SNDTIMEO
 337      SO_STATE
 338      SO_TYPE
 339      SO_USELOOPBACK
 340      SO_XOPEN
 341      SO_XSE
 342      UIO_MAXIOV
 343  );
 344  
 345  @EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
 346  
 347             IPPROTO_IP
 348             IPPROTO_IPV6
 349             IPPROTO_RAW
 350             IPPROTO_ICMP
 351             IPPROTO_TCP
 352             IPPROTO_UDP
 353  
 354             TCP_KEEPALIVE
 355             TCP_MAXRT
 356             TCP_MAXSEG
 357             TCP_NODELAY
 358             TCP_STDURG);
 359  
 360  %EXPORT_TAGS = (
 361      crlf    => [qw(CR LF CRLF $CR $LF $CRLF)],
 362      all     => [@EXPORT, @EXPORT_OK],
 363  );
 364  
 365  BEGIN {
 366      sub CR   () {"\015"}
 367      sub LF   () {"\012"}
 368      sub CRLF () {"\015\012"}
 369  }
 370  
 371  *CR   = \CR();
 372  *LF   = \LF();
 373  *CRLF = \CRLF();
 374  
 375  sub sockaddr_in {
 376      if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
 377      my($af, $port, @quad) = @_;
 378      warnings::warn "6-ARG sockaddr_in call is deprecated" 
 379          if warnings::enabled();
 380      pack_sockaddr_in($port, inet_aton(join('.', @quad)));
 381      } elsif (wantarray) {
 382      croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
 383          unpack_sockaddr_in(@_);
 384      } else {
 385      croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
 386          pack_sockaddr_in(@_);
 387      }
 388  }
 389  
 390  sub sockaddr_un {
 391      if (wantarray) {
 392      croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
 393          unpack_sockaddr_un(@_);
 394      } else {
 395      croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
 396          pack_sockaddr_un(@_);
 397      }
 398  }
 399  
 400  sub AUTOLOAD {
 401      my($constname);
 402      ($constname = $AUTOLOAD) =~ s/.*:://;
 403      croak "&Socket::constant not defined" if $constname eq 'constant';
 404      my ($error, $val) = constant($constname);
 405      if ($error) {
 406      croak $error;
 407      }
 408      *$AUTOLOAD = sub { $val };
 409      goto &$AUTOLOAD;
 410  }
 411  
 412  XSLoader::load 'Socket', $VERSION;
 413  
 414  1;