Net::Ping

(原始碼, CPAN)

版本 2.76

內容

名稱
語法
說明
- 函式
備註
安裝
錯誤
作者
版權

#名稱

Net::Ping - 檢查遠端主機的可連線性

#語法

use Net::Ping;

my $p = Net::Ping->new();
print "$host is alive.\n" if $p->ping($host);
$p->close();

my $p = Net::Ping->new("icmp");
$p->bind($my_addr); # Specify source interface of pings
foreach my $host (@host_array)
{
    print "$host is ";
    print "NOT " unless $p->ping($host, 2);
    print "reachable.\n";
    sleep(1);
}
$p->close();

my $p = Net::Ping->new("icmpv6");
my $ip = "[fd00:dead:beef::4e]";
print "$ip is alive.\n" if $p->ping($ip);

my $p = Net::Ping->new("tcp", 2);
# Try connecting to the www port instead of the echo port
$p->port_number(scalar(getservbyname("http", "tcp")));
while ($stop_time > time())
{
    print "$host not reachable ", scalar(localtime()), "\n"
        unless $p->ping($host);
    sleep(300);
}
undef($p);

# Like tcp protocol, but with many hosts
my $p = Net::Ping->new("syn");
$p->port_number(getservbyname("http", "tcp"));
foreach my $host (@host_array) {
  $p->ping($host);
}
while (my ($host, $rtt, $ip) = $p->ack) {
  print "HOST: $host [$ip] ACKed in $rtt seconds.\n";
}

# High precision syntax (requires Time::HiRes)
my $p = Net::Ping->new();
$p->hires();
my ($ret, $duration, $ip) = $p->ping($host, 5.5);
printf("$host [ip: $ip] is alive (packet return time: %.2f ms)\n",
        1000 * $duration)
  if $ret;
$p->close();

# For backward compatibility
print "$host is alive.\n" if pingecho($host);

#說明

此模組包含用於測試網路中遠端主機可連線性的方法。首先使用選用參數建立 ping 物件，可以對多個主機進行多次 ping，然後關閉連線。

你可以選擇六種不同的通訊協定來執行 ping。預設的通訊協定為「tcp」。請注意，即使遠端主機是連線狀態，仍可能無法使用其中一種或多種通訊協定進行 ping。例如，www.microsoft.com 通常是連線狀態，但無法使用「icmp」進行 ping。

使用「tcp」通訊協定時，ping() 方法會嘗試建立與遠端主機的回音埠連線。如果成功建立連線，則遠端主機視為可連線。實際上並未回傳任何資料。此通訊協定不需要任何特殊權限，但其負擔比「udp」和「icmp」通訊協定來得高。

指定「udp」通訊協定會導致 ping() 方法傳送 udp 封包至遠端主機的回音埠。如果從遠端主機收到回音封包，且接收到的封包包含與傳送封包相同的資料，則遠端主機即被視為可連線。此通訊協定不需要任何特殊權限。請注意，對於 udp ping，如果主機未執行適當的回音服務，則會回報該主機無法連線。對於類 Unix 系統，請參閱 inetd(8) 以取得更多資訊。

如果指定「icmp」通訊協定，ping() 方法會傳送 icmp 回音訊息至遠端主機，這正是 UNIX ping 程式所執行的動作。如果從遠端主機收到回音訊息，且回音資訊正確，則遠端主機即被視為可連線。指定「icmp」通訊協定需要以 root 身分執行程式，或將程式設定為 root 的 setuid。

如果指定「external」通訊協定，ping() 方法會嘗試使用 Net::Ping::External 模組來 ping 遠端主機。Net::Ping::External 會與系統預設的 ping 程式介接，以執行 ping，通常會產生相對精確的結果。如果系統未安裝 Net::Ping::External，指定「external」通訊協定將導致錯誤。

如果指定「syn」通訊協定，"ping" 方法只會傳送 TCP SYN 封包至遠端主機，然後立即傳回。如果成功傳送 syn 封包，將傳回 true 值，否則會傳回 false。注意：與其他通訊協定不同，傳回值並不會判斷遠端主機是否存活，因為完整的 TCP 三向交握可能尚未完成。只有在遠端主機於指定逾時時間內收到 TCP ACK 時，才被視為可連線。若要開始等待 ACK 封包，請使用 "ack" 方法，說明如下。使用「syn」通訊協定而非「tcp」通訊協定，可透過同時傳送平行 TCP SYN 封包，來判斷多個目的地是否可連線。在測試每個遠端主機時，它不會造成阻礙。此通訊協定不需要任何特殊權限。

#函數

#Net::Ping->new([proto, timeout, bytes, device, tos, ttl, family, host, port, bind, gateway, retrans, pingstring, source_verify econnrefused dontfrag IPV6_USE_MIN_MTU IPV6_RECVPATHMTU])

