use standard functions for checking

[rrdtool.git] / doc / rrdfetch.pod

diff --git a/doc/rrdfetch.pod b/doc/rrdfetch.pod
index 6eb10d1..29f91bc 100644 (file)
--- a/doc/rrdfetch.pod
+++ b/doc/rrdfetch.pod
@@ -4,10 +4,11 @@ rrdfetch - Fetch data from an RRD.
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 

-B<rrdtool> B<fetch> I<filename> I<CF> 
-S<[B<--resolution>|B<-r> I<resolution>]> 
-S<[B<--start>|B<-s> I<start>]> 
-S<[B<--end>|B<-e> I<end>]> 
+B<rrdtool> B<fetch> I<filename> I<CF>
+S<[B<--resolution>|B<-r> I<resolution>]>
+S<[B<--start>|B<-s> I<start>]>
+S<[B<--end>|B<-e> I<end>]>
+S<[B<--daemon> I<address>]>

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 


@@ -20,11 +21,11 @@ function.
 
 =over 8
 
 
 =over 8
 

-=item I<filename> 
+=item I<filename>

 
 the name of the B<RRD> you want to fetch the data from.
 
 
 the name of the B<RRD> you want to fetch the data from.
 

-=item I<CF> 
+=item I<CF>

 
 the consolidation function that is applied to the data you
 want to fetch (AVERAGE,MIN,MAX,LAST)
 
 the consolidation function that is applied to the data you
 want to fetch (AVERAGE,MIN,MAX,LAST)


@@ -48,12 +49,28 @@ the end of the time series in seconds since epoch. See also AT-STYLE
 TIME SPECIFICATION section for a detailed explanation of how to
 specify the end time.
 
 TIME SPECIFICATION section for a detailed explanation of how to
 specify the end time.
 

+=item B<--daemon> I<address>
+
+Address of the L<rrdcached> daemon. If specified, a C<flush> command is sent
+to the server before reading the RRD files. This allows B<rrdtool> to return
+fresh data even if the daemon is configured to cache values for a long time.
+For a list of accepted formats, see the B<-l> option in the L<rrdcached> manual.
+
+ rrdtool fetch --daemon unix:/var/run/rrdcached.sock /var/lib/rrd/foo.rrd AVERAGE
+
+Please note that due to thread-safety reasons, the time specified with B<-s>
+and B<-e> cannot use the complex forms described in
+L<"AT-STYLE TIME SPECIFICATION">. The only accepted arguments are "simple
+integers". Positive values are interpreted as seconds since epoch, negative
+values (and zero) are interpreted as relative to I<now>. So "1272535035" refers
+to "09:57:15 (UCT), April 29th 2010" and "-3600" means "one hour ago".
+

 =back
 
 =head2 RESOLUTION INTERVAL
 
 =back
 
 =head2 RESOLUTION INTERVAL
 

-In order to get RRDtool to fetch anything other than the finest resolution RRA 
-B<both> the start and end time must be specified on boundaries that are 
+In order to get RRDtool to fetch anything other than the finest resolution RRA
+B<both> the start and end time must be specified on boundaries that are

 multiples of the desired resolution. Consider the following example:
 
  rrdtool create subdata.rrd -s 10 DS:ds0:GAUGE:300:0:U \
 multiples of the desired resolution. Consider the following example:
 
  rrdtool create subdata.rrd -s 10 DS:ds0:GAUGE:300:0:U \


@@ -92,10 +109,10 @@ both start and end time are within the desired RRA
 
 =back
 
 
 =back
 

-So, if time now is called "t", do 
+So, if time now is called "t", do

 
  end time == int(t/900)*900,
 
  end time == int(t/900)*900,

- start time == end time - 1hour, 
+ start time == end time - 1hour,

  resolution == 900.
 
 Using the bash shell, this could look be:
  resolution == 900.
 
 Using the bash shell, this could look be:


@@ -103,7 +120,7 @@ Using the bash shell, this could look be:
  TIME=$(date +%s)
  RRDRES=900
  rrdtool fetch subdata.rrd AVERAGE -r $RRDRES \
  TIME=$(date +%s)
  RRDRES=900
  rrdtool fetch subdata.rrd AVERAGE -r $RRDRES \

