![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdfetch.1 b/doc/rrdfetch.1
index 9c20fb68ba0d76cb6d2964afbfa12303493bd3ec..4a441d9dc38de21eca7dcb6a08c4fc0e0c3b5967 100644 (file)
--- a/doc/rrdfetch.1
+++ b/doc/rrdfetch.1
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
. 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 (.Sh), items (.Ip), and index
+.\" 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.
-.if \nF \{\
+.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
-.\"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.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.
.\" ========================================================================
.\"
.IX Title "RRDFETCH 1"
-.TH RRDFETCH 1 "2008-02-17" "1.2.27" "rrdtool"
+.TH RRDFETCH 1 "2013-05-23" "1.4.8" "rrdtool"
+.\" 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"
rrdfetch \- Fetch data from an RRD.
.SH "SYNOPSIS"
[\fB\-\-resolution\fR|\fB\-r\fR\ \fIresolution\fR]
[\fB\-\-start\fR|\fB\-s\fR\ \fIstart\fR]
[\fB\-\-end\fR|\fB\-e\fR\ \fIend\fR]
+[\fB\-\-daemon\fR\ \fIaddress\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBfetch\fR function is normally used internally by the graph
the end of the time series in seconds since epoch. See also AT-STYLE
\&\s-1TIME\s0 \s-1SPECIFICATION\s0 section for a detailed explanation of how to
specify the end time.
-.Sh "\s-1RESOLUTION\s0 \s-1INTERVAL\s0"
+.IP "\fB\-\-daemon\fR \fIaddress\fR" 8
+.IX Item "--daemon address"
+Address of the rrdcached daemon. If specified, a \f(CW\*(C`flush\*(C'\fR command is sent
+to the server before reading the \s-1RRD\s0 files. This allows \fBrrdtool\fR 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 \fB\-l\fR option in the rrdcached manual.
+.Sp
+.Vb 1
+\& rrdtool fetch \-\-daemon unix:/var/run/rrdcached.sock /var/lib/rrd/foo.rrd AVERAGE
+.Ve
+.SS "\s-1RESOLUTION\s0 \s-1INTERVAL\s0"
.IX Subsection "RESOLUTION INTERVAL"
In order to get RRDtool to fetch anything other than the finest resolution \s-1RRA\s0
\&\fBboth\fR the start and end time must be specified on boundaries that are
Or in Perl:
.PP
.Vb 3
-\& perl \-e '$ctime = time; $rrdres = 900; \e
+\& perl \-e \*(Aq$ctime = time; $rrdres = 900; \e
\& system "rrdtool fetch subdata.rrd AVERAGE \e
-\& \-r $rrdres \-e @{[int($ctime/$rrdres)*$rrdres]} \-s e\-1h"'
+\& \-r $rrdres \-e @{[int($ctime/$rrdres)*$rrdres]} \-s e\-1h"\*(Aq
.Ve
-.Sh "AT-STYLE \s-1TIME\s0 \s-1SPECIFICATION\s0"
+.SS "AT-STYLE \s-1TIME\s0 \s-1SPECIFICATION\s0"
.IX Subsection "AT-STYLE TIME SPECIFICATION"
Apart from the traditional \fISeconds since epoch\fR, RRDtool does also
understand at-style time specification. The specification is called
-\&\*(L"at\-style\*(R" after the Unix command \fIat\fR\|(1) that has moderately complex
+\&\*(L"at-style\*(R" after the Unix command \fIat\fR\|(1) that has moderately complex
ways to specify time to run your job at a certain date and time. The
at-style specification consists of two parts: the \fB\s-1TIME\s0 \s-1REFERENCE\s0\fR
specification and the \fB\s-1TIME\s0 \s-1OFFSET\s0\fR specification.
-.Sh "\s-1TIME\s0 \s-1REFERENCE\s0 \s-1SPECIFICATION\s0"
+.SS "\s-1TIME\s0 \s-1REFERENCE\s0 \s-1SPECIFICATION\s0"
.IX Subsection "TIME REFERENCE SPECIFICATION"
The time reference specification is used, well, to establish a reference
moment in time (to which the time offset is then applied to). When present,
\&\fI\s-1NOTE2\s0\fR: if you specify the \fIday\fR in this way, the \fItime-of-day\fR is
\&\s-1REQUIRED\s0 as well.
.PP
-Finally, you can use the words \fBnow\fR, \fBstart\fR, or \fBend\fR as your time
+Finally, you can use the words \fBnow\fR, \fBstart\fR, \fBend\fR or \fBepoch\fR as your time
reference. \fBNow\fR refers to the current moment (and is also the default
time reference). \fBStart\fR (\fBend\fR) can be used to specify a time
relative to the start (end) time for those tools that use these
-categories (\fBrrdfetch\fR, rrdgraph).
+categories (\fBrrdfetch\fR, rrdgraph) and \fBepoch\fR indicates the
+*IX epoch (*IX timestamp 0 = 1970\-01\-01 00:00:00 \s-1UTC\s0). \fBepoch\fR 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. \fBepoch\fR+19711205s unambiguously
+denotes timestamp 19711205 and not 1971\-12\-05 00:00:00 \s-1UTC\s0.
.PP
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
words \fBnow\fR, \fBstart\fR, \fBend\fR can be abbreviated as \fBn\fR, \fBs\fR, \fBe\fR.
-.Sh "\s-1TIME\s0 \s-1OFFSET\s0 \s-1SPECIFICATION\s0"
+.SS "\s-1TIME\s0 \s-1OFFSET\s0 \s-1SPECIFICATION\s0"
.IX Subsection "TIME OFFSET SPECIFICATION"
The time offset specification is used to add/subtract certain time
intervals to/from the time reference moment. It consists of a \fIsign\fR
\&\fI\s-1NOTE4\s0\fR: The single-letter abbreviation for both \fBmonths\fR and \fBminutes\fR
is \fBm\fR. To disambiguate them, the parser tries to read your mind\ :)
by applying the following two heuristics:
-.IP "1" 3
-.IX Item "1"
+.IP "1." 3
If \fBm\fR is used in context of (i.e. right after the) years,
months, weeks, or days it is assumed to mean \fBmonths\fR, while
in the context of hours, minutes, and seconds it means minutes.
(e.g., in \-1y6m or +3w1m \fBm\fR is interpreted as \fBmonths\fR, while in
\&\-3h20m or +5s2m \fBm\fR the parser decides for \fBminutes\fR).
-.IP "2" 3
-.IX Item "2"
+.IP "2." 3
Out of context (i.e. right after the \fB+\fR or \fB\-\fR sign) the
meaning of \fBm\fR is guessed from the number it directly follows.
Currently, if the number's absolute value is below 25 it is assumed
that \fBm\fR means \fBmonths\fR, otherwise it is treated as \fBminutes\fR.
(e.g., \-25m == \-25 minutes, while +24m == +24 months)
.PP
-\&\fIFinal \s-1NOTES\s0\fR: Time specification is case\-insensitive.
+\&\fIFinal \s-1NOTES\s0\fR: Time specification is case-insensitive.
Whitespace can be inserted freely or omitted altogether.
There are, however, cases when whitespace is required
(e.g., 'midnight\ Thu'). In this case you should either quote the
whole phrase to prevent it from being taken apart by your shell or use
\&'_' (underscore) or ',' (comma) which also count as whitespace
(e.g., midnight_Thu or midnight,Thu).
-.Sh "\s-1TIME\s0 \s-1SPECIFICATION\s0 \s-1EXAMPLES\s0"
+.SS "\s-1TIME\s0 \s-1SPECIFICATION\s0 \s-1EXAMPLES\s0"
.IX Subsection "TIME SPECIFICATION EXAMPLES"
\&\fIOct 12\fR \*(-- October 12 this year
.PP
.PP
\&\fI19970703 12:45\fR \*(-- 12:45 July 3th, 1997
(my favorite, and its even got an \s-1ISO\s0 number (8601)).
+.SH "ENVIRONMENT VARIABLES"
+.IX Header "ENVIRONMENT VARIABLES"
+The following environment variables may be used to change the behavior of
+\&\f(CW\*(C`rrdtool\ fetch\*(C'\fR:
+.IP "\fB\s-1RRDCACHED_ADDRESS\s0\fR" 4
+.IX Item "RRDCACHED_ADDRESS"
+If this environment variable is set it will have the same effect as specifying
+the \f(CW\*(C`\-\-daemon\*(C'\fR option on the command line. If both are present, the command
+line argument takes precedence.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker <tobi@oetiker.ch>