建立一個新的 ping 物件。所有參數都是選用的，而且可以傳遞為雜湊參照。除了前 7 個選項之外，所有選項都必須傳遞為雜湊參照。

proto 指定執行 ping 時要使用的通訊協定。目前的選擇包括「tcp」、「udp」、「icmp」、「icmpv6」、「stream」、「syn」或「external」。預設值為「tcp」。

如果提供以秒為單位的 timeout，則會在未將逾時傳遞給 ping() 方法（如下）時使用該逾時。逾時必須大於 0，而且如果未指定，預設值為 5 秒。

如果提供資料位元組數目（bytes），則會在傳送至遠端主機的 ping 封包中包含那麼多個資料位元組。如果通訊協定為「tcp」，則會忽略資料位元組數目。如果通訊協定為「udp」，則資料位元組的最小（而且預設）數目為 1，否則為 0。可以指定的最大資料位元組數目為 65535，但建議維持在 MTU（ICMP 為 1472 位元組）以下。許多小型裝置無法處理片段化的 ICMP 封包。

如果提供 device，則會在傳送 ping 封包之前使用此裝置繫結來源端點。我相信這目前僅適用於超級使用者權限以及 udp 和 icmp 通訊協定。

如果提供 <tos>，則會將此 ToS 組態至 socket 中。

對於 icmp，可以指定 ttl 以設定傳出封包的 TTL。

IPv4 的有效 family 值

4, v4, ip4, ipv4, AF_INET (constant)

IPv6 的有效 family 值

6, v6, ip6, ipv6, AF_INET6 (constant)

如果未提供 family 參數，host 參數將隱式指定 family。

port 參數僅對 udp、tcp 或串流 ping 有效，且不會執行您認為它會執行的動作。當我們收到「連線拒絕」時，ping 會傳回 true！預設值為回音埠。

bind 參數指定要繫結的 local_addr。透過指定 bind 參數，您不需要 bind 方法。

gateway 參數僅對 IPv6 有效，且需要 IPv6 位址。

retrans 參數為指數遞減率，預設值為 1.2。它與 $def_factor 全域變數相符。

dontfrag 參數設定 IP_DONTFRAG 位元，但請注意，Socket 尚未定義 IP_DONTFRAG，且在許多系統上不可用。然後它會被忽略。在 linux 上，它也會將 IP_MTU_DISCOVER 設定為 IP_PMTUDISC_DO，但我們不需要分段傳送過大封包。您需要手動設定 $data_size。

#$p->ping($host [, $timeout [, $family]]);

對遠端主機執行 ping 並等待回應。$host 可以是遠端主機的主機名稱或 IP 號碼。選擇性逾時時間必須大於 0 秒，且預設值為在建立 ping 物件時指定的逾時時間。傳回成功旗標。如果找不到主機名稱或 IP 號碼有問題，傳回的成功旗標將為 undef。否則，如果主機可連線，成功旗標將為 1；如果不可連線，則為 0。在大部分實際用途上，undef 和 0 可以視為相同情況。在陣列內容中，也會傳回經過時間以及主機解析到的 IP 字串形式。如果先前已呼叫 hires()，經過時間值將是 Time::HiRes::time() 函數傳回的浮點數；否則，它會以整數傳回。

#$p->source_verify( { 0 | 1 } );

允許啟用或停用來源端點驗證。這對於具有多個介面的遠端目的地很有用，其中回應可能不會來自與原始目的地端點相同的端點。這只會影響 udp 和 icmp 協定的 ping。

這在預設情況下已啟用。

#$p->service_check( { 0 | 1 } );

設定是否連線行為應強制執行遠端服務可用性以及可達性。通常，如果遠端伺服器回報 ECONNREFUSED，它一定是可達的，因為它回報的狀態封包。啟用此選項後，必須成功建立完整的 TCP 三向交握，才能宣稱它可達。注意：它仍然只會連線和斷線。它不會使用任何協定（例如 HTTP 或 FTP）來確保遠端伺服器在任何方面都是正常的。遠端伺服器 CPU 可能會停止運作，對任何連線的用戶端沒有回應，但如果核心拋出 ACK 封包，它仍被視為存活的。要真正確定伺服器是否正常回應將取決於應用程式，這超出了 Net::Ping 的範圍。對於 udp 協定，啟用此選項要求遠端伺服器使用 udp 回應服務定義的相同 udp 資料。

這會影響「udp」、「tcp」和「syn」協定。

這在預設情況下已停用。

#$p->tcp_service_check( { 0 | 1 } );

已棄用的方法，但與 service_check() 方法相同。

#$p->hires( { 0 | 1 } );

