.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "External 3pm" .TH External 3pm "2008-12-18" "perl v5.10.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::Ping::External \- Cross\-platform interface to ICMP "ping" utilities .SH "SYNOPSIS" .IX Header "SYNOPSIS" In general: .PP .Vb 2 \& use Net::Ping::External qw(ping); \& ping(%options); .Ve .PP Some examples: .PP .Vb 1 \& use Net::Ping::External qw(ping); \& \& # Ping a single host \& my $alive = ping(host => "127.0.0.1"); \& print "127.0.0.1 is online" if $alive; \& \& # Or a list of hosts \& my @hosts = qw(127.0.0.1 127.0.0.2 127.0.0.3 127.0.0.4); \& my $num_alive = 0; \& foreach (@hosts) { \& $alive = ping(hostname => $_, timeout => 5); \& print "$_ is alive!\en" if $alive; \& $num_alive++; \& } \& print "$num_alive hosts are alive.\en"; \& \& # Using all the fancy options: \& ping(hostname => "127.0.0.1", count => 5, size => 1024, timeout => 3); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Net::Ping::External is a module which interfaces with the \*(L"ping\*(R" command on many systems. It presently provides a single function, \f(CW\*(C`ping()\*(C'\fR, that takes in a hostname and (optionally) a timeout and returns true if the host is alive, and false otherwise. Unless you have the ability (and willingness) to run your scripts as the superuser on your system, this module will probably provide more accurate results than Net::Ping will. .PP Why? .IP "\(bu" 4 \&\s-1ICMP\s0 ping is the most reliable way to tell whether a remote host is alive. .IP "\(bu" 4 However, Net::Ping cannot use an \s-1ICMP\s0 ping unless you are running your script with privileged (\s-1AKA\s0 \*(L"root\*(R") access. .IP "\(bu" 4 The system's \*(L"ping\*(R" command uses \s-1ICMP\s0 and does not usually require privileged access. .IP "\(bu" 4 While it is relatively trivial to write a Perl script that parses the output of the \*(L"ping\*(R" command on a given system, the aim of this module is to encapsulate this functionality and provide a single interface for it that works on many systems. .SS "\fIping()\fP \s-1OPTIONS\s0" .IX Subsection "ping() OPTIONS" This module is still \*(L"alpha\*(R"; it is expected that more options to the \f(CW\*(C`ping()\*(C'\fR function will be added soon. .IP "\(bu" 4 \&\f(CW\*(C`host, hostname\*(C'\fR .Sp The hostname (or dotted-quad \s-1IP\s0 address) of the remote host you are trying to ping. You must specify either the \*(L"hostname\*(R" option or the \*(L"ip\*(R" option. .Sp \&\*(L"host\*(R" and \*(L"hostname\*(R" are synonymous. .IP "\(bu" 4 \&\f(CW\*(C`ip\*(C'\fR .Sp A packed bit-string representing the 4\-byte packed \s-1IP\s0 address (as returned by \f(CW\*(C`Socket.pm\*(C'\fR's \f(CW\*(C`inet_aton()\*(C'\fR function) of the host that you would like to ping. .IP "\(bu" 4 \&\f(CW\*(C`timeout\*(C'\fR .Sp The maximum amount of time, in seconds, that \f(CW\*(C`ping()\*(C'\fR will wait for a response. If the remote system does not respond before the timeout has elapsed, \f(CW\*(C`ping()\*(C'\fR will return false. .Sp Default value: 5. .IP "\(bu" 4 \&\f(CW\*(C`count\*(C'\fR .Sp The number of \s-1ICMP\s0 ping packets to send to the remote host. Eventually, Net::Ping::External will return the number of packets that were acknowledged by the remote host; for now, however, \f(CW\*(C`ping()\*(C'\fR still returns just true or false. .Sp Default value: 1. .IP "\(bu" 4 \&\f(CW\*(C`size\*(C'\fR .Sp Specifies the number of data bytes to be sent. The default is 56, which translates into 64 \s-1ICMP\s0 data bytes when combined with the 8 bytes of \s-1ICMP\s0 header data. .Sp Default value: 56. .SS "\s-1SUPPORTED\s0 \s-1PLATFORMS\s0" .IX Subsection "SUPPORTED PLATFORMS" Support currently exists for interfacing with the standard ping utilities on the following systems. Please note that the path to the `ping' should be somewhere in your \s-1PATH\s0 environment variable (or your system's closest equivalent thereof.) Otherwise, Net::Ping::External will be unable to locate your system's `ping' command. .IP "\(bu" 4 Win32 .Sp Tested \s-1OK\s0 on Win98, Win \s-1XP\s0. It should work on other Windows systems as well. .IP "\(bu" 4 Cygwin .Sp Tested \s-1OK\s0 on Cygwin 1.5.21. Problem is that we may be running windows ping. They have different options. .IP "\(bu" 4 Linux .Sp Tested \s-1OK\s0 on Debian 2.2 and Redhat 6.2. It appears that different versions of Linux use different versions of ping, which support different options. Not sure how I'm going to resolve this yet; for now, all the options but \&\f(CW\*(C`count\*(C'\fR are disabled. .IP "\(bu" 4 \&\s-1BSD\s0 .Sp Tested \s-1OK\s0 on OpenBSD 2.7 and 3.0, Netbsd 1.5.3, Freebsd 4.6.2, 5.4. Needs testing for BSDi. .IP "\(bu" 4 Solaris .Sp Tested \s-1OK\s0 on Solaris 2.6 and 2.7. .IP "\(bu" 4 \&\s-1IRIX\s0 .Sp Tested \s-1OK\s0 on \s-1IRIX\s0 6.5. .IP "\(bu" 4 \&\s-1AIX\s0, \s-1DEC\s0 \s-1OSF\s0, \s-1UNICOSMK\s0, NeXTStep, HP-UX, \s-1BSD/OS\s0 (BSDi), BeOS .Sp Support for these systems is integrated into this module but none have been tested yet. If you have successful or unsuccessful test results for any of these systems, please send them to me. On some of these systems, some of the arguments may not be supported. If you'd like to see better support on your system, please e\-mail me. .PP More systems will be added as soon as any users request them. If your system is not currently supported, e\-mail me; adding support to your system is probably trivial. .SH "BUGS" .IX Header "BUGS" This module should be considered beta. Bugs may exist. Although no specific bugs are known at this time, the module could use testing on a greater variety of systems. .PP See the warning below. .SH "WARNING" .IX Header "WARNING" This module calls whatever \*(L"ping\*(R" program it first finds in your \s-1PATH\s0 environment variable. If your \s-1PATH\s0 contains a trojan \*(L"ping\*(R" program, this module will call that program. This involves a small amount of risk, but no more than simply typing \*(L"ping\*(R" at a system prompt. .PP Beware Greeks bearing gifts. .SH "AUTHOR" .IX Header "AUTHOR" Alexandr Ciornii (alexchorny \s-1AT\s0 gmail.com), Colin McMillen (colinm \s-1AT\s0 cpan.org) .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "CREDITS" .IX Header "CREDITS" Dan Moore contributed command-line options and code for NeXT, BeOS, HP-UX, and \s-1BSD/OS\s0. .PP Jarkko Hietaniemi contributed a huge list of command-line options and results for the `ping' command on 9 different systems. .PP Randy Moore contributed several patches for Win32 support. .PP Marc-Andre Dumas contributed a patch for FreeBSD support. .PP Jonathan Stowe fixed a bug in 0.09 that prevented the module from running on some systems. .PP Numerous people sent in a patch to fix a bug in 0.10 that broke ping on Windows systems. .PP Peter N. Lewis contributed a patch that works correctly on Mac \s-1OS\s0 X 10.2 (and hopefully other versions as well). .SH "SEE ALSO" .IX Header "SEE ALSO" Net::Ping