the operator in the example is * not + -- Nick Sharp njsharp bigpond.net.au
[rrdtool.git] / doc / rrdgraph_graph.pod
1 =pod
2
3 =head1 NAME
4
5 rrdgraph_graph - rrdtool graph command reference
6
7 =head1 SYNOPSIS
8
9 B<PRINT>B<:>I<vname>B<:>I<format>
10
11 B<GPRINT>B<:>I<vname>B<:>I<format>
12
13 B<COMMENT>B<:>I<text>
14
15 B<VRULE>B<:>I<time>B<#>I<color>[B<:>I<legend>]
16
17 B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
18
19 B<AREA>B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
20
21 B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
22
23 B<SHIFT>B<:>I<vname>B<:>I<offset>
24
25 =cut
26
27 #
28 #B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
29 #
30
31 =pod
32
33 B<PRINT>B<:>I<vname>B<:>I<CF>B<:>I<format> (deprecated)
34
35 B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format> (deprecated)
36
37 B<HRULE>B<:>I<value>B<#>I<color>[B<:>I<legend>] (deprecated)
38
39 B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>] (deprecated)
40
41 =head1 DESCRIPTION
42
43 These instructions allow you to generate your image or report.
44 If you don't use any graph elements, no graph is generated.
45 Similarly, no report is generated if you don't use print options.
46
47 =head1 PRINT
48
49 =over 4
50
51
52 =item B<PRINT:>I<vname>B<:>I<format>
53
54 Depending on the context, either the value component or the time
55 component of a B<VDEF> is printed using I<format>. It is an error
56 to specify a I<vname> generated by a B<DEF> or B<CDEF>.
57
58 Any text in I<format> is printed literally with one exception:
59 The percent character introduces a formatter string. This string
60 can be:
61
62 For printing values:
63
64 =over 4
65
66 =item *
67
68 B<%%> just prints a literal '%' character
69
70 =item *
71
72 B<%#.#le> prints numbers like 1.2346e+04. The optional integers # denote field
73 width and decimal precision.
74
75 =item *
76
77 B<%#.#lf> prints numbers like 12345.6789, with optional field width
78 and precision.
79
80 =item *
81
82 B<%s> place this after B<%le>, B<%lf> or B<%lg>. This will be replaced by the
83 appropriate SI magnitude unit and the value will be scaled
84 accordingly (123456 -> 123.456 k).
85
86 =item *
87
88 B<%S> is similar to B<%s>. It does, however, use a previously defined
89 magnitude unit. If there is no such unit yet, it tries to define
90 one (just like B<%s>) unless the value is zero, in which case the magnitude
91 unit stays undefined. Thus, formatter strings using B<%S> and no B<%s>
92 will all use the same magnitude unit except for zero values.
93
94 =back
95
96 For printing times:
97
98 =over 4
99
100 =item *
101
102 B<%%> just prints a literal '%' character
103
104 =item *
105
106 B<%a, %A> print the abbreviated or full name of the day of the week.
107
108 =item *
109
110 B<%b, %B> print the abbreviated or full name of the month.
111
112 =item *
113
114 B<%d, %m, %y, %H, %M, %S> print day, month, year, hour, minute, and
115 second in two-digit format.
116
117 =item *
118
119 B<%Y> prints the year in 4-digit format.
120
121 =item *
122
123 B<%I, %p> print the hour (01..12), 'am' or 'pm'.
124
125 =item *
126
127 B<%j, %w> print day of the week (0..6), day of the year (1..366)
128
129 =item *
130
131 B<%c, %x, %X> print date+time, date only, time only.
132
133 =item *
134
135 B<%U, %W> number of the week of the current year, with either the
136 first Sunday (%U) or the first Monday (%W) determining the first week.
137
138 =item *
139
140 B<%Z> prints the time zone.
141
142 =back
143
144 =item B<PRINT:>I<vname>B<:>I<CF><:>I<format>
145
146 I<Deprecated. Use the new form of this command in new scripts.>
147 The first form of this command is to be used with B<CDEF> I<vname>s.
148
149 =back
150
151 =head1 GRAPH
152
153 =over 4
154
155 =item B<GPRINT>B<:>I<vname>B<:>I<format>
156
157 This is the same as C<PRINT>, but printed inside the graph.
158
159 =item B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format>
160
161 I<Deprecated. Use the new form of this command in new scripts.>
162 This is the same as C<PRINT>, but printed inside the graph.
163
164 =item B<COMMENT>B<:>I<text>
165
166 Text is printed literally in the legend section of the graph. Note that in
167 RRDtool 1.2 you have to escape colons in COMMENT text in the same way you
168 have to escape them in B<*PRINT> commands by writing B<'\:'>.
169
170 =item B<HRULE>B<:>I<value>B<#>I<color> [ :I<legend> ]
171
172 I<Deprecated. Use B<LINE> in new scripts.>
173
174 =item B<VRULE>B<:>I<time>B<#>I<color> [B<:>I<legend> ]
175
176 Draw a vertical line at I<time>.  Its color is composed from three
177 hexadecimal numbers specifying the rgb color components (00 is off, FF is
178 maximum) red, green and blue. Optionally, a legend box and string is
179 printed in the legend section. I<time> may be a number or a variable
180 from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
181
182 =item B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
183
184 Draw a line of the specified width onto the graph. I<width> can be a
185 floating point number. If the color is not specified, the drawing is done
186 'invisibly'. This is useful when stacking something else on top of this
187 line. Also optional is the legend box and string which will be printed in
188 the legend section if specified. The B<value> can be generated by B<DEF>,
189 B<VDEF>, and B<CDEF>.  If the optional B<STACK> modifier is used, this line
190 is stacked on top of the previous element which can be a B<LINE> or an
191 B<AREA>.
192
193 When you do not specify a color, you cannot specify a legend.  Should
194 you want to use STACK, use the "LINEx:<value>::STACK" form.
195
196 =item B<AREA>B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
197
198 See B<LINE>, however the area between the x-axis and the line will
199 be filled.
200
201 =item B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
202
203 Plot a tick mark (a vertical line) for each value of I<vname> that is
204 non-zero and not *UNKNOWN*. The I<fraction> argument specifies the
205 length of the tick mark as a fraction of the y-axis; the default value
206 is 0.1 (10% of the axis). Note that the color specification is not
207 optional.
208
209 =item B<SHIFT>B<:>I<vname>B<:>I<offset>
210
211 Using this command B<RRDtool> will graph the following elements
212 with the specified offset.  For instance, you can specify an
213 offset of S<( 7*24*60*60 = ) 604'800 seconds> to "look back" one
214 week. Make sure to tell the viewer of your graph you did this ...
215 As with the other graphing elements, you can specify a number or
216 a variable here.
217
218 =cut
219
220 # This section describes the curruently defunct
221 # PieChart code.
222 #
223 # =item B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
224 #
225 # B<RRDtool> has now support for B<pie charts>. If you include the
226 # B<PART> command, the canvas is extended to make room for a chart.
227 # The size of the canvas is determined by the lesser of
228 # L<width and height|rrdgraph/item_Size>.
229 #
230 # Pie parts will be concatenated, the first one will start at the
231 # top and parts will be created clockwise.  The size of the part
232 # is defined by the value part of the L<VDEF|rrdgraph_data/VDEF>
233 # function.  It should return a number between 0 and 100, being a
234 # percentage.  Providing wrong input will produce undefined results.
235 #
236 #
237
238 =pod
239
240 =item B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>]
241
242 I<Deprecated.  Use the B<STACK> modifiers on the other commands.>
243
244 =back
245
246 B<Some notes on stacking>
247
248 When stacking, an element is not placed above the X-axis but rather
249 on top of the previous element.  There must be something to stack
250 upon.
251
252 You can use an B<invisible> LINE or AREA to stacked upon.
253
254 An B<unknown> value makes the entire stack unknown from that moment on.
255 You don't know where to begin (the unknown value) and therefore do
256 not know where to end.
257
258 If you want to make sure you will be displaying a certain variable,
259 make sure never to stack upon the unknown value.  Use a CDEF instruction
260 with B<IF> and B<UN> to do so.
261
262 =head1 NOTES on legend arguments
263
264 =head2 Escaping the colon
265
266 A colon ':' in a I<legend> argument will mark the end of the
267 legend. To enter a ':' as part of a legend, the colon must be escaped
268 with a backslash '\:'.  Beware that many environments process
269 backslashes themselves, so it may be necessary to write two
270 backslashes in order to one being passed onto rrd_graph.
271
272 =head2 String Formatting
273
274 The text printed below the actual graph can be formatted by appending special
275 escape characters at the end of a text. When ever such a character occurs,
276 all pending text is pushed onto the graph according to the character
277 specified.
278
279 Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
280 right aligned, and B<\c> for centered. In the next section there is an
281 example showing how to use centered formatting.
282
283 Normally there are two space characters inserted between every two items
284 printed into the graph. The space following a string can be suppressed by
285 putting a B<\g> at the end of the string. The B<\g> also ignores any space
286 inside the string if it is at the very end of the string. This can be used
287 in connection with B<%s> to suppress empty unit strings.
288
289  GPRINT:a:MAX:%lf%s\g
290
291 A special case is COMMENT:B<\s> which inserts some additional vertical space
292 before placing the next row of legends.
293
294 If you are using the proportional font in your graph, you can use tab
295 characters or the sequence B<\t> to line-up legend elements. Note that
296 the tabs inserted are relative to the start of the current legend
297 element!
298
299 =head1 SEE ALSO
300
301 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
302 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
303 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
304 L<rrdgraph_graph> page describes all of the graph and print functions.
305
306 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
307
308 =head1 AUTHOR
309
310 Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
311
312 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>