+=pod
+
=head1 NAME
-rrdtool graph - Round Robin Database tool grapher functions
+rrdgraph_graph - rrdtool graph command reference
+
+=head1 SYNOPSIS
+
+B<PRINT>B<:>I<vname>B<:>I<format>
+
+B<GPRINT>B<:>I<vname>B<:>I<format>
+
+B<COMMENT>B<:>I<text>
-WARNING: This is for version 1.1.x which is B<I<BETA>> software.
-The software may contain serious bugs. Some of the items
-described in here may not yet exist (although this should
-be mentioned) or still be in the alpha stage. As with every
-other RRDtool release: use at your own risk. In contrast with
-the stable version of RRDtool, this release may contain bugs
-known to the authors. It is highly recommended that you subscribe
-to the mailing list.
+B<VRULE>B<:>I<time>B<#>I<color>[B<:>I<legend>]
-=head1 SYNOPSYS
+B<HRULE>B<:>I<value>B<#>I<color>[B<:>I<legend>]
-I<(to be) Depriciated commands>
+B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
-[B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>]
-[B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>]
-[B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]]
-[B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]
+B<AREA>B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
-I<(soon) available commands>
+B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
-[B<PRINT:>I<vname>B<:>I<format>]
-[B<GPRINT:>I<vname>B<:>I<format>]
-[B<COMMENT:>I<text>]
-[B<VRULE:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]]
-[B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]][B<:STACK>]
-[B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]][B<:STACK>]
+B<SHIFT>B<:>I<vname>B<:>I<offset>
-I<to be implemented commands>
+B<TEXTALIGN>B<:>{B<left>|B<right>|B<justified>|B<center>}
-[B<SHIFT:>I<vname>]
-[B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]]
+B<PRINT>B<:>I<vname>B<:>I<CF>B<:>I<format> (deprecated)
+
+B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format> (deprecated)
+
+B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>] (deprecated)
=head1 DESCRIPTION
These instructions allow you to generate your image or report.
If you don't use any graph elements, no graph is generated.
-Similarly no report is generated if you don't use print options.
+Similarly, no report is generated if you don't use print options.
=head1 PRINT
-B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>
+=over 4
-I<Depriciated. Use the new form of this command in new scripts.>
-The first form of this command is to be used with B<CDEF> I<vname>s.
-B<PRINT:>I<vname>B<:>I<format>
+=item B<PRINT:>I<vname>B<:>I<format>[B<:strftime>]
Depending on the context, either the value component or the time
component of a B<VDEF> is printed using I<format>. It is an error
=over 4
-=item *
+=item B<%%>
-B<%%> just prints a literal '%' character
+just prints a literal '%' character
-=item *
+=item B<%#.#le>
-B<%#.#le> (where # is an optional number) prints like 1.2346e+04
+prints numbers like 1.2346e+04. The optional integers # denote field
+width and decimal precision.
-=item *
+=item B<%#.#lf>
-B<%#.#lf> prints like 12345.6789
+prints numbers like 12345.6789, with optional field width
+and precision.
-=item *
+=item B<%s>
-B<%s> place this after B<%le> or B<%lf>. This will be replaced by the
+place this after B<%le>, B<%lf> or B<%lg>. This will be replaced by the
appropriate SI magnitude unit and the value will be scaled
-accordingly (123456 -> 123.456 k)
+accordingly (123456 -> 123.456 k).
-=item *
+=item B<%S>
-B<%S> is similar to B<%s>. It does however use a previously defined
+is similar to B<%s>. It does, however, use a previously defined
magnitude unit. If there is no such unit yet, it tries to define
-one (just like B<%s>). However, if the value is zero, the magnitude
+one (just like B<%s>) unless the value is zero, in which case the magnitude
unit stays undefined. Thus, formatter strings using B<%S> and no B<%s>
will all use the same magnitude unit except for zero values.
=back
-For printing times:
+If you PRINT a VDEF value, you can also print the time associated with it by appending the string
+B<:strftime> to the format. Note that rrdtool uses the strftime function of your OSs clibrary. This means that
+the conversion specifier may vary. Check the manual page if you are uncertain. The following is a list of
+conversion specifiers usually supported across the board.
=over 4
-=item *
+=item B<%a>
+
+The abbreviated weekday name according to the current locale.
+
+=item B<%A>
+
+The full weekday name according to the current locale.
+
+=item B<%b>
+
+The abbreviated month name according to the current locale.
+
+=item B<%B>
+
+The full month name according to the current locale.
+
+=item B<%c>
+
+The preferred date and time representation for the current locale.
+
+=item B<%d>
+
+The day of the month as a decimal number (range 01 to 31).
+
+=item B<%H>
+
+The hour as a decimal number using a 24-hour clock (range 00 to 23).
+
+=item B<%I>
+
+The hour as a decimal number using a 12-hour clock (range 01 to 12).
+
+=item B<%j>
+
+The day of the year as a decimal number (range 001 to 366).
+
+=item B<%m>
+
+The month as a decimal number (range 01 to 12).
+
+=item B<%M>
+
+The minute as a decimal number (range 00 to 59).
+
+=item B<%p>
+
+Either `AM' or `PM' according to the given time value, or the corresponding
+strings for the current locale. Noon is treated as `pm' and midnight as
+`am'. Note that in many locales and `pm' notation is unsupported and in
+such cases %p will return an empty string.
+
+=item B<%S>
-B<%%> just prints a literal '%' character
+The second as a decimal number (range 00 to 61).
-=item *
+=item B<%U>
-B<%a, %A> prints abbreviated, full weekday name
+The week number of the current year as a decimal number, range 00 to 53, starting with the
+first Sunday as the first day of week 01. See also %V and %W.
-=item *
+=item B<%V>
-B<%b, %B> prints abbreviated, full month name
+The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where
+week 1 is the first week that has at least 4 days in the current year, and with Monday as the
+first day of the week. See also %U and %W.
-=item *
+=item B<%w>
-B<%d, %m, %y, %H, %M, %S> day,month,year,hour,minute,second all in two-digit format
+The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.
-=item *
+=item B<%W>
-B<%Y> year in 4-digit format
+The week number of the current year as a decimal number, range 00 to 53, starting with the
+first Monday as the first day of week 01.
-=item *
+=item B<%x>
-B<%I, %p> hour (01..12), 'am' or 'pm'
+The preferred date representation for the current locale without the time.
-=item *
+=item B<%X>
-B<%j, %w> day of the week (0..6), day of the year (1..366)
+The preferred time representation for the current locale without the date.
-=item *
+=item B<%y>
-B<%c, %x, %X> date+time, date, time
+The year as a decimal number without a century (range 00 to 99).
-=item *
+=item B<%Y>
-B<%U, %W> week number of the current year with either the first sunday or
-the first monday determining the first week
+The year as a decimal number including the century.
-=item *
+=item B<%Z>
-B<%Z> time zone
+The time zone or name or abbreviation.
+
+=item B<%%>
+
+A literal `%' character.
=back
-=head1 GRAPH
+=item B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>
+
+I<Deprecated. Use the new form of this command in new scripts.>
+The first form of this command is to be used with B<CDEF> I<vname>s.
+
+=back
-B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>
+=head1 GRAPH
-I<Depriciated. Use the new form of this command in new scripts.>
-This is the same as B<PRINT> but now it is printed inside the graph.
-See L<PRINT> for more information.
+=over 4
-B<GPRINT:>I<vname>B<:>I<format>
+=item B<GPRINT>B<:>I<vname>B<:>I<format>
-This is the same as B<PRINT> but now it is printed inside the graph.
-See L<PRINT> for more information.
+This is the same as C<PRINT>, but printed inside the graph.
-B<COMMENT:>I<text>
+=item B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format>
-Text is printed literally in the legend section of the graph
+I<Deprecated. Use the new form of this command in new scripts.>
+This is the same as C<PRINT>, but printed inside the graph.
-B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]
+=item B<COMMENT>B<:>I<text>
-Draw an horizontal line at I<value>. Its color is composed from three
-hexadecimal numbers specifying the color components (00 is off, FF is
-maximum) red, green and blue. Optionally a legend box and string is
-printed in the legend section. I<value> can be a variable from a B<VDEF>.
-It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
+Text is printed literally in the legend section of the graph. Note that in
+RRDtool 1.2 you have to escape colons in COMMENT text in the same way you
+have to escape them in B<*PRINT> commands by writing B<'\:'>.
-B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]
+=item B<VRULE>B<:>I<time>B<#>I<color> [B<:>I<legend> ]
Draw a vertical line at I<time>. Its color is composed from three
-hexadecimal numbers specifying the color components (00 is off, FF is
-maximum) red, green and blue. Optionally a legend box and string is
+hexadecimal numbers specifying the rgb color components (00 is off, FF is
+maximum) red, green and blue followed by an optional alpha. Optionally, a legend box and string is
printed in the legend section. I<time> may be a number or a variable
from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
-B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>]
+=item B<HRULE>B<:>I<value>B<#>I<color> [ :I<legend> ]
+
+Draw a horyzontal line at I<value>. HRULE acts much like LINE except that
+will have no effect on the scale of the graph. If a HRULE is outside the
+graphing area it will just not be visible.
-Draw a line of the specified width into the graph. If the color
-is not specified, the drawing is done 'blind'. This is useful when
-stacking something else on top of this line. Also optional is the
-legend box and string which will be printed in the legend section
-if specified. The B<vname> can be generated by B<DEF>, B<VDEF> and
-B<CDEF>. If the optional B<STACK> modifier is used, this line is
-stacked on top of the previous element which can be a B<LINEx> or
-an B<AREA>
+=item B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
-B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>]
+Draw a line of the specified width onto the graph. I<width> can be a
+floating point number. If the color is not specified, the drawing is done
+'invisibly'. This is useful when stacking something else on top of this
+line. Also optional is the legend box and string which will be printed in
+the legend section if specified. The B<value> can be generated by B<DEF>,
+B<VDEF>, and B<CDEF>. If the optional B<STACK> modifier is used, this line
+is stacked on top of the previous element which can be a B<LINE> or an
+B<AREA>.
-See B<LINEx>, however the area between the x-axis and the line will
-also be filled.
+When you do not specify a color, you cannot specify a legend. Should
+you want to use STACK, use the "LINEx:<value>::STACK" form.
-B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
+=item B<AREA>B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
-I<Depriciated. Use the B<STACK> modifiers on the other commands.>
-I<Note: the comments on stacking are still valid...>
-Repeats the last B<LINEx> or B<AREA> however it doesn't start at the
-x-axis but rather on top of the previous element. This implies that
-there needs to be something to stack on. An invisible B<LINEx> or
-B<AREA> is something you can stack on!
+See B<LINE>, however the area between the x-axis and the line will
+be filled.
-Note: When you stack on something that was I<unknown>, the whole
-stack will be I<unknown> for that point in time. If the beginning
-is undefined, there's no way to end somewhere... If you want to
-graph this stacked variable anyway you need to make sure that the
-B<LINEx> or B<AREA> it gets stacked on is not unknown. Use a CDEF
-instruction with B<IF> and B<UN> to do so.
+=item B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
-B<THE NEXT STUFF IS NOT YET IMPLEMENTED>
+Plot a tick mark (a vertical line) for each value of I<vname> that is
+non-zero and not *UNKNOWN*. The I<fraction> argument specifies the length of
+the tick mark as a fraction of the y-axis; the default value is 0.1 (10% of
+the axis). Note that the color specification is not optional. The TICK marks normaly
+start at the lower edge of the graphing area. If the fraction is negative they start
+at the upper border of the graphing area.
-B<SHIFT:>I<offset in seconds>
+=item B<SHIFT>B<:>I<vname>B<:>I<offset>
Using this command B<RRDtool> will graph the following elements
with the specified offset. For instance, you can specify an
-offset of S<( 7*24*60*60 = ) 604800 seconds> to "look back" one
-week. Make sure to notify the viewer you did so...
-The offset will be valid until the next B<SHIFT> command, which
-can have an offset of zero to restore normal graphing.
-As with the other grapher elements, you can specify a number or
+offset of S<( 7*24*60*60 = ) 604'800 seconds> to "look back" one
+week. Make sure to tell the viewer of your graph you did this ...
+As with the other graphing elements, you can specify a number or
a variable here.
-B<RRDtool> has now support for B<pie charts>. If you include the
-B<PART> command, the canvas is extended to make room for a chart
-(or, if no other graph elements are used, the canvas is solely
-used for the pie chart). The size of the canvas is determined by
-the lesser of L<width and height|rrdgraph/item_Size>.
+=item B<TEXTALIGN>B<:>{B<left>|B<right>|B<justified>|B<center>}
+
+Labels are placed below the graph. When they overflow to the left, they wrap
+to the next line. By default, lines are justified left and right. The
+B<TEXTALIGN> function lets you change this default. This is a command and
+not an option, so that you can change the default several times in your
+argument list.
+
+=cut
+
+# This section describes the curruently defunct
+# PieChart code.
+#
+# =item B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
+#
+# B<RRDtool> has now support for B<pie charts>. If you include the
+# B<PART> command, the canvas is extended to make room for a chart.
+# The size of the canvas is determined by the lesser of
+# L<width and height|rrdgraph/item_Size>.
+#
+# Pie parts will be concatenated, the first one will start at the
+# top and parts will be created clockwise. The size of the part
+# is defined by the value part of the L<VDEF|rrdgraph_data/VDEF>
+# function. It should return a number between 0 and 100, being a
+# percentage. Providing wrong input will produce undefined results.
+#
+#
+
+=pod
+
+=item B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>]
+
+I<Deprecated. Use the B<STACK> modifiers on the other commands.>
+
+=back
+
+B<Some notes on stacking>
+
+When stacking, an element is not placed above the X-axis but rather
+on top of the previous element. There must be something to stack
+upon.
+
+You can use an B<invisible> LINE or AREA to stacked upon.
+
+An B<unknown> value makes the entire stack unknown from that moment on.
+You don't know where to begin (the unknown value) and therefore do
+not know where to end.
+
+If you want to make sure you will be displaying a certain variable,
+make sure never to stack upon the unknown value. Use a CDEF instruction
+with B<IF> and B<UN> to do so.
+
+=head1 NOTES on legend arguments
+
+=head2 Escaping the colon
+
+A colon ':' in a I<legend> argument will mark the end of the
+legend. To enter a ':' as part of a legend, the colon must be escaped
+with a backslash '\:'. Beware that many environments process
+backslashes themselves, so it may be necessary to write two
+backslashes in order to one being passed onto rrd_graph.
+
+=head2 String Formatting
+
+The text printed below the actual graph can be formatted by appending special
+escape characters at the end of a text. When ever such a character occurs,
+all pending text is pushed onto the graph according to the character
+specified.
+
+Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
+right aligned, and B<\c> for centered. In the next section there is an
+example showing how to use centered formatting.
+
+B<\n> is a valid alias for B<\l> since incomplete parsing in earlier
+versions of rrdtool lead to this behaviour and a number of people has been using it.
+
+Normally there are two space characters inserted between every two items
+printed into the graph. The space following a string can be suppressed by
+putting a B<\g> at the end of the string. The B<\g> also ignores any space
+inside the string if it is at the very end of the string. This can be used
+in connection with B<%s> to suppress empty unit strings.
+
+ GPRINT:a:MAX:%lf%s\g
-B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]
+A special case is COMMENT:B<\s> which inserts some additional vertical space
+before placing the next row of legends.
-Draw a part of pie. Pie parts will be concatenated, the first one
-will start at the top and parts will be created clockwise.
-The size of the part is defined by the value part of
-the L<VDEF|rrdgraph_data/VDEF> function. It should return
-a number between 0 and 100, being a percentage.
-Providing wrong input will produce undefined results.
+If you are using the proportional font in your graph, you can use tab
+characters or the sequence B<\t> to line-up legend elements. Note that
+the tabs inserted are relative to the start of the current legend
+element!
=head1 SEE ALSO
L<rrdgraph> gives an overview of how B<rrdtool graph> works.
-L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
-L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
+L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
+L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
L<rrdgraph_graph> page describes all of the graph and print functions.
Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
=head1 AUTHOR
-Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
+Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>
projects / rrdtool.git / blobdiff