-    -e $(echo $(($TIME/$RRDRES*$RRDRES))) -s e-1h
+    -e $(($TIME/$RRDRES*$RRDRES)) -s e-1h

 
 Or in Perl:
 
 
 Or in Perl:
 


@@ -135,14 +152,12 @@ or just B<HH>. You can suffix it with B<am> or B<pm> or use
 including B<midnight> (00:00), B<noon> (12:00) and British
 B<teatime> (16:00).
 
 including B<midnight> (00:00), B<noon> (12:00) and British
 B<teatime> (16:00).
 

-=for comment
-XXX Wouldn't it be nice to have z'N\"uni and z'Vieri for Switzerland?
-
-The I<day> can be specified as I<month-name> I<day-of-the-month>
-and optional a 2- or 4-digit I<year> number (e.g. March 8 1999).
-Alternatively, you can use I<day-of-week-name> (e.g. Monday),
-or one of the words: B<yesterday>, B<today>, B<tomorrow>.
-You can also specify the I<day> as a full date in several numerical formats, including B<MM/DD/[YY]YY>, B<DD.MM.[YY]YY>, or B<YYYYMMDD>.
+The I<day> can be specified as I<month-name> I<day-of-the-month> and
+optional a 2- or 4-digit I<year> number (e.g. March 8 1999). Alternatively,
+you can use I<day-of-week-name> (e.g. Monday), or one of the words:
+B<yesterday>, B<today>, B<tomorrow>. You can also specify the I<day> as a
+full date in several numerical formats, including B<MM/DD/[YY]YY>,
+B<DD.MM.[YY]YY>, or B<YYYYMMDD>.

 
 I<NOTE1>: this is different from the original at(1) behavior, where a
 single-number date is interpreted as MMDD[YY]YY.
 
 I<NOTE1>: this is different from the original at(1) behavior, where a
 single-number date is interpreted as MMDD[YY]YY.


@@ -150,11 +165,16 @@ single-number date is interpreted as MMDD[YY]YY.
 I<NOTE2>: if you specify the I<day> in this way, the I<time-of-day> is
 REQUIRED as well.
 
 I<NOTE2>: if you specify the I<day> in this way, the I<time-of-day> is
 REQUIRED as well.
 

-Finally, you can use the words B<now>, B<start>, or B<end> as your time
+Finally, you can use the words B<now>, B<start>, B<end> or B<epoch> as your time

 reference. B<Now> refers to the current moment (and is also the default
 time reference). B<Start> (B<end>) can be used to specify a time
 relative to the start (end) time for those tools that use these
 reference. B<Now> refers to the current moment (and is also the default
 time reference). B<Start> (B<end>) can be used to specify a time
 relative to the start (end) time for those tools that use these

-categories (B<rrdfetch>, L<rrdgraph>).
+categories (B<rrdfetch>, L<rrdgraph>) and B<epoch> indicates the 
+*IX epoch (*IX timestamp 0 = 1970-01-01 00:00:00 UTC). B<epoch> is
+useful to disambiguate between a timestamp value and some forms
+of abbreviated date/time specifications, because it allows to use 
+time offset specifications using units, eg. B<epoch>+19711205s unambiguously
+denotes timestamp 19711205 and not 1971-12-05 00:00:00 UTC.

 
 Month and day of the week names can be used in their naturally
 abbreviated form (e.g., Dec for December, Sun for Sunday, etc.). The
 
 Month and day of the week names can be used in their naturally
 abbreviated form (e.g., Dec for December, Sun for Sunday, etc.). The


@@ -259,6 +279,22 @@ I<931225537> -- 18:45  July 5th, 1999
 I<19970703 12:45> -- 12:45  July 3th, 1997
 (my favorite, and its even got an ISO number (8601)).
 
 I<19970703 12:45> -- 12:45  July 3th, 1997
 (my favorite, and its even got an ISO number (8601)).
 

+=head1 ENVIRONMENT VARIABLES
+
+The following environment variables may be used to change the behavior of
+C<rrdtoolE<nbsp>fetch>:
+
+=over 4
+
+=item B<RRDCACHED_ADDRESS>
+
+If this environment variable is set it will have the same effect as specifying
+the C<--daemon> option on the command line. If both are present, the command
+line argument takes precedence.
+
+=back
+

 =head1 AUTHOR
 
 =head1 AUTHOR
 

-Tobias Oetiker <oetiker@ee.ethz.ch>
+Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
+