1RRDs(3)               User Contributed Perl Documentation              RRDs(3)
2
3
4

NAME

6       RRDs - Access RRDtool as a shared module
7

SYNOPSIS

9         use RRDs;
10         RRDs::error
11         RRDs::last ...
12         RRDs::info ...
13         RRDs::create ...
14         RRDs::update ...
15         RRDs::updatev ...
16         RRDs::graph ...
17         RRDs::fetch ...
18         RRDs::tune ...
19         RRDs::times(start, end)
20         RRDs::dump ...
21         RRDs::restore ...
22

DESCRIPTION

24       Calling Sequence
25
26       This module accesses RRDtool functionality directly from within perl.
27       The arguments to the functions listed in the SYNOPSIS are explained in
28       the regular RRDtool documentation. The commandline call
29
30        rrdtool update mydemo.rrd --template in:out N:12:13
31
32       gets turned into
33
34        RRDs::update ("mydemo.rrd", "--template", "in:out", "N:12:13");
35
36       Note that
37
38        --template=in:out
39
40       is also valid.
41
42       The RRDs::times function takes two parameters:  a "start" and "end"
43       time.  These should be specified in the AT-STYLE TIME SPECIFICATION
44       format used by RRDtool.  See the rrdfetch documentation for a detailed
45       explanation on how to specify time.
46
47       Error Handling
48
49       The RRD functions will not abort your program even when they can not
50       make sense out of the arguments you fed them.
51
52       The function RRDs::error should be called to get the error status after
53       each function call. If RRDs::error does not return anything then the
54       previous function has completed its task successfully.
55
56        use RRDs;
57        RRDs::update ("mydemo.rrd","N:12:13");
58        my $ERR=RRDs::error;
59        die "ERROR while updating mydemo.rrd: $ERR\n" if $ERR;
60
61       Return Values
62
63       The functions RRDs::last, RRDs::graph, RRDs::info, RRDs::fetch and
64       RRDs::times return their findings.
65
66       RRDs::last returns a single INTEGER representing the last update time.
67
68        $lastupdate = RRDs::last ...
69
70       RRDs::graph returns an pointer to an ARRAY containing the x-size and
71       y-size of the created image and results of the PRINT arguments.
72
73        ($averages,$xsize,$ysize) = RRDs::graph ...
74        print "Imagesize: ${xsize}x${ysize}\n";
75        print "Averages: ", (join ", ", @$averages);
76
77       RRDs::info returns a pointer to a hash. The keys of the hash represent
78       the property names of the RRD and the values of the hash are the values
79       of the properties.
80
81        $hash = RRDs::info "example.rrd";
82        foreach my $key (keys %$hash){
83          print "$key = $$hash{$key}\n";
84        }
85
86       RRDs::updatev also returns a pointer to hash. The keys of the hash are
87       concatenated strings of a timestamp, RRA index, and data source name
88       for each consolidated data point (CDP) written to disk as a result of
89       the current update call. The hash values are CDP values.
90
91       RRDs::fetch is the most complex of the pack regarding return values.
92       There are 4 values. Two normal integers, a pointer to an array and a
93       pointer to a array of pointers.
94
95         my ($start,$step,$names,$data) = RRDs::fetch ...
96         print "Start:       ", scalar localtime($start), " ($start)\n";
97         print "Step size:   $step seconds\n";
98         print "DS names:    ", join (", ", @$names)."\n";
99         print "Data points: ", $#$data + 1, "\n";
100         print "Data:\n";
101         foreach my $line (@$data) {
102           print "  ", scalar localtime($start), " ($start) ";
103           $start += $step;
104           foreach my $val (@$line) {
105             printf "%12.1f ", $val;
106           }
107           print "\n";
108         }
109
110       RRDs::times returns two integers which are the number of seconds since
111       epoch (1970-01-01) for the supplied "start" and "end" arguments,
112       respectively.
113
114       See the examples directory for more ways to use this extension.
115

NOTE

117       If you are manipulating the TZ variable you should also call the posixs
118       function tzset to initialize all internal state of the library for
119       properly operating in the timezone of your choice.
120
121        use POSIX qw(tzset);
122        $ENV{TZ} = 'CET';
123        POSIX::tzset();
124

AUTHOR

126       Tobias Oetiker <tobi@oetiker.ch>
127
128
129
130perl v5.8.8                       2008-02-17                           RRDs(3)
Impressum