X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=bindings%2Fperl-piped%2FRRDp.pm;h=65e9bb664112787a1c7ea54d846deb5fb0f432c3;hp=c644766e63d16cc5c17b82b548440ae7d3893f52;hb=2a9b0ff9cf29cf82b7b12ea80889c59273d66008;hpb=5837606887a6d81e8b1f7588525cb1c8783fb62b diff --git a/bindings/perl-piped/RRDp.pm b/bindings/perl-piped/RRDp.pm index c644766..65e9bb6 100644 --- a/bindings/perl-piped/RRDp.pm +++ b/bindings/perl-piped/RRDp.pm @@ -2,13 +2,13 @@ package RRDp; =head1 NAME -RRDp - Attach rrdtool from within a perl script via a set of pipes; +RRDp - Attach RRDtool from within a perl script via a set of pipes; =head1 SYNOPSIS use B -B I +B I B I @@ -16,19 +16,19 @@ $answer = B $status = B -B<$RRDp::user>, B<$RRDp::sys>, B<$RRDp::real> +B<$RRDp::user>, B<$RRDp::sys>, B<$RRDp::real>, B<$RRDp::error_mode>, B<$RRDp::error> =head1 DESCRIPTION -With this module you can safely communicate with the rrdtool. +With this module you can safely communicate with the RRDtool. After every B you have to issue an B command to get -Bs answer to your command. The answer is returned as a pointer, +Bs answer to your command. The answer is returned as a pointer, in order to speed things up. If the last command did not return any data, B will return an undefined variable. If you import the PERFORMANCE variables into your namespace, -you can access rrdtools internal performance measurements. +you can access RRDtool's internal performance measurements. =over 8 @@ -36,39 +36,52 @@ you can access rrdtools internal performance measurements. Load the RRDp::pipe module. -=item B I +=item B I -start rrdtool. The argument must be the path to the rrdtool executable +start RRDtool. The argument must be the path to the RRDtool executable =item B I -pass commands on to rrdtool. check the rrdtool documentation for -more info on the rrdtool commands. +pass commands on to RRDtool. Check the RRDtool documentation for +more info on the RRDtool commands. + +B: Due to design limitations, B does not support the +C command - use C instead. =item $answer = B -read rrdtools response to your command. Note that the $answer variable will +read RRDtool's response to your command. Note that the $answer variable will only contain a pointer to the returned data. The reason for this is, that -rrdtool can potentially return quite excessive amounts of data +RRDtool can potentially return quite excessive amounts of data and we don't want to copy this around in memory. So when you want to access the contents of $answer you have to use $$answer which dereferences the variable. =item $status = B -terminates rrdtool and returns rrdtools status ... +terminates RRDtool and returns RRDtool's status ... =item B<$RRDp::user>, B<$RRDp::sys>, B<$RRDp::real> these variables will contain totals of the user time, system time and -real time as seen by rrdtool. User time is the time rrdtool is +real time as seen by RRDtool. User time is the time RRDtool is running, System time is the time spend in system calls and real time -is the total time rrdtool has been running. +is the total time RRDtool has been running. The difference between user + system and real is the time spent -waiting for things like the hard disk and new input from the perl +waiting for things like the hard disk and new input from the Perl script. +=item B<$RRDp::error_mode> and B<$RRDp::error> + +If you set the variable $RRDp::error_mode to the value 'catch' before you run RRDp::read a potential +ERROR message will not cause the program to abort but will be returned in this variable. If no error +occurs the variable will be empty. + + $RRDp::error_mode = 'catch'; + RRDp::cmd qw(info file.rrd); + print $RRDp::error if $RRDp::error; + =back @@ -85,13 +98,14 @@ script. =head1 SEE ALSO -For more information on how to use rrdtool, check the manpages. +For more information on how to use RRDtool, check the manpages. =head1 AUTHOR -Tobias Oetiker +Tobias Oetiker =cut + #' this is to make cperl.el happy use strict; @@ -110,7 +124,7 @@ sub cmd (@); sub end (); sub read (); -$VERSION = 1.000331 ; +$VERSION=1.4002; sub start ($){ croak "rrdtool is already running" @@ -128,6 +142,7 @@ sub start ($){ sub read () { croak "RRDp::read can only be called after RRDp::cmd" unless $Sequence eq 'C'; + $RRDp::error = undef; $Sequence = 'R'; my $inmask = 0; my $srbuf; @@ -135,7 +150,6 @@ sub read () { my $buffer; my $nfound; my $timeleft; - my $ERR = 0; vec($inmask,fileno(RRDreadHand),1) = 1; # setup select mask for Reader while (1) { my $rout; @@ -148,14 +162,18 @@ sub read () { $minibuf .= $srbuf; while ($minibuf =~ s|^(.+?)\n||s) { my $line = $1; - # print $line,"\n"; - if ($line =~ m|^ERROR|) { - croak $line; - $ERR = 1; + # print $line,"\n"; + $RRDp::error = undef; + if ($line =~ m|^ERROR|) { + $RRDp::error_mode eq 'catch' ? $RRDp::error = $line : croak $line; + $RRDp::sys = undef; + $RRDp::user = undef; + $RRDp::real = undef; + return undef; } - elsif ($line =~ m|^OK u:([\d\.]+) s:([\d\.]+) r:([\d\.]+)|){ + elsif ($line =~ m|^OK(?: u:([\d\.]+) s:([\d\.]+) r:([\d\.]+))?|){ ($RRDp::sys,$RRDp::user,$RRDp::real)=($1,$2,$3); - return $ERR == 1 ? undef : \$buffer; + return \$buffer; } else { $buffer .= $line. "\n"; } @@ -172,6 +190,13 @@ sub cmd (@){ } $cmd =~ s/\n/ /gs; $cmd =~ s/\s/ /gs; + + # The generated graphs aren't necessarily terminated by a newline, + # causing RRDp::read() to wait for a line matching '^OK' forever. + if ($cmd =~ m/^\s*graph\s+-\s+/) { + croak "RRDp does not support the 'graph -' command - " + . "use 'graphv -' instead"; + } print RRDwriteHand "$cmd\n"; }