src/oping.c: Implement the "-O" option.

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

diff --git a/src/mans/oping.pod b/src/mans/oping.pod
index a2307fe..425bdca 100644 (file)
--- a/src/mans/oping.pod
+++ b/src/mans/oping.pod
@@ -31,7 +31,7 @@ supports colors.
 
 =item B<-4>
 
-Force the use of IPv4. 
+Force the use of IPv4.
 
 =item B<-6>
 
@@ -46,6 +46,12 @@ Send (and receive) I<count> ICMP packets, then stop and exit.
 Send one ICMP packet (per host) each I<interval> seconds. This can be a
 floating-point number to specify sub-second precision.
 
+=item B<-w> I<timeout>
+
+Specifies the time to wait for an C<ECHO REPLY> packet before giving up, in
+seconds. This can be a floating point number for sub-second precision. Defaults
+to B<1.0> seconds.
+
 =item B<-t> I<ttl>
 
 Set the IP Time to Live to I<ttl>. This must be a number between (and
@@ -79,6 +85,12 @@ real user ID (as returned by L<getuid(2)>) and the effective user ID (as
 returned by L<geteuid(2)>) differ, the only argument allowed for this option is
 "-" (i.e. standard input).
 
+=item B<-O> I<filename>
+
+Write measurements in I<Comma Separated Values> (CSV) format to I<filename>.
+This option writes three columns per row: wall clock time in (fractional)
+seconds since epoch, hostname and the round trip time in milliseconds.
+
 =item B<-Q> I<qos>
 
 Specify the I<Quality of Service> (QoS) for outgoing packets. This is a
@@ -166,6 +178,12 @@ 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<-m> I<mark>
+
+I<Linux only> Sets the I<mark> (an integer number) on outgoing packets. This
+can be used by L<iptables(8)> and other networking infrastructure for filtering
+and routing.
+
 =item B<-u>|B<-U>
 
 I<noping only> B<-u> forces UTF-8 output, B<-U> disables UTF-8 output. If
@@ -183,9 +201,15 @@ Do not show a graph.
 
 =item B<prettyping>
 
-Show a graph with time on the x-axis in a round-robin fashion, i.e. continue on
-the left if the right edge is reached. The y-axis shows the round-trip time.
-This is the default.
+Show a graph with time on the x-axis, the y-axis shows the round-trip time.
+This is the default graph.
+
+If your terminal supports unicode and colors, they are used to improve
+the precision of the data shown: a green box is drawn for round-trip times up
+to one third of the configured timeout, the height representing the RTT. Longer
+RTTs will start to fill the box yellow (with a green background) and then red
+(with a yellow background). Lost packages are drawn as a bold red explamation
+mark.
 
 =item B<boxplot>
 
@@ -199,7 +223,7 @@ whiskers and 2.5% above.
 
   |----------[#####|##########]--------------------------------------------|
   ^          ^     ^          ^                                            ^
- 2.75%      25%   50%        75%                                         97.5%
+ 2.5%       25%   50%        75%                                         97.5%
 
 =item B<histogram>
 
@@ -208,12 +232,9 @@ as round-trip time from 0ms on the left to the I<interval> (the B<-i> option,
 default 1000ms) on the right.
 
 The height of the graph is scaled so that the most-used buckets vertically fills
-the line. The buckets are colored green up to and including the median, yellow
-up to and including the 95th percentile and red for the remainder.
-
-In addition, the histogram is colored, if supported by the terminal. The green
-bars include the median (50% of responses), yellow bars include the 95th
-percentile and outliers are colored red.
+the line. The buckets are colored green up to and including the 80th
+percentile, yellow up to and including the 95th percentile and red for the
+remainder.
 
 =back
 
@@ -223,19 +244,8 @@ 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>.
+e.g. if B<-cE<nbsp>5> is given, the default is I<80>. The calculated percentile
+is based on the last 900 packets (15 minutes with the default interval).
 
 =item B<-Z> I<percent>
 
@@ -266,11 +276,11 @@ printed in red.
 
 =head1 SEE ALSO
 
-L<ping(8)>, L<http://www.fping.com/>, L<liboping(3)>
+L<ping(8)>, L<http://fping.org/>, L<liboping(3)>
 
 =head1 AUTHOR
 
 liboping is written by Florian "octo" Forster E<lt>ff at octo.itE<gt>.
-Its homepage can be found at L<http://verplant.org/liboping/>.
+Its homepage can be found at L<http://noping.cc/>.
 
 Copyright (c) 2005-2011 by Florian "octo" Forster.