1 <?xml version="1.0" ?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml">
4 <head>
5 <title>RRDs</title>
6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
7 <link rev="made" href="mailto:root@localhost" />
8 </head>
10 <body style="background-color: white">
13 <!-- INDEX BEGIN -->
14 <div name="index">
15 <p><a name="__index__"></a></p>
16 <!--
18 <ul>
20 <li><a href="#name">NAME</a></li>
21 <li><a href="#synopsis">SYNOPSIS</a></li>
22 <li><a href="#description">DESCRIPTION</a></li>
23 <ul>
25 <li><a href="#calling_sequence">Calling Sequence</a></li>
26 <li><a href="#error_handling">Error Handling</a></li>
27 <li><a href="#return_values">Return Values</a></li>
28 </ul>
30 <li><a href="#note">NOTE</a></li>
31 <li><a href="#author">AUTHOR</a></li>
32 </ul>
34 -->
37 </div>
38 <!-- INDEX END -->
40 <p>
41 </p>
42 <h1><a name="name">NAME</a></h1>
43 <p>RRDs - Access RRDtool as a shared module</p>
44 <p>
45 </p>
46 <hr />
47 <h1><a name="synopsis">SYNOPSIS</a></h1>
48 <pre>
49 use RRDs;
50 RRDs::error
51 RRDs::last ...
52 RRDs::info ...
53 RRDs::create ...
54 RRDs::update ...
55 RRDs::updatev ...
56 RRDs::graph ...
57 RRDs::fetch ...
58 RRDs::tune ...
59 RRDs::times(start, end)
60 RRDs::dump ...
61 RRDs::restore ...</pre>
62 <p>
63 </p>
64 <hr />
65 <h1><a name="description">DESCRIPTION</a></h1>
66 <p>
67 </p>
68 <h2><a name="calling_sequence">Calling Sequence</a></h2>
69 <p>This module accesses RRDtool functionality directly from within Perl. The
70 arguments to the functions listed in the SYNOPSIS are explained in the regular
71 RRDtool documentation. The command line call</p>
72 <pre>
73 rrdtool update mydemo.rrd --template in:out N:12:13</pre>
74 <p>gets turned into</p>
75 <pre>
76 RRDs::update ("mydemo.rrd", "--template", "in:out", "N:12:13");</pre>
77 <p>Note that</p>
78 <pre>
79 --template=in:out</pre>
80 <p>is also valid.</p>
81 <p>The RRDs::times function takes two parameters: a "start" and "end" time.
82 These should be specified in the <strong>AT-STYLE TIME SPECIFICATION</strong> format
83 used by RRDtool. See the <strong>rrdfetch</strong> documentation for a detailed
84 explanation on how to specify time.</p>
85 <p>
86 </p>
87 <h2><a name="error_handling">Error Handling</a></h2>
88 <p>The RRD functions will not abort your program even when they can not make
89 sense out of the arguments you fed them.</p>
90 <p>The function RRDs::error should be called to get the error status
91 after each function call. If RRDs::error does not return anything
92 then the previous function has completed its task successfully.</p>
93 <pre>
94 use RRDs;
95 RRDs::update ("mydemo.rrd","N:12:13");
96 my $ERR=RRDs::error;
97 die "ERROR while updating mydemo.rrd: $ERR\n" if $ERR;</pre>
98 <p>
99 </p>
100 <h2><a name="return_values">Return Values</a></h2>
101 <p>The functions RRDs::last, RRDs::graph, RRDs::info, RRDs::fetch and RRDs::times
102 return their findings.</p>
103 <p><strong>RRDs::last</strong> returns a single INTEGER representing the last update time.</p>
104 <pre>
105 $lastupdate = RRDs::last ...</pre>
106 <p><strong>RRDs::graph</strong> returns an ARRAY containing the x-size and y-size of the
107 created image and a pointer to an array with the results of the PRINT arguments.</p>
108 <pre>
109 ($result_arr,$xsize,$ysize) = RRDs::graph ...
110 print "Imagesize: ${xsize}x${ysize}\n";
111 print "Averages: ", (join ", ", @$averages);</pre>
112 <p><strong>RRDs::info</strong> returns a pointer to a hash. The keys of the hash
113 represent the property names of the RRD and the values of the hash are
114 the values of the properties.</p>
115 <pre>
116 $hash = RRDs::info "example.rrd";
117 foreach my $key (keys %$hash){
118 print "$key = $$hash{$key}\n";
119 }</pre>
120 <p><strong>RRDs::graphv</strong> takes the same parameters as <strong>RRDs::graph</strong> but it returns a
121 pointer to hash. The hash returned contains meta information about the
122 graph. Like its size as well as the position of the graph area on the image.
123 When calling with and empty filename than the contents of the graph will be
124 returned in the hash as well (key 'image').</p>
125 <p><strong>RRDs::updatev</strong> also returns a pointer to hash. The keys of the hash
126 are concatenated strings of a timestamp, RRA index, and data source name for
127 each consolidated data point (CDP) written to disk as a result of the
128 current update call. The hash values are CDP values.</p>
129 <p><strong>RRDs::fetch</strong> is the most complex of
130 the pack regarding return values. There are 4 values. Two normal
131 integers, a pointer to an array and a pointer to a array of pointers.</p>
132 <pre>
133 my ($start,$step,$names,$data) = RRDs::fetch ...
134 print "Start: ", scalar localtime($start), " ($start)\n";
135 print "Step size: $step seconds\n";
136 print "DS names: ", join (", ", @$names)."\n";
137 print "Data points: ", $#$data + 1, "\n";
138 print "Data:\n";
139 for my $line (@$data) {
140 print " ", scalar localtime($start), " ($start) ";
141 $start += $step;
142 for my $val (@$line) {
143 printf "%12.1f ", $val;
144 }
145 print "\n";
146 }</pre>
147 <p><strong>RRDs::times</strong> returns two integers which are the number of seconds since
148 epoch (1970-01-01) for the supplied "start" and "end" arguments, respectively.</p>
149 <p>See the examples directory for more ways to use this extension.</p>
150 <p>
151 </p>
152 <hr />
153 <h1><a name="note">NOTE</a></h1>
154 <p>If you are manipulating the TZ variable you should also call the POSIX
155 function <em>tzset(3)</em> to initialize all internal state of the library for properly
156 operating in the timezone of your choice.</p>
157 <pre>
158 use POSIX qw(tzset);
159 $ENV{TZ} = 'CET';
160 POSIX::tzset();</pre>
161 <p>
162 </p>
163 <hr />
164 <h1><a name="author">AUTHOR</a></h1>
165 <p>Tobias Oetiker <<a href="mailto:tobi@oetiker.ch">tobi@oetiker.ch</a>></p>
167 </body>
169 </html>