doc/rrdgraph_graph.1

   1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "RRDGRAPH_GRAPH 1"
 127 .TH RRDGRAPH_GRAPH 1 "2010-01-25" "1.4.3" "rrdtool"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 rrdgraph_graph \- rrdtool graph command reference
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 \&\fB\s-1PRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIformat\fR
 137 .PP
 138 \&\fB\s-1GPRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIformat\fR
 139 .PP
 140 \&\fB\s-1COMMENT\s0\fR\fB:\fR\fItext\fR
 141 .PP
 142 \&\fB\s-1VRULE\s0\fR\fB:\fR\fItime\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR][\fB:dashes\fR[\fB=\fR\fIon_s\fR[,\fIoff_s\fR[,\fIon_s\fR,\fIoff_s\fR]...]][\fB:dash\-offset=\fR\fIoffset\fR]]
 143 .PP
 144 \&\fB\s-1HRULE\s0\fR\fB:\fR\fIvalue\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR][\fB:dashes\fR[\fB=\fR\fIon_s\fR[,\fIoff_s\fR[,\fIon_s\fR,\fIoff_s\fR]...]][\fB:dash\-offset=\fR\fIoffset\fR]]
 145 .PP
 146 \&\fB\s-1LINE\s0\fR[\fIwidth\fR]\fB:\fR\fIvalue\fR[\fB#\fR\fIcolor\fR][\fB:\fR[\fIlegend\fR][\fB:STACK\fR]][\fB:dashes\fR[\fB=\fR\fIon_s\fR[,\fIoff_s\fR[,\fIon_s\fR,\fIoff_s\fR]...]][\fB:dash\-offset=\fR\fIoffset\fR]]
 147 .PP
 148 \&\fB\s-1AREA\s0\fR\fB:\fR\fIvalue\fR[\fB#\fR\fIcolor\fR][\fB:\fR[\fIlegend\fR][\fB:STACK\fR]]
 149 .PP
 150 \&\fB\s-1TICK\s0\fR\fB:\fR\fIvname\fR\fB#\fR\fIrrggbb\fR[\fIaa\fR][\fB:\fR\fIfraction\fR[\fB:\fR\fIlegend\fR]]
 151 .PP
 152 \&\fB\s-1SHIFT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIoffset\fR
 153 .PP
 154 \&\fB\s-1TEXTALIGN\s0\fR\fB:\fR{\fBleft\fR|\fBright\fR|\fBjustified\fR|\fBcenter\fR}
 155 .PP
 156 \&\fB\s-1PRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR (deprecated)
 157 .PP
 158 \&\fB\s-1GPRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR (deprecated)
 159 .PP
 160 \&\fB\s-1STACK\s0\fR\fB:\fR\fIvname\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR] (deprecated)
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 These instructions allow you to generate your image or report.
 164 If you don't use any graph elements, no graph is generated.
 165 Similarly, no report is generated if you don't use print options.
 166 .SS "\s-1PRINT\s0"
 167 .IX Subsection "PRINT"
 168 \fI\f(BI\s-1PRINT:\s0\fI\fIvname\fI\f(BI:\fI\fIformat\fI[\f(BI:strftime\fI]\fR
 169 .IX Subsection "PRINT:vname:format[:strftime]"
 170 .PP
 171 Depending on the context, either the value component or the time
 172 component of a \fB\s-1VDEF\s0\fR is printed using \fIformat\fR. It is an error
 173 to specify a \fIvname\fR generated by a \fB\s-1DEF\s0\fR or \fB\s-1CDEF\s0\fR.
 174 .PP
 175 Any text in \fIformat\fR is printed literally with one exception:
 176 The percent character introduces a formatter string. This string
 177 can be:
 178 .PP
 179 For printing values:
 180 .IP "\fB%%\fR" 4
 181 .IX Item "%%"
 182 just prints a literal '%' character
 183 .IP "\fB%#.#le\fR" 4
 184 .IX Item "%#.#le"
 185 prints numbers like 1.2346e+04. The optional integers # denote field
 186 width and decimal precision.
 187 .IP "\fB%#.#lf\fR" 4
 188 .IX Item "%#.#lf"
 189 prints numbers like 12345.6789, with optional field width
 190 and precision.
 191 .ie n .IP "\fB\fB%s\fB\fR" 4
 192 .el .IP "\fB\f(CB%s\fB\fR" 4
 193 .IX Item "%s"
 194 place this after \fB\f(CB%le\fB\fR, \fB\f(CB%lf\fB\fR or \fB\f(CB%lg\fB\fR. This will be replaced by the
 195 appropriate \s-1SI\s0 magnitude unit and the value will be scaled
 196 accordingly (123456 \-> 123.456 k).
 197 .ie n .IP "\fB\fB%S\fB\fR" 4
 198 .el .IP "\fB\f(CB%S\fB\fR" 4
 199 .IX Item "%S"
 200 is similar to \fB\f(CB%s\fB\fR. It does, however, use a previously defined
 201 magnitude unit. If there is no such unit yet, it tries to define
 202 one (just like \fB\f(CB%s\fB\fR) unless the value is zero, in which case the magnitude
 203 unit stays undefined. Thus, formatter strings using \fB\f(CB%S\fB\fR and no \fB\f(CB%s\fB\fR
 204 will all use the same magnitude unit except for zero values.
 205 .PP
 206 If you \s-1PRINT\s0 a \s-1VDEF\s0 value, you can also print the time associated with it by appending the string
 207 \&\fB:strftime\fR to the format. Note that RRDtool uses the strftime function of your OSs C library. This means that
 208 the conversion specifier may vary. Check the manual page if you are uncertain. The following is a list of
 209 conversion specifiers usually supported across the board.
 210 .ie n .IP "\fB\fB%a\fB\fR" 4
 211 .el .IP "\fB\f(CB%a\fB\fR" 4
 212 .IX Item "%a"
 213 The abbreviated weekday name according to the current locale.
 214 .ie n .IP "\fB\fB%A\fB\fR" 4
 215 .el .IP "\fB\f(CB%A\fB\fR" 4
 216 .IX Item "%A"
 217 The full weekday name according to the current locale.
 218 .ie n .IP "\fB\fB%b\fB\fR" 4
 219 .el .IP "\fB\f(CB%b\fB\fR" 4
 220 .IX Item "%b"
 221 The abbreviated month name according to the current locale.
 222 .ie n .IP "\fB\fB%B\fB\fR" 4
 223 .el .IP "\fB\f(CB%B\fB\fR" 4
 224 .IX Item "%B"
 225 The full month name according to the current locale.
 226 .ie n .IP "\fB\fB%c\fB\fR" 4
 227 .el .IP "\fB\f(CB%c\fB\fR" 4
 228 .IX Item "%c"
 229 The preferred date and time representation for the current locale.
 230 .ie n .IP "\fB\fB%d\fB\fR" 4
 231 .el .IP "\fB\f(CB%d\fB\fR" 4
 232 .IX Item "%d"
 233 The day of the month as a decimal number (range 01 to 31).
 234 .ie n .IP "\fB\fB%H\fB\fR" 4
 235 .el .IP "\fB\f(CB%H\fB\fR" 4
 236 .IX Item "%H"
 237 The hour as a decimal number using a 24\-hour clock (range 00 to 23).
 238 .ie n .IP "\fB\fB%I\fB\fR" 4
 239 .el .IP "\fB\f(CB%I\fB\fR" 4
 240 .IX Item "%I"
 241 The hour as a decimal number using a 12\-hour clock (range 01 to 12).
 242 .ie n .IP "\fB\fB%j\fB\fR" 4
 243 .el .IP "\fB\f(CB%j\fB\fR" 4
 244 .IX Item "%j"
 245 The day of the year as a decimal number (range 001 to 366).
 246 .ie n .IP "\fB\fB%m\fB\fR" 4
 247 .el .IP "\fB\f(CB%m\fB\fR" 4
 248 .IX Item "%m"
 249 The month as a decimal number (range 01 to 12).
 250 .ie n .IP "\fB\fB%M\fB\fR" 4
 251 .el .IP "\fB\f(CB%M\fB\fR" 4
 252 .IX Item "%M"
 253 The minute as a decimal number (range 00 to 59).
 254 .ie n .IP "\fB\fB%p\fB\fR" 4
 255 .el .IP "\fB\f(CB%p\fB\fR" 4
 256 .IX Item "%p"
 257 Either `\s-1AM\s0' or `\s-1PM\s0' according to the given time value, or the corresponding
 258 strings for the current locale.  Noon is treated as `pm' and midnight as
 259 `am'.  Note that in many locales and `pm' notation is unsupported and in
 260 such cases \f(CW%p\fR will return an empty string.
 261 .ie n .IP "\fB\fB%s\fB\fR" 4
 262 .el .IP "\fB\f(CB%s\fB\fR" 4
 263 .IX Item "%s"
 264 The second as a decimal number (range 00 to 61).
 265 .ie n .IP "\fB\fB%S\fB\fR" 4
 266 .el .IP "\fB\f(CB%S\fB\fR" 4
 267 .IX Item "%S"
 268 The seconds since the epoch (1.1.1970) (libc dependent non standard!)
 269 .ie n .IP "\fB\fB%U\fB\fR" 4
 270 .el .IP "\fB\f(CB%U\fB\fR" 4
 271 .IX Item "%U"
 272 The  week  number  of  the current year as a decimal number, range 00 to 53, starting with the
 273 first Sunday as the first day of week 01. See also \f(CW%V\fR and \f(CW%W\fR.
 274 .ie n .IP "\fB\fB%V\fB\fR" 4
 275 .el .IP "\fB\f(CB%V\fB\fR" 4
 276 .IX Item "%V"
 277 The \s-1ISO\s0 8601:1988 week number of the current year as a decimal number, range 01 to  53,  where
 278 week  1 is the first week that has at least 4 days in the current year, and with Monday as the
 279 first day of the week. See also \f(CW%U\fR and \f(CW%W\fR.
 280 .ie n .IP "\fB\fB%w\fB\fR" 4
 281 .el .IP "\fB\f(CB%w\fB\fR" 4
 282 .IX Item "%w"
 283 The day of the week as a decimal, range 0 to 6, Sunday being 0.  See also \f(CW%u\fR.
 284 .ie n .IP "\fB\fB%W\fB\fR" 4
 285 .el .IP "\fB\f(CB%W\fB\fR" 4
 286 .IX Item "%W"
 287 The week number of the current year as a decimal number, range 00 to  53,  starting  with  the
 288 first Monday as the first day of week 01.
 289 .ie n .IP "\fB\fB%x\fB\fR" 4
 290 .el .IP "\fB\f(CB%x\fB\fR" 4
 291 .IX Item "%x"
 292 The preferred date representation for the current locale without the time.
 293 .ie n .IP "\fB\fB%X\fB\fR" 4
 294 .el .IP "\fB\f(CB%X\fB\fR" 4
 295 .IX Item "%X"
 296 The preferred time representation for the current locale without the date.
 297 .ie n .IP "\fB\fB%y\fB\fR" 4
 298 .el .IP "\fB\f(CB%y\fB\fR" 4
 299 .IX Item "%y"
 300 The year as a decimal number without a century (range 00 to 99).
 301 .ie n .IP "\fB\fB%Y\fB\fR" 4
 302 .el .IP "\fB\f(CB%Y\fB\fR" 4
 303 .IX Item "%Y"
 304 The year as a decimal number including the century.
 305 .ie n .IP "\fB\fB%Z\fB\fR" 4
 306 .el .IP "\fB\f(CB%Z\fB\fR" 4
 307 .IX Item "%Z"
 308 The time zone or name or abbreviation.
 309 .IP "\fB%%\fR" 4
 310 .IX Item "%%"
 311 A literal `%' character.
 312 .PP
 313 \fI\f(BI\s-1PRINT:\s0\fI\fIvname\fI\f(BI:\fI\fI\s-1CF\s0\fI\f(BI:\fI\fIformat\fI\fR
 314 .IX Subsection "PRINT:vname:CF:format"
 315 .PP
 316 \&\fIDeprecated. Use the new form of this command in new scripts.\fR
 317 The first form of this command is to be used with \fB\s-1CDEF\s0\fR \fIvname\fRs.
 318 .SS "\s-1GRAPH\s0"
 319 .IX Subsection "GRAPH"
 320 \fI\f(BI\s-1GPRINT\s0\fI\f(BI:\fI\fIvname\fI\f(BI:\fI\fIformat\fI\fR
 321 .IX Subsection "GPRINT:vname:format"
 322 .PP
 323 This is the same as \f(CW\*(C`PRINT\*(C'\fR, but printed inside the graph.
 324 .PP
 325 \fI\f(BI\s-1GPRINT\s0\fI\f(BI:\fI\fIvname\fI\f(BI:\fI\fI\s-1CF\s0\fI\f(BI:\fI\fIformat\fI\fR
 326 .IX Subsection "GPRINT:vname:CF:format"
 327 .PP
 328 \&\fIDeprecated. Use the new form of this command in new scripts.\fR
 329 This is the same as \f(CW\*(C`PRINT\*(C'\fR, but printed inside the graph.
 330 .PP
 331 \fI\f(BI\s-1COMMENT\s0\fI\f(BI:\fI\fItext\fI\fR
 332 .IX Subsection "COMMENT:text"
 333 .PP
 334 Text is printed literally in the legend section of the graph. Note that in
 335 RRDtool 1.2 you have to escape colons in \s-1COMMENT\s0 text in the same way you
 336 have to escape them in \fB*PRINT\fR commands by writing \fB'\e:'\fR.
 337 .PP
 338 \fI\f(BI\s-1VRULE\s0\fI\f(BI:\fI\fItime\fI\f(BI#\fI\fIcolor\fI[\f(BI:\fI\fIlegend\fI][\f(BI:dashes\fI[\f(BI=\fI\fIon_s\fI[,\fIoff_s\fI[,\fIon_s\fI,\fIoff_s\fI]...]][\f(BI:dash\-offset=\fI\fIoffset\fI]]\fR
 339 .IX Subsection "VRULE:time#color[:legend][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]"
 340 .PP
 341 Draw a vertical line at \fItime\fR.  Its color is composed from three
 342 hexadecimal numbers specifying the rgb color components (00 is off, \s-1FF\s0 is
 343 maximum) red, green and blue followed by an optional alpha. Optionally, a legend box and string is
 344 printed in the legend section. \fItime\fR may be a number or a variable
 345 from a \fB\s-1VDEF\s0\fR. It is an error to use \fIvname\fRs from \fB\s-1DEF\s0\fR or \fB\s-1CDEF\s0\fR here.
 346 Dashed lines can be drawn using the \fBdashes\fR modifier. See \fB\s-1LINE\s0\fR for more
 347 details.
 348 .PP
 349 \fI\f(BI\s-1HRULE\s0\fI\f(BI:\fI\fIvalue\fI\f(BI#\fI\fIcolor\fI[\f(BI:\fI\fIlegend\fI][\f(BI:dashes\fI[\f(BI=\fI\fIon_s\fI[,\fIoff_s\fI[,\fIon_s\fI,\fIoff_s\fI]...]][\f(BI:dash\-offset=\fI\fIoffset\fI]]\fR
 350 .IX Subsection "HRULE:value#color[:legend][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]"
 351 .PP
 352 Draw a horizontal line at \fIvalue\fR.  \s-1HRULE\s0 acts much like \s-1LINE\s0 except that
 353 will have no effect on the scale of the graph. If a \s-1HRULE\s0 is outside the
 354 graphing area it will just not be visible.
 355 .PP
 356 \fI\f(BI\s-1LINE\s0\fI[\fIwidth\fI]\f(BI:\fI\fIvalue\fI[\f(BI#\fI\fIcolor\fI][\f(BI:\fI[\fIlegend\fI][\f(BI:STACK\fI]][\f(BI:dashes\fI[\f(BI=\fI\fIon_s\fI[,\fIoff_s\fI[,\fIon_s\fI,\fIoff_s\fI]...]][\f(BI:dash\-offset=\fI\fIoffset\fI]]\fR
 357 .IX Subsection "LINE[width]:value[#color][:[legend][:STACK]][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]"
 358 .PP
 359 Draw a line of the specified width onto the graph. \fIwidth\fR can be a
 360 floating point number. If the color is not specified, the drawing is done
 361 \&'invisibly'. This is useful when stacking something else on top of this
 362 line. Also optional is the legend box and string which will be printed in
 363 the legend section if specified. The \fBvalue\fR can be generated by \fB\s-1DEF\s0\fR,
 364 \&\fB\s-1VDEF\s0\fR, and \fB\s-1CDEF\s0\fR.  If the optional \fB\s-1STACK\s0\fR modifier is used, this line
 365 is stacked on top of the previous element which can be a \fB\s-1LINE\s0\fR or an
 366 \&\fB\s-1AREA\s0\fR.
 367 .PP
 368 The \fBdashes\fR modifier enables dashed line style. Without any further options
 369 a symmetric dashed line with a segment length of 5 pixels will be drawn. The
 370 dash pattern can be changed if the \fBdashes=\fR parameter is followed by either
 371 one value or an even number (1, 2, 4, 6, ...) of positive values. Each value
 372 provides the length of alternate \fIon_s\fR and \fIoff_s\fR portions of the
 373 stroke. The \fBdash-offset\fR parameter specifies an \fIoffset\fR into the pattern
 374 at which the stroke begins.
 375 .PP
 376 When you do not specify a color, you cannot specify a legend.  Should
 377 you want to use \s-1STACK\s0, use the \*(L"LINEx:<value>::STACK\*(R" form.
 378 .PP
 379 \fI\f(BI\s-1AREA\s0\fI\f(BI:\fI\fIvalue\fI[\f(BI#\fI\fIcolor\fI][\f(BI:\fI[\fIlegend\fI][\f(BI:STACK\fI]]\fR
 380 .IX Subsection "AREA:value[#color][:[legend][:STACK]]"
 381 .PP
 382 See \fB\s-1LINE\s0\fR, however the area between the x\-axis and the line will
 383 be filled.
 384 .PP
 385 \fI\f(BI\s-1TICK\s0\fI\f(BI:\fI\fIvname\fI\f(BI#\fI\fIrrggbb\fI[\fIaa\fI][\f(BI:\fI\fIfraction\fI[\f(BI:\fI\fIlegend\fI]]\fR
 386 .IX Subsection "TICK:vname#rrggbb[aa][:fraction[:legend]]"
 387 .PP
 388 Plot a tick mark (a vertical line) for each value of \fIvname\fR that is
 389 non-zero and not *UNKNOWN*. The \fIfraction\fR argument specifies the length of
 390 the tick mark as a fraction of the y\-axis; the default value is 0.1 (10% of
 391 the axis). Note that the color specification is not optional. The \s-1TICK\s0 marks normally
 392 start at the lower edge of the graphing area. If the fraction is negative they start
 393 at the upper border of the graphing area.
 394 .PP
 395 \fI\f(BI\s-1SHIFT\s0\fI\f(BI:\fI\fIvname\fI\f(BI:\fI\fIoffset\fI\fR
 396 .IX Subsection "SHIFT:vname:offset"
 397 .PP
 398 Using this command \fBRRDtool\fR will graph the following elements
 399 with the specified offset.  For instance, you can specify an
 400 offset of (\ 7*24*60*60\ =\ )\ 604'800\ seconds to \*(L"look back\*(R" one
 401 week. Make sure to tell the viewer of your graph you did this ...
 402 As with the other graphing elements, you can specify a number or
 403 a variable here.
 404 .PP
 405 \fI\f(BI\s-1TEXTALIGN\s0\fI\f(BI:\fI{\f(BIleft\fI|\f(BIright\fI|\f(BIjustified\fI|\f(BIcenter\fI}\fR
 406 .IX Subsection "TEXTALIGN:{left|right|justified|center}"
 407 .PP
 408 Labels are placed below the graph. When they overflow to the left, they wrap
 409 to the next line. By default, lines are justified left and right. The
 410 \&\fB\s-1TEXTALIGN\s0\fR function lets you change this default. This is a command and
 411 not an option, so that you can change the default several times in your
 412 argument list.
 413 .PP
 414 \fI\f(BI\s-1STACK\s0\fI\f(BI:\fI\fIvname\fI\f(BI#\fI\fIcolor\fI[\f(BI:\fI\fIlegend\fI]\fR
 415 .IX Subsection "STACK:vname#color[:legend]"
 416 .PP
 417 \&\fIDeprecated.  Use the \f(BI\s-1STACK\s0\fI modifiers on the other commands instead!\fR
 418 .PP
 419 \&\fBSome notes on stacking\fR
 420 .PP
 421 When stacking, an element is not placed above the X\-axis but rather
 422 on top of the previous element.  There must be something to stack
 423 upon.
 424 .PP
 425 You can use an \fBinvisible\fR \s-1LINE\s0 or \s-1AREA\s0 to stacked upon.
 426 .PP
 427 An \fBunknown\fR value makes the entire stack unknown from that moment on.
 428 You don't know where to begin (the unknown value) and therefore do
 429 not know where to end.
 430 .PP
 431 If you want to make sure you will be displaying a certain variable,
 432 make sure never to stack upon the unknown value.  Use a \s-1CDEF\s0 instruction
 433 with \fB\s-1IF\s0\fR and \fB\s-1UN\s0\fR to do so.
 434 .SH "NOTES on legend arguments"
 435 .IX Header "NOTES on legend arguments"
 436 .SS "Escaping the colon"
 437 .IX Subsection "Escaping the colon"
 438 A colon ':' in a \fIlegend\fR argument will mark the end of the
 439 legend. To enter a ':' as part of a legend, the colon must be escaped
 440 with a backslash '\e:'.  Beware that many environments process
 441 backslashes themselves, so it may be necessary to write two
 442 backslashes in order to one being passed onto rrd_graph.
 443 .SS "String Formatting"
 444 .IX Subsection "String Formatting"
 445 The text printed below the actual graph can be formatted by appending special
 446 escape characters at the end of a text. When ever such a character occurs,
 447 all pending text is pushed onto the graph according to the character
 448 specified.
 449 .PP
 450 Valid markers are: \fB\ej\fR for justified, \fB\el\fR for left aligned, \fB\er\fR for
 451 right aligned, and \fB\ec\fR for centered. In the next section there is an
 452 example showing how to use centered formatting.
 453 .PP
 454 \&\fB\en\fR is a valid alias for \fB\el\fR since incomplete parsing in earlier
 455 versions of RRDtool lead to this behavior and a number of people has been using it.
 456 .PP
 457 Normally there are two space characters inserted between every two items
 458 printed into the graph. The space following a string can be suppressed by
 459 putting a \fB\eg\fR at the end of the string. The \fB\eg\fR also ignores any space
 460 inside the string if it is at the very end of the string. This can be used
 461 in connection with \fB\f(CB%s\fB\fR to suppress empty unit strings.
 462 .PP
 463 .Vb 1
 464 \& GPRINT:a:MAX:%lf%s\eg
 465 .Ve
 466 .PP
 467 A special case is \s-1COMMENT:\s0\fB\es\fR which inserts some additional vertical space
 468 before placing the next row of legends.
 469 .PP
 470 If you want to have left and right aligned legends on the same line use \s-1COMMENT:\s0\fB\eu\fR
 471 to go one line back like this:
 472 .PP
 473 .Vb 3
 474 \& COMMENT:left\el
 475 \& COMMENT:\eu
 476 \& COMMENT:right\er
 477 .Ve
 478 .PP
 479 When using a proportional font in your graph, the tab
 480 characters or the sequence \fB\et\fR will line-up legend elements. Note that
 481 the tabs inserted are relative to the start of the current legend
 482 element!
 483 .PP
 484 Since RRDtool 1.3 is using Pango for rending text, you can use Pango markup.
 485 Pango uses the xml \fBspan\fR tags for inline formatting instructions.:
 486 .PP
 487 A simple example of a marked-up string might be:
 488 .PP
 489 .Vb 1
 490 \& <span foreground="blue" size="x\-large">Blue text</span> is <i>cool</i>!
 491 .Ve
 492 .PP
 493 The complete list of attributes for the span tag (taken from the pango documentation):
 494 .IP "\fBfont_desc\fR" 4
 495 .IX Item "font_desc"
 496 A font description string, such as \*(L"Sans Italic 12\*(R"; note that any other span attributes will override this description. So if you have \*(L"Sans Italic\*(R" and also a style=\*(L"normal\*(R" attribute, you will get Sans normal, not italic.
 497 .IP "\fBfont_family\fR" 4
 498 .IX Item "font_family"
 499 A font family name
 500 .IP "\fBface\fR" 4
 501 .IX Item "face"
 502 Synonym for font_family
 503 .IP "\fBsize\fR" 4
 504 .IX Item "size"
 505 Font size in 1024ths of a point, or one of the absolute sizes 'xx\-small', 'x\-small', 'small', 'medium', 'large', 'x\-large', 'xx\-large', or one of the relative sizes 'smaller' or 'larger'. If you want to specify a absolute size, it's usually easier to take advantage of the ability to specify a partial font description using 'font_desc'; you can use font_desc='12.5' rather than size='12800'.
 506 .IP "\fBstyle\fR" 4
 507 .IX Item "style"
 508 One of 'normal', 'oblique', 'italic'
 509 .IP "\fBweight\fR" 4
 510 .IX Item "weight"
 511 One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight
 512 .IP "\fBvariant\fR" 4
 513 .IX Item "variant"
 514 \&'normal' or 'smallcaps'
 515 .IP "\fBstretch\fR" 4
 516 .IX Item "stretch"
 517 One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'
 518 .IP "\fBforeground\fR" 4
 519 .IX Item "foreground"
 520 An \s-1RGB\s0 color specification such as '#00FF00' or a color name such as 'red'
 521 .IP "\fBbackground\fR" 4
 522 .IX Item "background"
 523 An \s-1RGB\s0 color specification such as '#00FF00' or a color name such as 'red'
 524 .IP "\fBunderline\fR" 4
 525 .IX Item "underline"
 526 One of 'none', 'single', 'double', 'low', 'error'
 527 .IP "\fBunderline_color\fR" 4
 528 .IX Item "underline_color"
 529 The color of underlines; an \s-1RGB\s0 color specification such as '#00FF00' or a color name such as 'red'
 530 .IP "\fBrise\fR" 4
 531 .IX Item "rise"
 532 Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
 533 .IP "\fBstrikethrough\fR" 4
 534 .IX Item "strikethrough"
 535 \&'true' or 'false' whether to strike through the text
 536 .IP "\fBstrikethrough_color\fR" 4
 537 .IX Item "strikethrough_color"
 538 The color of crossed out lines; an \s-1RGB\s0 color specification such as '#00FF00' or a color name such as 'red'
 539 .IP "\fBfallback\fR" 4
 540 .IX Item "fallback"
 541 \&'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
 542 .IP "\fBlang\fR" 4
 543 .IX Item "lang"
 544 A language code, indicating the text language
 545 .IP "\fBletter_spacing\fR" 4
 546 .IX Item "letter_spacing"
 547 Inter-letter spacing in 1024ths of a point.
 548 .IP "\fBgravity\fR" 4
 549 .IX Item "gravity"
 550 One of 'south', 'east', 'north', 'west', 'auto'.
 551 .IP "\fBgravity_hint\fR" 4
 552 .IX Item "gravity_hint"
 553 One of 'natural', 'strong', 'line'.
 554 .PP
 555 To save you some typing, there are also some shortcuts:
 556 .IP "\fBb\fR" 4
 557 .IX Item "b"
 558 Bold
 559 .IP "\fBbig\fR" 4
 560 .IX Item "big"
 561 Makes font relatively larger, equivalent to <span size=\*(L"larger\*(R">
 562 .IP "\fBi\fR" 4
 563 .IX Item "i"
 564 Italic
 565 .IP "\fBs\fR" 4
 566 .IX Item "s"
 567 Strike through
 568 .IP "\fBsub\fR" 4
 569 .IX Item "sub"
 570 Subscript
 571 .IP "\fBsup\fR" 4
 572 .IX Item "sup"
 573 Superscript
 574 .IP "\fBsmall\fR" 4
 575 .IX Item "small"
 576 Makes font relatively smaller, equivalent to <span size=\*(L"smaller\*(R">
 577 .IP "\fBtt\fR" 4
 578 .IX Item "tt"
 579 Monospace font
 580 .IP "\fBu\fR" 4
 581 .IX Item "u"
 582 Underline
 583 .SH "SEE ALSO"
 584 .IX Header "SEE ALSO"
 585 rrdgraph gives an overview of how \fBrrdtool graph\fR works.
 586 rrdgraph_data describes \fB\s-1DEF\s0\fR,\fB\s-1CDEF\s0\fR and \fB\s-1VDEF\s0\fR in detail.
 587 rrdgraph_rpn describes the \fB\s-1RPN\s0\fR language used in the \fB?DEF\fR statements.
 588 rrdgraph_graph page describes all of the graph and print functions.
 589 .PP
 590 Make sure to read rrdgraph_examples for tips&tricks.
 591 .SH "AUTHOR"
 592 .IX Header "AUTHOR"
 593 Program by Tobias Oetiker <tobi@oetiker.ch>
 594 .PP
 595 This manual page by Alex van den Bogaerdt <alex@vandenbogaerdt.nl>
 596 with corrections and/or additions by several people