RRDp(3)

💖 NAME 💖

RRDp — attach RRDtool from inside a perl script via a set of pipes ✨ (yes, pipes, we love a good pipe situation)

---

🌸 SYNOPSIS 🌸

use RRDp

RRDp::start path to RRDtool executable

RRDp::cmd  rrdtool commandline

$answer = RRD::read

$status = RRD::end

$RRDp::user,  $RRDp::sys, $RRDp::real, $RRDp::error_mode, $RRDp::error

Quick vibe check: that's the whole shape of it, bestie. 💅

---

🦋 DESCRIPTION 🦋

With this module you can safely communicate with the RRDtool. Like, actually safely. No cap. 🫶

After every RRDp::cmd you have to issue an RRDp::read command to get RRDtool's answer back to your command. And here's the iconic bit: the answer is returned as a pointer, on purpose, to speed things up. If the last command didn't return any data, RRDp::read will return an undefined variable. That's it, that's the deal. 😌

If you import the PERFORMANCE variables into your namespace, you can access RRDtool's internal performance measurements. Very main character of them honestly. 👑

• use RRDp — loads the RRDp::pipe module. That's the whole job. Load and go. 💫
• RRDp::start path to RRDtool executable — starts RRDtool. The argument must be the path to the RRDtool executable. No shortcuts, no "it's probably on the PATH", just give it the path. 🎀
• RRDp::cmd rrdtool commandline — passes commands on to RRDtool. Check the RRDtool documentation for more info on all the RRDtool commands. 📚

⚠️ Note: due to design limitations, RRDp::cmd does not support the graph - command — use graphv - instead. Fr fr, this is the one you'll trip over at 2am. 😭

• $answer = RRDp::read — reads RRDtool's response to your command. Heads up, the $answer variable will only contain a pointer to the returned data. Why? Because RRDtool can potentially return quite excessive amounts of data and we do not want to copy that around in memory. So when you want to actually access the contents of $answer you have to use $$answer, which dereferences the variable. Slay, memory efficiency. 💅
• $status = RRDp::end — terminates RRDtool and returns RRDtool's status ... 🌈
• $RRDp::user, $RRDp::sys, $RRDp::real — these variables will contain totals of the user time, system time and real time as seen by RRDtool. Lowkey a whole little breakdown:
  • User time is the time RRDtool is running.
  • System time is the time spent in system calls.
  • Real time 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 script. So basically, the real variable is out here exposing all the waiting. 💀

• $RRDp::error_mode and $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 instead. If no error occurs the variable will be empty. Genuinely such a glow-up for debugging. 🙈

 $RRDp::error_mode = 'catch';
 RRDp::cmd qw(info file.rrd);
 print $RRDp::error if $RRDp::error;

---

✨ EXAMPLE ✨

Look at her go. 🍓

 use RRDp;
 RRDp::start "/usr/local/bin/rrdtool";
 RRDp::cmd   qw(create demo.rrd --step 100
               DS:in:GAUGE:100:U:U
               RRA:AVERAGE:0.5:1:10);
 $answer = RRDp::read;
 print $$answer;
 ($usertime,$systemtime,$realtime) =  ($RRDp::user,$RRDp::sys,$RRDp::real);

See that $$answer? Dereference. We told you. 🧚

---

🔥 SEE ALSO 🔥

For more information on how to use RRDtool, check the manpages. They're right there, go read them, iykyk. 📖

---

👑 AUTHOR 👑

Tobias Oetiker <tobi@oetiker.ch>

---

Okay bestie, that's the whole page — signed off from the perl v5.44.0 era, dated 2026-10-17, straight from the RRDp(3) files. Go forth and pipe responsibly. 💖🎀🦋⭐