[p5sagit/p5-mst-13.2.git] / lib / Net / Ping.pm

package Net::Ping;

# Authors: karrer@bernina.ethz.ch (Andreas Karrer)
#          pmarquess@bfsec.bt.co.uk (Paul Marquess)

require Exporter;

@ISA = qw(Exporter);
@EXPORT = qw(ping pingecho);
$VERSION = 1.00;

use Socket 'PF_INET', 'AF_INET', 'SOCK_STREAM';
require Carp ;

use strict ;

$Net::Ping::tcp_proto = (getprotobyname('tcp'))[2];
$Net::Ping::echo_port = (getservbyname('echo', 'tcp'))[2];

# keep -w happy
$Net::Ping::tcp_proto = $Net::Ping::tcp_proto ;
$Net::Ping::echo_port = $Net::Ping::echo_port ;

sub ping {
    Carp::croak "ping not implemented yet. Use pingecho()";
}


sub pingecho {

    Carp::croak "usage: pingecho host [timeout]" 
        unless @_ == 1 || @_ == 2 ;

    my ($host, $timeout) = @_;
    my ($saddr, $ip);
    my ($ret) ;
    local (*PINGSOCK);

    # check if $host is alive by connecting to its echo port, within $timeout
    # (default 5) seconds. returns 1 if OK, 0 if no answer, 0 if host not found

    $timeout = 5 unless $timeout;

    if ($host =~ /^\s*((\d+\.){3}\d+)\s*$/)
      { $ip = pack ('C4', split (/\./, $1)) }
    else
      { $ip = (gethostbyname($host))[4] }

    return 0 unless $ip;		# "no such host"

    $saddr = pack('S n a4 x8', AF_INET, $Net::Ping::echo_port, $ip);
    $SIG{'ALRM'} = sub { die } ;
    alarm($timeout);
    
    $ret = 0;
    eval <<'EOM' ;
    return unless socket(PINGSOCK, PF_INET, SOCK_STREAM, $Net::Ping::tcp_proto) ;
    return unless connect(PINGSOCK, $saddr) ;
    $ret=1 ;
EOM
    alarm(0);
    close(PINGSOCK);
    $ret;
}   

1;
__END__

=cut

=head1 NAME

Net::Ping, pingecho - check a host for upness

=head1 SYNOPSIS

    use Net::Ping;
    print "'jimmy' is alive and kicking\n" if pingecho('jimmy', 10) ;

=head1 DESCRIPTION

This module contains routines to test for the reachability of remote hosts.
Currently the only routine implemented is pingecho(). 

pingecho() uses a TCP echo (I<not> an ICMP one) to determine if the
remote host is reachable. This is usually adequate to tell that a remote
host is available to rsh(1), ftp(1), or telnet(1) onto.

=head2 Parameters

=over 5

=item hostname

The remote host to check, specified either as a hostname or as an IP address.

=item timeout

The timeout in seconds. If not specified it will default to 5 seconds.

=back

=head1 WARNING

pingecho() uses alarm to implement the timeout, so don't set another alarm
while you are using it.
Commit	Line	Data
a0d0e21e	1	package Net::Ping;
	2
	3	# Authors: karrer@bernina.ethz.ch (Andreas Karrer)
	4	# pmarquess@bfsec.bt.co.uk (Paul Marquess)
	5
	6	require Exporter;
	7
	8	@ISA = qw(Exporter);
	9	@EXPORT = qw(ping pingecho);
8e07c86e	10	$VERSION = 1.00;
a0d0e21e	11
8e07c86e	12	use Socket 'PF_INET', 'AF_INET', 'SOCK_STREAM';
8e07c86e	13	require Carp ;
a0d0e21e	14
8e07c86e	15	use strict ;
	16
	17	$Net::Ping::tcp_proto = (getprotobyname('tcp'))[2];
	18	$Net::Ping::echo_port = (getservbyname('echo', 'tcp'))[2];
	19
	20	# keep -w happy
	21	$Net::Ping::tcp_proto = $Net::Ping::tcp_proto ;
	22	$Net::Ping::echo_port = $Net::Ping::echo_port ;
a0d0e21e	23
a0d0e21e	24	sub ping {
8e07c86e	25	Carp::croak "ping not implemented yet. Use pingecho()";
a0d0e21e	26	}
	27
	28
	29	sub pingecho {
	30
8e07c86e	31	Carp::croak "usage: pingecho host [timeout]"
a0d0e21e	32	unless @_ == 1 \|\| @_ == 2 ;
a0d0e21e	33
8e07c86e	34	my ($host, $timeout) = @_;
	35	my ($saddr, $ip);
	36	my ($ret) ;
a0d0e21e	37	local (*PINGSOCK);
a0d0e21e	38
	39	# check if $host is alive by connecting to its echo port, within $timeout
	40	# (default 5) seconds. returns 1 if OK, 0 if no answer, 0 if host not found
	41
	42	$timeout = 5 unless $timeout;
	43
	44	if ($host =~ /^\s((\d+\.){3}\d+)\s$/)
	45	{ $ip = pack ('C4', split (/\./, $1)) }
	46	else
	47	{ $ip = (gethostbyname($host))[4] }
	48
	49	return 0 unless $ip; # "no such host"
	50
8e07c86e	51	$saddr = pack('S n a4 x8', AF_INET, $Net::Ping::echo_port, $ip);
a0d0e21e	52	$SIG{'ALRM'} = sub { die } ;
a0d0e21e	53	alarm($timeout);
8e07c86e	54
	55	$ret = 0;
	56	eval <<'EOM' ;
	57	return unless socket(PINGSOCK, PF_INET, SOCK_STREAM, $Net::Ping::tcp_proto) ;
	58	return unless connect(PINGSOCK, $saddr) ;
	59	$ret=1 ;
a0d0e21e	60	EOM
a0d0e21e	61	alarm(0);
a0d0e21e	62	close(PINGSOCK);
8e07c86e	63	$ret;
a0d0e21e	64	}
	65
	66	1;
8e07c86e	67	__END__
	68
	69	=cut
	70
	71	=head1 NAME
	72
	73	Net::Ping, pingecho - check a host for upness
	74
	75	=head1 SYNOPSIS
	76
	77	use Net::Ping;
	78	print "'jimmy' is alive and kicking\n" if pingecho('jimmy', 10) ;
	79
	80	=head1 DESCRIPTION
	81
	82	This module contains routines to test for the reachability of remote hosts.
	83	Currently the only routine implemented is pingecho().
	84
	85	pingecho() uses a TCP echo (I<not> an ICMP one) to determine if the
	86	remote host is reachable. This is usually adequate to tell that a remote
	87	host is available to rsh(1), ftp(1), or telnet(1) onto.
	88
	89	=head2 Parameters
	90
	91	=over 5
	92
	93	=item hostname
	94
	95	The remote host to check, specified either as a hostname or as an IP address.
	96
	97	=item timeout
	98
	99	The timeout in seconds. If not specified it will default to 5 seconds.
	100
	101	=back
	102
	103	=head1 WARNING
	104
	105	pingecho() uses alarm to implement the timeout, so don't set another alarm
	106	while you are using it.
	107
	108