使用 1 個原因讓此模組使用 Time::HiRes 模組，允許後續呼叫 ping() 回傳毫秒。

#$p->time

目前時間，是否為高解析度。

#$p->socket_blocking_mode( $fh, $mode );

設定或清除檔案處理中的 O_NONBLOCK 旗標。

#$p->IPV6_USE_MIN_MTU

使用參數設定選項。不使用則傳回選項值。

#$p->IPV6_RECVPATHMTU

通知相應的 IPv6 MTU。

使用參數設定選項。不使用則傳回選項值。

#$p->IPV6_HOPLIMIT

使用參數設定選項。不使用則傳回選項值。

#$p->IPV6_REACHCONF NYI

設定 ipv6 可達性 IPV6_REACHCONF 已在 RFC3542 中移除。ping6 -R 支援它。IPV6_REACHCONF 需要 root/admin 權限。

使用參數設定選項。不使用則傳回選項值。

尚未實作。

#$p->bind($local_addr);

設定發送 ping 的來源位址。這必須是本機主機上其中一個介面的位址。$local_addr 可以指定為網域名稱或文字 IP 位址，例如「192.168.1.1」。

如果通訊協定設定為「tcp」，則可以多次呼叫此方法，而每次呼叫 ping() 方法（如下）都將使用最新的 $local_addr。如果通訊協定為「icmp」或「udp」，則每個物件最多只能呼叫 bind() 一次，而且（如果呼叫的話）必須在呼叫該物件的 ping() 之前呼叫。

在對 new() 指定 bind 選項時，可以省略 bind() 呼叫。

#$p->message_type([$ping_type]);

使用「icmp」通訊協定時，此呼叫允許將訊息類型變更為「echo」或「timestamp」（僅適用於 IPv4，請參閱 RFC 792）。

不使用參數時，它會傳回目前使用的 icmp 通訊協定訊息類型。預設傳回「echo」。

#$p->open($host);

當您使用「串流」協定時，此呼叫會預先開啟 tcp socket。只有當您想要在建立連線時提供不同的逾時，或從第一次 ping 中移除建立連線的負擔時，才需要執行此操作。如果您沒有呼叫 open()，則會在第一次呼叫 ping() 時自動開啟連線。如果您使用的是串流以外的任何協定，此呼叫只會執行無動作。

在 new() 中指定 host 選項時，可以省略 $host 引數。

#$p->ack( [ $host ] );

在使用「syn」協定時，請使用此方法來判斷遠端主機的可及性。此方法的用意是呼叫次數最多可達呼叫 ping() 的次數。每次呼叫都會傳回透過 TCP ACK 回應的主機（如傳遞給 ping() 的主機）。主機傳回的順序不一定與使用 ping() 方法將其排入 SYN 佇列的順序相同。如果在收到 TCP ACK 之前逾時，或如果遠端主機未在嘗試連接的埠上監聽，則不會建立 TCP 連線，且 ack() 會傳回 undef。在清單內容中，會傳回主機、確認時間、點分 IP 字串和埠號，而不會只傳回主機。如果指定了選用的 $host 引數，傳回值將只與該主機相關。如果您使用的是「syn」以外的任何協定，此呼叫只會執行無動作。

當 "new" 有 host 選項時，將使用此主機。如果沒有 $host 引數，則會掃描所有主機。

#$p->nack( $failed_ack_host );

主機 $failed_ack_host 未收到有效 ACK 的原因。當 ack($fail_ack_host) 傳回 false 值時，此方法有助於找出原因。

#$p->ack_unfork($host)

由 "ack" 呼叫的變體，啟用「syn」通訊協定和 $syn_forking。

#$p->ping_icmp([$host, $timeout, $family])

使用 icmp 通訊協定的 "ping" 方法。

#$p->ping_icmpv6([$host, $timeout, $family])

使用 icmpv6 通訊協定的 "ping" 方法。

#$p->ping_stream([$host, $timeout, $family])

使用 stream 通訊協定的 "ping" 方法。

執行 stream ping。如果 tcp 連線尚未開啟，則會開啟。然後會傳送一些資料並等待回覆。它會在結束時保持 stream 開啟。

#$p->ping_syn([$host, $ip, $start_time, $stop_time])

使用 syn 通訊協定的 "ping" 方法。傳送 TCP SYN 封包至指定的 host。

#$p->ping_syn_fork([$host, $timeout, $family])

使用 forking syn 通訊協定的 "ping" 方法。

#$p->ping_tcp([$host, $timeout, $family])

使用 tcp 通訊協定的 "ping" 方法。

#$p->ping_udp([$host, $timeout, $family])

使用 udp 通訊協定的 "ping" 方法。

