oping, noping: Implement percentile reporting.

[liboping.git] / src / mans / oping.pod

diff --git a/src/mans/oping.pod b/src/mans/oping.pod
index f0af718dc92bd47adc672bd1a5e38d411ae22b7f..19d45042f6d237c451fb4649b6d75bce60bd6368 100644 (file)
--- a/src/mans/oping.pod
+++ b/src/mans/oping.pod
@@ -166,6 +166,31 @@ I<Explicit Congestion Notification> (ECN), even if the deprecated
 I<Type of Service> (ToS) aliases were used to specify the bits of outgoing
 packets.
 
+=item B<-u>|B<-U>
+
+I<noping only> B<-u> forces UTF-8 output, B<-U> disables UTF-8 output. If
+neither is given, the codeset is automatically determined from the locale.
+
+=item B<-P> I<percent>
+
+Configures the latency percentile to report. I<percent> must be a number
+between zero and 100, exclusively in both cases. In general, defaults to B<95>.
+If B<-c> is given and a number less than 20, this would be the same as the
+maximum. In this case the default is chosen so that it excludes the maximum,
+e.g. if B<-cE<nbsp>5> is given, the default is I<80>.
+
+The calculated percentile has roughly millisecond precision. If precision is of
+importance, read on for a more detailed explanation. In order to calculate the
+percentile without keeping all replies in memory, I<oping> divides the
+I<interval> (the B<-i> option) in 1000 "buckets". Each bucket counts the number
+of packets received in the represented time. That means that the precision
+decreases if the interval is increased, because each bucket represents a larger
+(fraction of the) response time. The code looks for the first bucket
+representing at least I<percent> responses and returns the upper-bound latency
+represented by that bucket. Since the represented percentage may be larger than
+the configured percentile, this algorithm I<overestimes> the actual percentile
+by at most 1000th of I<interval>.
+
 =item B<-Z> I<percent>
 
 If any hosts have a drop rate higher than I<percent>, where I<percent> is a
@@ -175,6 +200,9 @@ limit will effectively disable the feature (the default). Setting the option to
 zero means that the exit status will only be zero if I<all> replies for I<all>
 hosts have been received.
 
+The exit status will indicate the number of hosts with more than I<percent>
+packets lost, up to a number of 255 failing hosts.
+
 =back
 
 =head1 COLORS