Imported upstream version 1.3.8.

[pkg-rrdtool.git] / doc / rrdgraph_data.1

diff --git a/doc/rrdgraph_data.1 b/doc/rrdgraph_data.1
index 1118388fc8079a3ecf78b185e1c44d40e72165ac..bf7511c6c08aaf239ba1f8bc3119dac55afc2058 100644 (file)
--- a/doc/rrdgraph_data.1
+++ b/doc/rrdgraph_data.1
@@ -1,15 +1,7 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
 .\"
 .\" 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
@@ -48,22 +40,25 @@
 .    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.
@@ -129,12 +124,16 @@
 .\" ========================================================================
 .\"
 .IX Title "RRDGRAPH_DATA 1"
-.TH RRDGRAPH_DATA 1 "2009-02-21" "1.3.7" "rrdtool"
+.TH RRDGRAPH_DATA 1 "2009-04-29" "1.3.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"
 rrdgraph_data \- preparing data for graphing in rrdtool graph
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
-\&\fB\s-1DEF:\s0\fR\fI<vname>\fR=\fI<rrdfile>\fR:\fI<ds-name>\fR:\fI<\s-1CF\s0>\fR[:step=\fI<step>\fR][:start=\fI<time>\fR][:end=\fI<time>\fR][:reduce=\fI<\f(BI\s-1CF\s0\fI>\fR]
+\&\fB\s-1DEF:\s0\fR\fI<vname>\fR=\fI<rrdfile>\fR:\fI<ds\-name>\fR:\fI<\s-1CF\s0>\fR[:step=\fI<step>\fR][:start=\fI<time>\fR][:end=\fI<time>\fR][:reduce=\fI<\f(BI\s-1CF\s0\fI>\fR]
 .PP
 \&\fB\s-1VDEF\s0\fR:\fIvname\fR=\fI\s-1RPN\s0 expression\fR
 .PP
@@ -156,7 +155,7 @@ already taken by an \s-1RPN\s0 operator. A safe bet it to use lowercase or
 mixedcase names for variables since operators will always be in uppercase.
 .SH "DEF"
 .IX Header "DEF"
-\&\fB\s-1DEF:\s0\fR\fI<vname>\fR=\fI<rrdfile>\fR:\fI<ds-name>\fR:\fI<\s-1CF\s0>\fR[:step=\fI<step>\fR][:start=\fI<time>\fR][:end=\fI<time>\fR][:reduce=\fI<\f(BI\s-1CF\s0\fI>\fR]
+\&\fB\s-1DEF:\s0\fR\fI<vname>\fR=\fI<rrdfile>\fR:\fI<ds\-name>\fR:\fI<\s-1CF\s0>\fR[:step=\fI<step>\fR][:start=\fI<time>\fR][:end=\fI<time>\fR][:reduce=\fI<\f(BI\s-1CF\s0\fI>\fR]
 .PP
 This command fetches data from an \fB\s-1RRD\s0\fR file.  The virtual name
 \&\fIvname\fR can then be used throughout the rest of the script. By
@@ -179,7 +178,7 @@ start and end times, such as \f(CW\*(C`\-\-start end\-8days8hours\*(C'\fR).
 .PP
 If consolidation needs to be done, the \fB\s-1CF\s0\fR of the \fB\s-1RRA\s0\fR specified in the
 \&\fB\s-1DEF\s0\fR itself will be used to reduce the data density. This behaviour can
-be changed using \f(CW\*(C`:reduce=\f(CI<\f(CB\s-1CF\s0\f(CI>\f(CW\*(C'\fR.  This optional parameter
+be changed using \f(CW\*(C`:reduce=\f(CI<\f(CBCF\f(CI>\f(CW\*(C'\fR.  This optional parameter
 specifies the \fB\s-1CF\s0\fR to use during the data reduction phase.
 .PP
 Example:
@@ -217,6 +216,32 @@ data point. The resulting \fIvname\fR can then be used further on in
 the script, just as if it were generated by a \fB\s-1DEF\s0\fR instruction.
 .PP
 Example: \f(CW\*(C`CDEF:mydatabits=mydata,8,*\*(C'\fR
+.SH "About CDEF versus VDEF"
+.IX Header "About CDEF versus VDEF"
+At some point in processing, \fBRRDtool\fR has gathered an array of rates
+ready to display.
+.PP
+\&\fB\s-1CDEF\s0\fR works on such an array.  For example, \fICDEF:new=ds0,8,*\fR
+would multiply each of the array members by eight (probably
+transforming bytes into bits). The result is an array containing the
+new values.
+.PP
+\&\fB\s-1VDEF\s0\fR also works on such an array but in a different way.  For
+example, \fIVDEF:max=ds0,MAXIMUM\fR would scan each of the array members
+and store the maximum value.
+.SS "When do you use \fB\s-1VDEF\s0\fP versus \fB\s-1CDEF\s0\fP?"
+.IX Subsection "When do you use VDEF versus CDEF?"
+Use \fB\s-1CDEF\s0\fR to transform your data prior to graphing.  In the above
+example, we'd use a \fB\s-1CDEF\s0\fR to transform bytes to bits before
+graphing the bits.
+.PP
+You use a \fB\s-1VDEF\s0\fR if you want \fImax(1,5,3,2,4)\fR to return five which
+would be displayed in the graph's legend (to answer, what was the
+maximum value during the graph period).
+.PP
+If you want to apply 'complex' operations to the result of a \s-1VDEF\s0 you have
+to use a \s-1CDEF\s0 again since VDEFs only look like \s-1RPN\s0 expressions, they aren't
+realy.
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
 rrdgraph gives an overview of how \fBrrdtool graph\fR works.