執行 udp 回應 ping。建構一個訊息，至少包含一個位元組的順序號碼和任何其他資料位元組。傳送訊息並等待訊息傳回。如果我們收到訊息，請確保其所有部分都相符。如果相符，我們就完成了。否則，返回並等待訊息，直到時間用完。傳回我們努力的結果。

#$p->ping_external([$host, $timeout, $family])

與外部通訊協定一起使用的 "ping" 方法。使用 Net::Ping::External 執行外部 ping。

#$p->tcp_connect([$ip, $timeout])

啟動 TCP 連線，用於 tcp ping。

#$p->tcp_echo([$ip, $timeout, $pingstring])

執行 TCP 回應。它將給定的字串寫入 socket，然後再讀回。成功時傳回 1，失敗時傳回 0。

#$p->close();

關閉此 ping 物件的網路連線。網路連線也會因「undef $p」而關閉。如果 ping 物件超出範圍（例如 $p 是子常式的區域變數，而你離開了子常式），網路連線會自動關閉。

#$p->port_number([$port_number])

當呼叫時附帶埠號，用於 ping 的埠號會設定為 $port_number，而不是使用回應埠。它也會呼叫 $p->service_check(1)，導致只有在特定埠可存取時，ping 才會傳回成功的回應。此函式傳回 "ping" 將連線的埠值。

#$p->mselect

一個補償平台特殊性的 select() 包裝器。

#$p->ntop

inet_ntop() 的平台抽象

#$p->checksum($msg)

對訊息進行檢查和。基本上將所有短字詞相加，並將高階位元摺疊到低階位元中。

#$p->icmp_result

傳回 addr、類型和次代碼的清單。

#pingecho($host [, $timeout]);

為了提供與先前版本的 Net::Ping 的向後相容性，提供一個具有與先前相同功能的 pingecho() 子程式。pingecho() 使用 tcp 協定。傳回值和參數與 "ping" 方法所述相同。此子程式已過時，可能會在未來的 Net::Ping 版本中移除。

#wakeonlan($mac, [$host, [$port]])

發出廣受歡迎的喚醒區域網路魔法 udp 封包，以喚醒本機裝置。另請參閱 Net::Wake，但此處將 mac 位址設為第一個引數。$host 應該是本機閘道。如果不設定，將廣播。

預設主機：'255.255.255.255' 預設埠：9

perl -MNet::Ping=wakeonlan -e'wakeonlan "e0:69:95:35:68:d2"'

#備註

如果您指定 udp 或 icmp 協定，將會減少網路負載（以及程式中的一些效率）。tcp 協定會為每個 ping 產生 2.5 倍以上的流量，高於 udp 或 icmp。如果頻繁 ping 許多主機，您可能希望在每次 ping 之間實作一小段等待時間（例如 25 毫秒或更長），以避免封包淹沒您的網路。

icmp 和 icmpv6 協定要求程式以 root 身分執行，或設定為 root 的 setuid。其他協定不需要特殊權限，但並非所有網路裝置都實作 tcp 或 udp 回音。

本機主機通常會在幾毫秒內回應 ping。但是，在非常壅塞的網路中，可能需要長達 3 秒或更長的時間才能從遠端主機收到回音封包。如果在這些條件下將逾時設定得太低，看起來遠端主機無法連線（這幾乎是事實）。

可達性並不一定表示遠端主機實際上運作超出其回送封包的能力。與 icmp 相比，tcp 稍微能更佳地指出系統的健康狀況，因為它使用更多網路堆疊來回應。

由於缺乏更好的方法，此模組使用其自己的例程來封裝和解封 ICMP 封包。最好撰寫一個獨立的模組，了解所有不同類型的 ICMP 封包。

#安裝

最新的原始碼樹可透過 git 取得

git clone https://github.com/rurban/Net-Ping.git
cd Net-Ping

tarball 可依下列方式建立

perl Makefile.PL ; make ; make dist

最新的 Net::Ping 發行版包含在 cperl 和 perl5 中。

#錯誤

如需已知問題清單，請瀏覽

https://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Ping 和 https://github.com/rurban/Net-Ping/issues

如需回報新的錯誤，請瀏覽

https://github.com/rurban/Net-Ping/issues

#作者

Current maintainers:
  perl11 (for cperl, with IPv6 support and more)
  p5p    (for perl5)

Previous maintainers:
  bbb@cpan.org (Rob Brown)
  Steve Peters

External protocol:
  colinm@cpan.org (Colin McMillen)

Stream protocol:
  bronson@trestle.com (Scott Bronson)

Wake-on-lan:
  1999-2003 Clinton Wong

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

Original Net::Ping author:
  mose@ns.ccsn.edu (Russell Mosemann)

#版權

本程式為自由軟體；您可以在與 Perl 相同的條款下重新散布或修改它。