7 IO::Socket - supply object methods for sockets
15 C<IO::Socket> provides an object interface to creating and using sockets. It
16 is built upon the L<IO::Handle> interface and inherits all the methods defined
19 C<IO::Socket> only defines methods for those operations which are common to all
20 types of socket. Operations which are specified to a socket in a particular
21 domain have methods defined in sub classes of C<IO::Socket>
23 See L<perlfunc> for complete descriptions of each of the following
24 supported C<IO::Seekable> methods, which are just front ends for the
25 corresponding built-in functions:
34 peername (getpeername)
35 sockname (getsockname)
37 Some methods take slightly different arguments to those defined in L<perlfunc>
38 in attempt to make the interface more flexible. These are
42 perform the system call C<accept> on the socket and return a new object. The
43 new object will be created in the same class as the listen socket, unless
44 C<PKG> is specified. This object can be used to communicate with the client
45 that was trying to connect. In a scalar context the new socket is returned,
46 or undef upon failure. In an array context a two-element array is returned
47 containing the new socket and the peer address, the list will
48 be empty upon failure.
50 Additional methods that are provided are
54 Set or get the timeout value associated with this socket. If called without
55 any arguments then the current setting is returned. If called with an argument
56 the current setting is changed and the previous value returned.
58 =item sockopt(OPT [, VAL])
60 Unified method to both set and get options in the SOL_SOCKET level. If called
61 with one argument then getsockopt is called, otherwise setsockopt is called
73 use vars qw(@ISA @EXPORT_OK $VERSION);
76 @ISA = qw(IO::Handle);
78 # This one will turn 1.2 => 1.02 and 1.2.3 => 1.0203 and so on ...
79 $VERSION = do{my @r=(q$Revision: 1.8$=~/(\d+)/g);sprintf "%d."."%02d"x$#r,@r};
84 Exporter::export 'Socket', $callpkg, @_;
89 my $fh = $class->SUPER::new();
91 ${*$fh}{'io_socket_timeout'} = delete $arg{Timeout};
93 return scalar(%arg) ? $fh->configure(\%arg)
98 croak 'IO::Socket: Cannot configure a generic socket';
102 @_ == 4 or croak 'usage: $fh->socket(DOMAIN, TYPE, PROTOCOL)';
103 my($fh,$domain,$type,$protocol) = @_;
105 socket($fh,$domain,$type,$protocol) or
108 ${*$fh}{'io_socket_type'} = $type;
113 @_ == 4 || croak 'usage: IO::Socket->pair(DOMAIN, TYPE, PROTOCOL)';
114 my($class,$domain,$type,$protocol) = @_;
115 my $fh1 = $class->new();
116 my $fh2 = $class->new();
118 socketpair($fh1,$fh1,$domain,$type,$protocol) or
121 ${*$fh1}{'io_socket_type'} = ${*$fh2}{'io_socket_type'} = $type;
127 @_ == 2 || @_ == 3 or croak 'usage: $fh->connect(NAME) or $fh->connect(PORT, ADDR)';
129 my $addr = @_ == 1 ? shift : sockaddr_in(@_);
130 my $timeout = ${*$fh}{'io_socket_timeout'};
131 local($SIG{ALRM}) = $timeout ? sub { undef $fh; }
132 : $SIG{ALRM} || 'DEFAULT';
135 croak 'connect: Bad address'
136 if(@_ == 2 && !defined $_[1]);
139 defined $Config{d_alarm} && defined alarm($timeout) or
143 my $ok = eval { connect($fh, $addr) };
148 croak "connect: timeout"
151 undef $fh unless $ok;
158 @_ == 2 || @_ == 3 or croak 'usage: $fh->bind(NAME) or $fh->bind(PORT, ADDR)';
160 my $addr = @_ == 1 ? shift : sockaddr_in(@_);
162 return bind($fh, $addr) ? $fh
167 @_ >= 1 && @_ <= 2 or croak 'usage: $fh->listen([QUEUE])';
170 unless $queue && $queue > 0;
172 return listen($fh, $queue) ? $fh
177 @_ == 1 || @_ == 2 or croak 'usage $fh->accept([PKG])';
179 my $pkg = shift || $fh;
180 my $timeout = ${*$fh}{'io_socket_timeout'};
181 my $new = $pkg->new(Timeout => $timeout);
187 vec($fdset, $fh->fileno,1) = 1;
188 croak "accept: timeout"
189 unless select($fdset,undef,undef,$timeout);
191 $peer = accept($new,$fh);
194 return wantarray ? defined $peer ? ($new, $peer)
196 : defined $peer ? $new
201 @_ == 1 or croak 'usage: $fh->sockname()';
206 @_ == 1 or croak 'usage: $fh->peername()';
209 || ${*$fh}{'io_socket_peername'}
214 @_ >= 2 && @_ <= 4 or croak 'usage: $fh->send(BUF, [FLAGS, [TO]])';
216 my $flags = $_[2] || 0;
217 my $peer = $_[3] || $fh->peername;
219 croak 'send: Cannot determine peer address'
222 my $r = send($fh, $_[1], $flags, $peer);
224 # remember who we send to, if it was sucessful
225 ${*$fh}{'io_socket_peername'} = $peer
226 if(@_ == 4 && defined $r);
232 @_ == 3 || @_ == 4 or croak 'usage: $fh->recv(BUF, LEN [, FLAGS])';
235 my $flags = $_[3] || 0;
237 # remember who we recv'd from
238 ${*$sock}{'io_socket_peername'} = recv($sock, $_[1]='', $len, $flags);
243 @_ == 4 or croak '$fh->setsockopt(LEVEL, OPTNAME)';
244 setsockopt($_[0],$_[1],$_[2],$_[3]);
247 my $intsize = length(pack("i",0));
250 @_ == 3 or croak '$fh->getsockopt(LEVEL, OPTNAME)';
251 my $r = getsockopt($_[0],$_[1],$_[2]);
254 if(defined $r && length($r) == $intsize);
260 @_ == 1 ? $fh->getsockopt(SOL_SOCKET,@_)
261 : $fh->setsockopt(SOL_SOCKET,@_);
265 @_ == 1 || @_ == 2 or croak 'usage: $fh->timeout([VALUE])';
267 my $r = ${*$fh}{'io_socket_timeout'} || undef;
269 ${*$fh}{'io_socket_timeout'} = 0 + $val
276 @_ == 1 or croak '$fh->socktype()';
277 ${*{$_[0]}}{'io_socket_type'} || undef;
288 package IO::Socket::INET;
291 use vars qw(@ISA $VERSION);
296 @ISA = qw(IO::Socket);
298 my %socket_type = ( tcp => SOCK_STREAM,
302 =head2 IO::Socket::INET
304 C<IO::Socket::INET> provides a constructor to create an AF_INET domain socket
305 and some related methods. The constructor can take the following options
307 PeerAddr Remote host address
308 PeerPort Remote port or service
309 LocalPort Local host bind port
310 LocalAddr Local host bind address
311 Proto Protocol name (eg tcp udp etc)
312 Type Socket type (SOCK_STREAM etc)
313 Listen Queue size for listen
314 Timeout Timeout value for various operations
316 If Listen is defined then a listen socket is created, else if the socket
317 type, which is derived from the protocol, is SOCK_STREAM then a connect
320 Only one of C<Type> or C<Proto> needs to be specified, one will be assumed
327 Return the address part of the sockaddr structure for the socket
331 Return the port number that the socket is using on the local host
335 Return the address part of the sockaddr structure for the socket in a
336 text form xx.xx.xx.xx
338 =item peeraddr(), peerport(), peerhost()
340 Same as for the sock* functions, but returns the data about the peer
341 host instead of the local host.
347 my($addr,$port,$proto) = @_;
352 if(defined $addr && $addr =~ s,:([\w\(\)/]+)$,,);
355 @proto = $proto =~ m,\D, ? getprotobyname($proto)
356 : getprotobynumber($proto);
358 $proto = $proto[2] || undef;
362 $port =~ s,\((\d+)\)$,,;
364 my $defport = $1 || undef;
365 my $pnum = ($port =~ m,^(\d+)$,)[0];
367 @serv= getservbyname($port, $proto[0] || "")
370 $port = $pnum || $serv[2] || $defport || undef;
372 $proto = (getprotobyname($serv[3]))[2] || undef
376 return ($addr || undef,
384 my($lport,$rport,$laddr,$raddr,$proto,$type);
387 ($laddr,$lport,$proto) = _sock_info($arg->{LocalAddr},
391 $laddr = defined $laddr ? inet_aton($laddr)
394 unless(exists $arg->{Listen}) {
395 ($raddr,$rport,$proto) = _sock_info($arg->{PeerAddr},
400 croak 'IO::Socket: Cannot determine protocol'
403 my $pname = (getprotobynumber($proto))[0];
404 $type = $arg->{Type} || $socket_type{$pname};
406 $fh->socket(AF_INET, $type, $proto) or
409 $fh->bind($lport || 0, $laddr) or
412 if(exists $arg->{Listen}) {
413 $fh->listen($arg->{Listen} || 5) or
417 croak "IO::Socket: Cannot determine remote port"
418 unless($rport || $type == SOCK_DGRAM);
420 if($type == SOCK_STREAM || defined $raddr) {
421 croak "IO::Socket: Bad peer address"
422 unless defined $raddr;
424 $fh->connect($rport,inet_aton($raddr)) or
433 @_ == 1 or croak 'usage: $fh->sockaddr()';
435 (sockaddr_in($fh->sockname))[1];
439 @_ == 1 or croak 'usage: $fh->sockport()';
441 (sockaddr_in($fh->sockname))[0];
445 @_ == 1 or croak 'usage: $fh->sockhost()';
447 inet_ntoa($fh->sockaddr);
451 @_ == 1 or croak 'usage: $fh->peeraddr()';
453 (sockaddr_in($fh->peername))[1];
457 @_ == 1 or croak 'usage: $fh->peerport()';
459 (sockaddr_in($fh->peername))[0];
463 @_ == 1 or croak 'usage: $fh->peerhost()';
465 inet_ntoa($fh->peeraddr);
472 package IO::Socket::UNIX;
475 use vars qw(@ISA $VERSION);
480 @ISA = qw(IO::Socket);
482 =head2 IO::Socket::UNIX
484 C<IO::Socket::UNIX> provides a constructor to create an AF_UNIX domain socket
485 and some related methods. The constructor can take the following options
487 Type Type of socket (eg SOCK_STREAM or SOCK_DGRAM)
488 Local Path to local fifo
489 Peer Path to peer fifo
490 Listen Create a listen socket
496 Returns the pathname to the fifo at the local end
500 Returns the pathanme to the fifo at the peer end
508 my $type = $arg->{Type} || SOCK_STREAM;
510 $fh->socket(AF_UNIX, $type, 0) or
513 if(exists $arg->{Local}) {
514 my $addr = sockaddr_un($arg->{Local});
518 if(exists $arg->{Listen}) {
519 $fh->listen($arg->{Listen} || 5) or
522 elsif(exists $arg->{Peer}) {
523 my $addr = sockaddr_un($arg->{Peer});
524 $fh->connect($addr) or
532 @_ == 1 or croak 'usage: $fh->hostpath()';
533 (sockaddr_un($_[0]->hostname))[0];
537 @_ == 1 or croak 'usage: $fh->peerpath()';
538 (sockaddr_un($_[0]->peername))[0];
543 Graham Barr <Graham.Barr@tiuk.ti.com>
549 The VERSION is derived from the revision turning each number after the
550 first dot into a 2 digit number so
552 Revision 1.8 => VERSION 1.08
553 Revision 1.2.3 => VERSION 1.0203
557 Copyright (c) 1995 Graham Barr. All rights reserved. This program is free
558 software; you can redistribute it and/or modify it under the same terms
563 1; # Keep require happy